IntelFrameworkPkg/Library/FrameworkHiiLib/HiiLib.c

   1 /** @file
   2   HII Library implementation that uses DXE protocols and services.
   3
   4   Copyright (c) 2006, Intel Corporation<BR>
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15
  16 #include <FrameworkDxe.h>
  17
  18 #include <Protocol/FrameworkHii.h>
  19
  20 #include <Library/FrameworkHiiLib.h>
  21 #include <Library/DebugLib.h>
  22 #include <Library/MemoryAllocationLib.h>
  23 #include <Library/UefiBootServicesTableLib.h>
  24
  25 EFI_HII_PROTOCOL *mHii = NULL;
  26
  27 /**
  28   Library constustor function for HiiLib library instance locate the
  29   gEfiHiiProtocolGuid firstly, the other interface in this library
  30   instance will dependent on the protocol of gEfiHiiProtocolGuid.
  31   So the depex of gEfiHiiProtocolGuid is required for this library
  32   instance.
  33   If protocol of gEfiHiiProtocolGuid is not installed, then ASSERT().
  34
  35   @param  ImageHandle  The image handle of driver module who use this library instance.
  36   @param  SystemTable  Pointer to the EFI System Table.
  37
  38   @retval EFI_SUCCESS  library constuctor always success.
  39 **/
  40 EFI_STATUS
  41 EFIAPI
  42 FrameworkHiiLibConstructor (
  43   IN     EFI_HANDLE                 ImageHandle,
  44   IN     EFI_SYSTEM_TABLE           *SystemTable
  45   )
  46 {
  47   EFI_STATUS                        Status;
  48
  49   Status = gBS->LocateProtocol (
  50                  &gEfiHiiProtocolGuid,
  51                  NULL,
  52                  (VOID **) &mHii
  53                  );
  54   ASSERT_EFI_ERROR (Status);
  55   ASSERT (mHii != NULL);
  56
  57   return EFI_SUCCESS;
  58 }
  59
  60 /**
  61   This function is internal function that prepare and create
  62   HII packages with given number and package's guid.
  63   It is invoked by HiiAddPackages() and PreparePackages() interface.
  64   If the parameter of package's number is 0, then ASSERT().
  65
  66   @param NumberOfPackages  Given number of package item in a HII package list.
  67   @param Guid              Given GUID of a HII package list.
  68   @param Marker            Package's content list.
  69
  70   @return                  pointer to new created HII package list.
  71 **/
  72 EFI_HII_PACKAGES *
  73 InternalPreparePackages (
  74   IN     UINTN                      NumberOfPackages,
  75   IN     CONST EFI_GUID             *Guid OPTIONAL,
  76   IN     VA_LIST                    Marker
  77   )
  78 {
  79   EFI_HII_PACKAGES                  *HiiPackages;
  80   VOID                              **Package;
  81   UINTN                             Index;
  82
  83   ASSERT (NumberOfPackages > 0);
  84
  85   HiiPackages = AllocateZeroPool (sizeof (EFI_HII_PACKAGES) + NumberOfPackages * sizeof (VOID *));
  86   ASSERT (HiiPackages != NULL);
  87
  88   HiiPackages->GuidId           = (EFI_GUID *) Guid;
  89   HiiPackages->NumberOfPackages = NumberOfPackages;
  90   Package                       = (VOID **) (((UINT8 *) HiiPackages) + sizeof (EFI_HII_PACKAGES));
  91
  92   for (Index = 0; Index < NumberOfPackages; Index++) {
  93     *Package = VA_ARG (Marker, VOID *);
  94     Package++;
  95   }
  96
  97   return HiiPackages;
  98 }
  99
 100 /**
 101   This function allocates pool for an EFI_HII_PACKAGES structure
 102   with enough space for the variable argument list of package pointers.
 103   The allocated structure is initialized using NumberOfPackages, Guid,
 104   and the variable length argument list of package pointers.
 105
 106   @param  NumberOfPackages  The number of HII packages to prepare.
 107   @param  Guid              Package GUID.
 108   @param  ...               The variable argument list of package pointers.
 109
 110   @return                   The allocated and initialized packages.
 111 **/
 112 EFI_HII_PACKAGES *
 113 EFIAPI
 114 PreparePackages (
 115   IN     UINTN                      NumberOfPackages,
 116   IN     CONST EFI_GUID             *Guid OPTIONAL,
 117   ...
 118   )
 119 {
 120   VA_LIST                           Args;
 121
 122   VA_START (Args, Guid);
 123   return InternalPreparePackages (NumberOfPackages, Guid, Args);
 124 }
 125
 126
 127 /**
 128   This function allocates pool for an EFI_HII_PACKAGE_LIST structure
 129   with additional space that is big enough to host all packages described by the variable
 130   argument list of package pointers.  The allocated structure is initialized using NumberOfPackages,
 131   GuidId,  and the variable length argument list of package pointers.
 132
 133   Then, EFI_HII_PACKAGE_LIST will be register to the default System HII Database. The
 134   Handle to the newly registered Package List is returned throught HiiHandle.
 135
 136   @param  NumberOfPackages    The number of HII packages to register.
 137   @param  GuidId              Package List GUID ID.
 138   @param  DriverHandle        The pointer of driver handle
 139   @param  HiiHandle           The ID used to retrieve the Package List later.
 140   @param  ...                 The variable argument list describing all HII Package.
 141
 142   @return                     The allocated and initialized packages.
 143 **/
 144 EFI_STATUS
 145 EFIAPI
 146 HiiLibAddPackages (
 147   IN     UINTN                      NumberOfPackages,
 148   IN     CONST EFI_GUID             *GuidId,
 149   IN     EFI_HANDLE                 DriverHandle, OPTIONAL
 150      OUT EFI_HII_HANDLE             *HiiHandle,
 151   ...
 152   )
 153 {
 154   VA_LIST                           Args;
 155   EFI_HII_PACKAGES                  *FrameworkHiiPacages;
 156   FRAMEWORK_EFI_HII_HANDLE          FrameworkHiiHandle;
 157   EFI_STATUS                        Status;
 158
 159   VA_START (Args, HiiHandle);
 160
 161   FrameworkHiiPacages = InternalPreparePackages (NumberOfPackages, GuidId, Args);
 162   Status = mHii->NewPack (mHii, FrameworkHiiPacages, &FrameworkHiiHandle);
 163   if (HiiHandle != NULL) {
 164     if (EFI_ERROR (Status)) {
 165       *HiiHandle = NULL;
 166     } else {
 167       *HiiHandle = (EFI_HII_HANDLE) (UINTN) FrameworkHiiHandle;
 168     }
 169   }
 170
 171   FreePool (FrameworkHiiPacages);
 172
 173   return Status;
 174 }
 175
 176 /**
 177   Removes a package list from the default HII database.
 178
 179   If HiiHandle is NULL, then ASSERT.
 180   If HiiHandle is not a valid EFI_HII_HANDLE in the default HII database, then ASSERT.
 181
 182   @param  HiiHandle      The handle that was previously registered to the data base that is requested for removal.
 183
 184   @return VOID
 185 **/
 186 VOID
 187 EFIAPI
 188 HiiLibRemovePackages (
 189   IN     EFI_HII_HANDLE             HiiHandle
 190   )
 191 {
 192   EFI_STATUS                        Status;
 193
 194   Status = mHii->RemovePack (mHii, (FRAMEWORK_EFI_HII_HANDLE) (UINTN) HiiHandle);
 195   ASSERT_EFI_ERROR (Status);
 196 }
 197
 198 /**
 199   This function adds the string into String Package of each language.
 200
 201   @param  PackageList            Handle of the package list where this string will
 202                                  be added.
 203   @param  StringId               On return, contains the new strings id, which is
 204                                  unique within PackageList.
 205   @param  String                 Points to the new null-terminated string.
 206
 207   @retval EFI_SUCCESS            The new string was added successfully.
 208   @retval EFI_NOT_FOUND          The specified PackageList could not be found in
 209                                  database.
 210   @retval EFI_OUT_OF_RESOURCES   Could not add the string due to lack of resources.
 211   @retval EFI_INVALID_PARAMETER  String is NULL or StringId is NULL is NULL.
 212
 213 **/
 214 EFI_STATUS
 215 EFIAPI
 216 HiiLibNewString (
 217   IN     EFI_HII_HANDLE             PackageList,
 218      OUT EFI_STRING_ID              *StringId,
 219   IN     CONST EFI_STRING           String
 220   )
 221 {
 222   FRAMEWORK_EFI_HII_HANDLE          FrameworkHiiHandle;
 223   EFI_STATUS                        Status;
 224
 225   FrameworkHiiHandle = (FRAMEWORK_EFI_HII_HANDLE) (UINTN) PackageList;
 226   Status = mHii->NewString (
 227                    mHii,
 228                    NULL,
 229                    FrameworkHiiHandle,
 230                    StringId,
 231                    String
 232                    );
 233
 234   return Status;
 235 }
 236
 237 /**
 238   Get the string given the StringId and String package Producer's Guid. The caller
 239   is responsible to free the *String.
 240
 241   If PackageList with the matching ProducerGuid is not found, then ASSERT.
 242   If PackageList with the matching ProducerGuid is found but no String is
 243   specified by StringId is found, then ASSERT.
 244
 245   @param  ProducerGuid           The Guid of String package list.
 246   @param  StringId               The String ID.
 247   @param  String                 The output string.
 248
 249   @retval EFI_SUCCESS            Operation is successful.
 250   @retval EFI_OUT_OF_RESOURCES   There is not enought memory in the system.
 251 **/
 252 EFI_STATUS
 253 EFIAPI
 254 HiiLibGetStringFromToken (
 255   IN     EFI_GUID                   *ProducerGuid,
 256   IN     EFI_STRING_ID              StringId,
 257      OUT EFI_STRING                 *String
 258   )
 259 {
 260   return EFI_SUCCESS;
 261 }
 262
 263 /**
 264   Get string specified by StringId form the HiiHandle. The caller
 265   is responsible to free the *String.
 266
 267   If String is NULL, then ASSERT.
 268   If HiiHandle could not be found in the default HII database, then ASSERT.
 269   If StringId is not found in PackageList, then ASSERT.
 270
 271   @param  PackageList            The HII handle of package list.
 272   @param  StringId               The String ID.
 273   @param  String                 The output string.
 274
 275   @retval EFI_NOT_FOUND          String is not found.
 276   @retval EFI_SUCCESS            Operation is successful.
 277   @retval EFI_OUT_OF_RESOURCES   There is not enought memory in the system.
 278
 279 **/
 280 EFI_STATUS
 281 EFIAPI
 282 HiiLibGetStringFromHandle (
 283   IN     EFI_HII_HANDLE             PackageList,
 284   IN     EFI_STRING_ID              StringId,
 285      OUT EFI_STRING                 *String
 286   )
 287 {
 288   return EFI_SUCCESS;
 289 }
 290
 291 /**
 292   Create the driver handle for HII driver. The protocol and
 293   Package list of this driver wili be installed into this
 294   driver handle.
 295   The implement set DriverHandle to NULL simpliy to let
 296   handle manager create a default new handle.
 297
 298   @param  DriverHandle   The pointer of driver handle
 299
 300   @return                Always success.
 301 **/
 302 EFI_STATUS
 303 EFIAPI
 304 HiiLibCreateHiiDriverHandle (
 305   OUT EFI_HANDLE                    *DriverHandle
 306   )
 307 {
 308   //
 309   // Driver
 310   // This implementation does nothing as DriverHandle concept only
 311   // applies to UEFI HII specification.
 312   //
 313
 314   *DriverHandle = NULL;
 315
 316   return EFI_SUCCESS;
 317 }
 318