MdeModulePkg/Include/Library/HiiLib.h

   1 /** @file
   2   Public include file for the HII Library
   3
   4   Copyright (c) 2007 - 2008, Intel Corporation
   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 #ifndef __HII_LIB_H__
  16 #define __HII_LIB_H__
  17
  18
  19 /**
  20   Assemble EFI_HII_PACKAGE_LIST according to the passed in packages.
  21
  22   If GuidId is NULL, then ASSERT.
  23   If not enough resource to complete the operation, then ASSERT.
  24
  25   @param  NumberOfPackages       Number of packages.
  26   @param  GuidId                 Package GUID.
  27   @param  ...                    Variable argument list for packages to be assembled.
  28
  29   @return Pointer of EFI_HII_PACKAGE_LIST_HEADER.
  30
  31 **/
  32 EFI_HII_PACKAGE_LIST_HEADER *
  33 EFIAPI
  34 HiiLibPreparePackageList (
  35   IN UINTN                    NumberOfPackages,
  36   IN CONST EFI_GUID                 *GuidId,
  37   ...
  38   );
  39
  40 /**
  41   This function allocates pool for an EFI_HII_PACKAGE_LIST structure
  42   with additional space that is big enough to host all packages described by the variable
  43   argument list of package pointers.  The allocated structure is initialized using NumberOfPackages,
  44   GuidId,  and the variable length argument list of package pointers.
  45
  46   Then, EFI_HII_PACKAGE_LIST will be register to the default System HII Database. The
  47   Handle to the newly registered Package List is returned throught HiiHandle.
  48
  49   If HiiHandle is NULL, then ASSERT.
  50
  51   @param  NumberOfPackages    The number of HII packages to register.
  52   @param  GuidId              Package List GUID ID.
  53   @param  DriverHandle        Optional. If not NULL, the DriverHandle on which an instance of DEVICE_PATH_PROTOCOL is installed.
  54                               This DriverHandle uniquely defines the device that the added packages are associated with.
  55   @param  HiiHandle           On output, the HiiHandle is update with the handle which can be used to retrieve the Package
  56                               List later. If the functions failed to add the package to the default HII database, this value will
  57                               be set to NULL.
  58   @param  ...                 The variable argument list describing all HII Package.
  59
  60   @return  EFI_SUCCESS         If the packages are successfully added to the default HII database.
  61   @return  EFI_OUT_OF_RESOURCE Not enough resource to complete the operation.
  62
  63 **/
  64 EFI_STATUS
  65 EFIAPI
  66 HiiLibAddPackages (
  67   IN       UINTN               NumberOfPackages,
  68   IN CONST EFI_GUID            *GuidId,
  69   IN       EFI_HANDLE          DriverHandle, OPTIONAL
  70   OUT      EFI_HII_HANDLE      *HiiHandle,
  71   ...
  72   );
  73
  74 /**
  75   Removes a package list from the default HII database.
  76
  77   If HiiHandle is NULL, then ASSERT.
  78   If HiiHandle is not a valid EFI_HII_HANDLE in the default HII database, then ASSERT.
  79
  80   @param  HiiHandle                The handle that was previously registered to the data base that is requested for removal.
  81                                              List later.
  82
  83 **/
  84 VOID
  85 EFIAPI
  86 HiiLibRemovePackages (
  87   IN      EFI_HII_HANDLE      HiiHandle
  88   );
  89
  90 /**
  91   This function adds the string into String Package of each language
  92   supported by the package list.
  93
  94   If String is NULL, then ASSERT.
  95   If StringId is NULL, the ASSERT.
  96   If PackageList could not be found in the default HII database, then ASSERT.
  97
  98   @param  PackageList            Handle of the package list where this string will
  99                                             be added.
 100   @param  StringId               On return, contains the new strings id, which is
 101                                           unique within PackageList.
 102   @param  String                 Points to the new null-terminated string.
 103
 104   @retval EFI_SUCCESS             The new string was added successfully.
 105   @retval EFI_OUT_OF_RESOURCES   Could not add the string due to lack of resources.
 106
 107 **/
 108 EFI_STATUS
 109 EFIAPI
 110 HiiLibNewString (
 111   IN  EFI_HII_HANDLE                  PackageList,
 112   OUT EFI_STRING_ID                   *StringId,
 113   IN  CONST EFI_STRING                String
 114   );
 115
 116 /**
 117   This function update the specified string in String Package of each language
 118   supported by the package list.
 119
 120   If String is NULL, then ASSERT.
 121   If PackageList could not be found in the default HII database, then ASSERT.
 122   If StringId is not found in PackageList, then ASSERT.
 123
 124   @param  PackageList            Handle of the package list where this string will
 125                                             be added.
 126   @param  StringId               Ths String Id to be updated.
 127   @param  String                 Points to the new null-terminated string.
 128
 129   @retval EFI_SUCCESS            The new string was added successfully.
 130   @retval EFI_OUT_OF_RESOURCES   Could not add the string due to lack of resources.
 131
 132 **/
 133 EFI_STATUS
 134 EFIAPI
 135 HiiLibSetString (
 136   IN  EFI_HII_HANDLE                  PackageList,
 137   IN  EFI_STRING_ID                   StringId,
 138   IN  CONST EFI_STRING                String
 139   );
 140
 141 /**
 142   This function try to retrieve string from String package of current language.
 143   If fails, it try to retrieve string from String package of first language it support.
 144
 145   If StringSize is NULL, then ASSERT.
 146   If String is NULL and *StringSize is not 0, then ASSERT.
 147   If PackageList could not be found in the default HII database, then ASSERT.
 148   If StringId is not found in PackageList, then ASSERT.
 149
 150   @param  PackageList     The package list in the HII database to search for
 151                                      the specified string.
 152   @param  StringId          The string's id, which is unique within
 153                                       PackageList.
 154   @param  String             Points to the new null-terminated string.
 155   @param  StringSize       On entry, points to the size of the buffer pointed
 156                                  to by String, in bytes. On return, points to the
 157                                  length of the string, in bytes.
 158
 159   @retval EFI_SUCCESS            The string was returned successfully.
 160   @retval EFI_NOT_FOUND          The string specified by StringId is not available.
 161   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by StringLength is too small
 162                                  to hold the string.
 163
 164 **/
 165 EFI_STATUS
 166 EFIAPI
 167 HiiLibGetString (
 168   IN  EFI_HII_HANDLE                  PackageList,
 169   IN  EFI_STRING_ID                   StringId,
 170   OUT EFI_STRING                      String,
 171   IN  OUT UINTN                       *StringSize
 172   );
 173
 174 /**
 175   Get string specified by StringId form the HiiHandle. The caller
 176   is responsible to free the *String.
 177
 178   If String is NULL, then ASSERT.
 179   If HiiHandle could not be found in the default HII database, then ASSERT.
 180   If StringId is not found in PackageList, then ASSERT.
 181
 182   @param  HiiHandle              The HII handle of package list.
 183   @param  StringId               The String ID.
 184   @param  String                 The output string.
 185
 186   @retval EFI_NOT_FOUND          String is not found.
 187   @retval EFI_SUCCESS            Operation is successful.
 188   @retval EFI_OUT_OF_RESOURCES   There is not enought memory in the system.
 189
 190 **/
 191 EFI_STATUS
 192 EFIAPI
 193 HiiLibGetStringFromHandle (
 194   IN  EFI_HII_HANDLE                  HiiHandle,
 195   IN  EFI_STRING_ID                   StringId,
 196   OUT EFI_STRING                      *String
 197   );
 198
 199 /**
 200   Get the string given the StringId and String package Producer's Guid. The caller
 201   is responsible to free the *String.
 202
 203   If PackageList with the matching ProducerGuid is not found, then ASSERT.
 204   If PackageList with the matching ProducerGuid is found but no String is
 205   specified by StringId is found, then ASSERT.
 206
 207   @param  ProducerGuid           The Guid of String package list.
 208   @param  StringId               The String ID.
 209   @param  String                 The output string.
 210
 211   @retval EFI_SUCCESS            Operation is successful.
 212   @retval EFI_OUT_OF_RESOURCES   There is not enought memory in the system.
 213
 214 **/
 215 EFI_STATUS
 216 EFIAPI
 217 HiiLibGetStringFromToken (
 218   IN  EFI_GUID                        *ProducerGuid,
 219   IN  EFI_STRING_ID                   StringId,
 220   OUT EFI_STRING                      *String
 221   );
 222
 223 /**
 224   Determines the handles that are currently active in the database.
 225   It's the caller's responsibility to free handle buffer.
 226
 227   If HandleBufferLength is NULL, then ASSERT.
 228   If HiiHandleBuffer is NULL, then ASSERT.
 229
 230   @param  HandleBufferLength     On input, a pointer to the length of the handle
 231                                  buffer. On output, the length of the handle buffer
 232                                  that is required for the handles found.
 233   @param  HiiHandleBuffer        Pointer to an array of Hii Handles returned.
 234
 235   @retval EFI_SUCCESS            Get an array of Hii Handles successfully.
 236
 237 **/
 238 EFI_STATUS
 239 EFIAPI
 240 HiiLibGetHiiHandles (
 241   IN OUT UINTN                     *HandleBufferLength,
 242   OUT    EFI_HII_HANDLE            **HiiHandleBuffer
 243   );
 244
 245 /**
 246   Extract Hii package list GUID for given HII handle.
 247
 248   If HiiHandle could not be found in the default HII database, then ASSERT.
 249   If Guid is NULL, then ASSERT.
 250
 251   @param  Handle              Hii handle
 252   @param  Guid                Package list GUID
 253
 254   @retval EFI_SUCCESS            Successfully extract GUID from Hii database.
 255
 256 **/
 257 EFI_STATUS
 258 EFIAPI
 259 HiiLibExtractGuidFromHiiHandle (
 260   IN      EFI_HII_HANDLE      Handle,
 261   OUT     EFI_GUID            *Guid
 262   );
 263
 264 /**
 265   Find HII Handle in the default HII database associated with given Device Path.
 266
 267   If DevicePath is NULL, then ASSERT.
 268
 269   @param  DevicePath             Device Path associated with the HII package list
 270                                  handle.
 271
 272   @retval Handle                 HII package list Handle associated with the Device
 273                                         Path.
 274   @retval NULL                   Hii Package list handle is not found.
 275
 276 **/
 277 EFI_HII_HANDLE
 278 EFIAPI
 279 HiiLibDevicePathToHiiHandle (
 280   IN EFI_DEVICE_PATH_PROTOCOL   *DevicePath
 281   );
 282
 283
 284 /**
 285   Get next language from language code list (with separator ';').
 286
 287   If LangCode is NULL, then ASSERT.
 288   If Lang is NULL, then ASSERT.
 289
 290   @param  LangCode    On input: point to first language in the list. On
 291                                  output: point to next language in the list, or
 292                                  NULL if no more language in the list.
 293   @param  Lang           The first language in the list.
 294
 295 **/
 296 VOID
 297 EFIAPI
 298 HiiLibGetNextLanguage (
 299   IN OUT CHAR8      **LangCode,
 300   OUT CHAR8         *Lang
 301   );
 302
 303 /**
 304   This function returns the list of supported languages, in the format specified
 305   in UEFI specification Appendix M.
 306
 307   If HiiHandle is not a valid Handle in the default HII database, then ASSERT.
 308
 309   @param  HiiHandle              The HII package list handle.
 310
 311   @retval   !NULL  The supported languages.
 312   @retval   NULL    If Supported Languages can not be retrived.
 313
 314 **/
 315 CHAR8 *
 316 EFIAPI
 317 HiiLibGetSupportedLanguages (
 318   IN EFI_HII_HANDLE           HiiHandle
 319   );
 320
 321 /**
 322   This function returns the list of supported 2nd languages, in the format specified
 323   in UEFI specification Appendix M.
 324
 325   If HiiHandle is not a valid Handle in the default HII database, then ASSERT.
 326   If not enough resource to complete the operation, then ASSERT.
 327
 328   @param  HiiHandle              The HII package list handle.
 329   @param  FirstLanguage          Pointer to language name buffer.
 330
 331   @return The supported languages.
 332
 333 **/
 334 CHAR8 *
 335 EFIAPI
 336 HiiLibGetSupportedSecondaryLanguages (
 337   IN EFI_HII_HANDLE           HiiHandle,
 338   IN CONST CHAR8              *FirstLanguage
 339   );
 340
 341
 342 /**
 343   This function returns the number of supported languages on HiiHandle.
 344
 345   If HiiHandle is not a valid Handle in the default HII database, then ASSERT.
 346   If not enough resource to complete the operation, then ASSERT.
 347
 348   @param  HiiHandle              The HII package list handle.
 349
 350   @return The  number of supported languages.
 351
 352 **/
 353 UINT16
 354 EFIAPI
 355 HiiLibGetSupportedLanguageNumber (
 356   IN EFI_HII_HANDLE           HiiHandle
 357   );
 358
 359 /**
 360   Exports the contents of one or all package lists in the HII database into a buffer.
 361
 362   If Handle is not NULL and not a valid EFI_HII_HANDLE registered in the database,
 363   then ASSERT.
 364   If PackageListHeader is NULL, then ASSERT.
 365   If PackageListSize is NULL, then ASSERT.
 366
 367   @param  Handle                 The HII Handle.
 368   @param  PackageListHeader      A pointer to a buffer that will contain the results of
 369                                  the export function.
 370   @param  PackageListSize        On output, the length of the buffer that is required for the exported data.
 371
 372   @retval EFI_SUCCESS            Package exported.
 373
 374   @retval EFI_OUT_OF_RESOURCES   Not enought memory to complete the operations.
 375
 376 **/
 377 EFI_STATUS
 378 EFIAPI
 379 HiiLibExportPackageLists (
 380   IN EFI_HII_HANDLE                    Handle,
 381   OUT EFI_HII_PACKAGE_LIST_HEADER      **PackageListHeader,
 382   OUT UINTN                            *PackageListSize
 383   );
 384
 385 /**
 386
 387   This function returns a list of the package handles of the
 388   specified type that are currently active in the HII database. The
 389   pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package
 390   handles to be listed.
 391
 392   If HandleBufferLength is NULL, then ASSERT.
 393   If HandleBuffer is NULL, the ASSERT.
 394   If PackageType is EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is
 395   NULL, then ASSERT.
 396   If PackageType is not EFI_HII_PACKAGE_TYPE_GUID and PackageGuid is not
 397   NULL, then ASSERT.
 398
 399
 400   @param PackageType          Specifies the package type of the packages
 401                               to list or EFI_HII_PACKAGE_TYPE_ALL for
 402                               all packages to be listed.
 403
 404   @param PackageGuid          If PackageType is
 405                               EFI_HII_PACKAGE_TYPE_GUID, then this is
 406                               the pointer to the GUID which must match
 407                               the Guid field of
 408                               EFI_HII_PACKAGE_GUID_HEADER. Otherwise, it
 409                               must be NULL.
 410
 411   @param HandleBufferLength   On output, the length of the handle buffer
 412                               that is required for the handles found.
 413
 414   @param HandleBuffer         On output, an array of EFI_HII_HANDLE  instances returned.
 415                               The caller is responcible to free this pointer allocated.
 416
 417   @retval EFI_SUCCESS           The matching handles are outputed successfully.
 418                                 HandleBufferLength is updated with the actual length.
 419   @retval EFI_OUT_OF_RESOURCES  Not enough resource to complete the operation.
 420   @retval EFI_NOT_FOUND         No matching handle could not be found in database.
 421 **/
 422 EFI_STATUS
 423 EFIAPI
 424 HiiLibListPackageLists (
 425   IN        UINT8                     PackageType,
 426   IN CONST  EFI_GUID                  *PackageGuid,
 427   IN OUT    UINTN                     *HandleBufferLength,
 428   OUT       EFI_HII_HANDLE            **Handle
 429   );
 430
 431 /**
 432   Convert language code from RFC3066 to ISO639-2.
 433
 434   LanguageRfc3066 contain a single RFC 3066 code such as
 435   "en-US" or "fr-FR".
 436
 437   The LanguageRfc3066 must be a buffer large enough
 438   for ISO_639_2_ENTRY_SIZE characters.
 439
 440   If LanguageRfc3066 is NULL, then ASSERT.
 441   If LanguageIso639 is NULL, then ASSERT.
 442
 443   @param  LanguageRfc3066        RFC3066 language code.
 444   @param  LanguageIso639         ISO639-2 language code.
 445
 446   @retval EFI_SUCCESS            Language code converted.
 447   @retval EFI_NOT_FOUND          Language code not found.
 448
 449 **/
 450 EFI_STATUS
 451 EFIAPI
 452 ConvertRfc3066LanguageToIso639Language (
 453   IN  CHAR8   *LanguageRfc3066,
 454   OUT CHAR8   *LanguageIso639
 455   );
 456
 457 /**
 458   Convert language code from ISO639-2 to RFC3066.
 459
 460   LanguageIso639 contain a single ISO639-2 code such as
 461   "eng" or "fra".
 462
 463   The LanguageRfc3066 must be a buffer large enough
 464   for RFC_3066_ENTRY_SIZE characters.
 465
 466   If LanguageIso639 is NULL, then ASSERT.
 467   If LanguageRfc3066 is NULL, then ASSERT.
 468
 469   @param  LanguageIso639         ISO639-2 language code.
 470   @param  LanguageRfc3066        RFC3066 language code.
 471
 472   @retval EFI_SUCCESS            Language code converted.
 473   @retval EFI_NOT_FOUND          Language code not found.
 474
 475 **/
 476 EFI_STATUS
 477 EFIAPI
 478 ConvertIso639LanguageToRfc3066Language (
 479   IN  CONST CHAR8   *LanguageIso639,
 480   OUT CHAR8         *LanguageRfc3066
 481   );
 482
 483 /**
 484   Convert language code list from RFC3066 to ISO639-2, e.g. "en-US;fr-FR" will
 485   be converted to "engfra".
 486
 487   If SupportedLanguages is NULL, then ASSERT.
 488
 489   @param  SupportedLanguages     The RFC3066 language list.
 490
 491   @return The ISO639-2 language list.
 492
 493 **/
 494 CHAR8 *
 495 EFIAPI
 496 Rfc3066ToIso639 (
 497   CHAR8  *SupportedLanguages
 498   );
 499
 500
 501 /**
 502   Determine what is the current language setting. The space reserved for Lang
 503   must be at least RFC_3066_ENTRY_SIZE bytes;
 504
 505   If Lang is NULL, then ASSERT.
 506
 507   @param  Lang                   Pointer of system language. Lang will always be filled with
 508                                          a valid RFC 3066 language string. If "PlatformLang" is not
 509                                          set in the system, the default language specifed by PcdUefiVariableDefaultPlatformLang
 510                                          is returned.
 511
 512   @return  EFI_SUCCESS     If the EFI Variable with "PlatformLang" is set and return in Lang.
 513   @return  EFI_NOT_FOUND If the EFI Variable with "PlatformLang" is not set, but a valid default language is return in Lang.
 514
 515 **/
 516 EFI_STATUS
 517 EFIAPI
 518 GetCurrentLanguage (
 519   OUT     CHAR8               *Lang
 520   );
 521
 522 #endif