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