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