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  HiiHandle                The ID used to retrieve the Package List later.
 143   @param  ...                          The variable argument list describing all HII Package.
 144
 145   @return
 146   The allocated and initialized packages.
 147
 148 **/
 149
 150 EFI_STATUS
 151 EFIAPI
 152 HiiLibAddPackages (
 153   IN       UINTN               NumberOfPackages,
 154   IN CONST EFI_GUID            *GuidId,
 155   IN       EFI_HANDLE          DriverHandle, OPTIONAL
 156   OUT      EFI_HII_HANDLE      *HiiHandle, OPTIONAL
 157   ...
 158   )
 159 {
 160   VA_LIST                   Args;
 161   EFI_HII_PACKAGES          *FrameworkHiiPacages;
 162   FRAMEWORK_EFI_HII_HANDLE  FrameworkHiiHandle;
 163   EFI_STATUS                Status;
 164
 165
 166   VA_START (Args, HiiHandle);
 167   FrameworkHiiPacages = InternalPreparePackages (NumberOfPackages, GuidId, Args);
 168
 169   Status      = mHii->NewPack (mHii, FrameworkHiiPacages, &FrameworkHiiHandle);
 170   if (HiiHandle != NULL) {
 171     if (EFI_ERROR (Status)) {
 172       *HiiHandle = NULL;
 173     } else {
 174       *HiiHandle = (EFI_HII_HANDLE) (UINTN) FrameworkHiiHandle;
 175     }
 176   }
 177
 178   FreePool (FrameworkHiiPacages);
 179
 180   return Status;
 181 }
 182
 183 /**
 184   Removes a package list from the default HII database.
 185
 186   If HiiHandle is NULL, then ASSERT.
 187   If HiiHandle is not a valid EFI_HII_HANDLE in the default HII database, then ASSERT.
 188
 189   @param  HiiHandle                The handle that was previously registered to the data base that is requested for removal.
 190                                              List later.
 191
 192   @return  VOID
 193
 194 **/
 195 VOID
 196 EFIAPI
 197 HiiLibRemovePackages (
 198   IN      EFI_HII_HANDLE      HiiHandle
 199   )
 200 {
 201   EFI_STATUS Status;
 202
 203   Status = mHii->RemovePack (mHii, (FRAMEWORK_EFI_HII_HANDLE) (UINTN) HiiHandle);
 204   ASSERT_EFI_ERROR (Status);
 205 }
 206
 207
 208 /**
 209   This function adds the string into String Package of each language.
 210
 211   @param  PackageList            Handle of the package list where this string will
 212                                  be added.
 213   @param  StringId               On return, contains the new strings id, which is
 214                                  unique within PackageList.
 215   @param  String                 Points to the new null-terminated string.
 216
 217   @retval EFI_SUCCESS            The new string was added successfully.
 218   @retval EFI_NOT_FOUND          The specified PackageList could not be found in
 219                                  database.
 220   @retval EFI_OUT_OF_RESOURCES   Could not add the string due to lack of resources.
 221   @retval EFI_INVALID_PARAMETER  String is NULL or StringId is NULL is NULL.
 222
 223 **/
 224 EFI_STATUS
 225 EFIAPI
 226 HiiLibNewString (
 227   IN  EFI_HII_HANDLE                  PackageList,
 228   OUT EFI_STRING_ID                   *StringId,
 229   IN  CONST EFI_STRING                String
 230   )
 231 {
 232   FRAMEWORK_EFI_HII_HANDLE  FrameworkHiiHandle;
 233   EFI_STATUS                Status;
 234
 235   FrameworkHiiHandle = (FRAMEWORK_EFI_HII_HANDLE) (UINTN) PackageList;
 236   Status = mHii->NewString (
 237             mHii,
 238             NULL,
 239             FrameworkHiiHandle,
 240             StringId,
 241             String
 242           );
 243
 244   return Status;
 245 }
 246
 247 /**
 248   Get the string given the StringId and String package Producer's Guid. The caller
 249   is responsible to free the *String.
 250
 251   If PackageList with the matching ProducerGuid is not found, then ASSERT.
 252   If PackageList with the matching ProducerGuid is found but no String is
 253   specified by StringId is found, then ASSERT.
 254
 255   @param  ProducerGuid           The Guid of String package list.
 256   @param  StringId               The String ID.
 257   @param  String                 The output string.
 258
 259   @retval EFI_SUCCESS            Operation is successful.
 260   @retval EFI_OUT_OF_RESOURCES   There is not enought memory in the system.
 261
 262 **/
 263 EFI_STATUS
 264 EFIAPI
 265 HiiLibGetStringFromToken (
 266   IN  EFI_GUID                        *ProducerGuid,
 267   IN  EFI_STRING_ID                   StringId,
 268   OUT EFI_STRING                      *String
 269   )
 270 {
 271   return EFI_SUCCESS;
 272 }
 273
 274 /**
 275   Get string specified by StringId form the HiiHandle. The caller
 276   is responsible to free the *String.
 277
 278   If String is NULL, then ASSERT.
 279   If HiiHandle could not be found in the default HII database, then ASSERT.
 280   If StringId is not found in PackageList, then ASSERT.
 281
 282   @param  HiiHandle              The HII handle of package list.
 283   @param  StringId               The String ID.
 284   @param  String                 The output string.
 285
 286   @retval EFI_NOT_FOUND          String is not found.
 287   @retval EFI_SUCCESS            Operation is successful.
 288   @retval EFI_OUT_OF_RESOURCES   There is not enought memory in the system.
 289   @retval EFI_INVALID_PARAMETER  The String is NULL.
 290
 291 **/
 292 EFI_STATUS
 293 EFIAPI
 294 HiiLibGetStringFromHandle (
 295   IN  EFI_HII_HANDLE                  PackageList,
 296   IN  EFI_STRING_ID                   StringId,
 297   OUT EFI_STRING                      *String
 298   )
 299 {
 300   return EFI_SUCCESS;
 301 }
 302
 303 /**
 304   Create the driver handle for HII driver. The protocol and
 305   Package list of this driver wili be installed into this
 306   driver handle.
 307   The implement set DriverHandle to NULL simpliy to let
 308   handle manager create a default new handle.
 309
 310   @param[out] DriverHandle the pointer of driver handle
 311   @return always successful.
 312 **/
 313 EFI_STATUS
 314 EFIAPI
 315 HiiLibCreateHiiDriverHandle (
 316   OUT EFI_HANDLE               *DriverHandle
 317   )
 318 {
 319   //
 320   // Driver
 321   // This implementation does nothing as DriverHandle concept only
 322   // applies to UEFI HII specification.
 323   //
 324
 325   *DriverHandle = NULL;
 326
 327   return EFI_SUCCESS;
 328 }
 329