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