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   Registers a list of packages in the HII Database and returns the HII Handle
  21   associated with that registration.  If an HII Handle has already been registered
  22   with the same PackageListGuid, then NULL is returned.  If there are not enough
  23   resources to perform the registration, then NULL is returned.  If an empty list
  24   of packages is passed in, then NULL is returned.  If the size of the list of
  25   package is 0, then NULL is returned.
  26
  27   The variable arguments are pointers which point to package header that defined
  28   by UEFI VFR compiler and StringGather tool.
  29
  30   #pragma pack (push, 1)
  31   typedef struct {
  32     UINT32                  BinaryLength;
  33     EFI_HII_PACKAGE_HEADER  PackageHeader;
  34   } EDKII_AUTOGEN_PACKAGES_HEADER;
  35   #pragma pack (pop)
  36
  37   @param[in]  PackageListGuid  The GUID of the package list.
  38   @param[in]  DeviceHandle     If not NULL, the Device Handle on which
  39                                an instance of DEVICE_PATH_PROTOCOL is installed.
  40                                This Device Handle uniquely defines the device that
  41                                the added packages are associated with.
  42   @param[in]  ...              The variable argument list that contains pointers
  43                                to packages terminated by a NULL.
  44
  45   @retval NULL   A HII Handle has already been registered in the HII Database with
  46                  the same PackageListGuid.
  47   @retval NULL   The HII Handle could not be created.
  48   @retval NULL   An empty list of packages was passed in.
  49   @retval NULL   All packages are empty.
  50   @retval Other  The HII Handle associated with the newly registered package list.
  51
  52 **/
  53 EFI_HII_HANDLE
  54 EFIAPI
  55 HiiAddPackages (
  56   IN CONST EFI_GUID    *PackageListGuid,
  57   IN       EFI_HANDLE  DeviceHandle  OPTIONAL,
  58   ...
  59   )
  60 ;
  61
  62 /**
  63   Removes a package list from the HII database.
  64
  65   If HiiHandle is NULL, then ASSERT.
  66   If HiiHandle is not a valid EFI_HII_HANDLE in the HII database, then ASSERT.
  67
  68   @param[in]  HiiHandle   The handle that was previously registered in the HII database
  69
  70 **/
  71 VOID
  72 EFIAPI
  73 HiiRemovePackages (
  74   IN      EFI_HII_HANDLE      HiiHandle
  75   )
  76 ;
  77
  78 /**
  79   This function create a new string in String Package or updates an existing
  80   string in a String Package.  If StringId is 0, then a new string is added to
  81   a String Package.  If StringId is not zero, then a string in String Package is
  82   updated.  If SupportedLanguages is NULL, then the string is added or updated
  83   for all the languages that the String Package supports.  If SupportedLanguages
  84   is not NULL, then the string is added or updated for the set of languages
  85   specified by SupportedLanguages.
  86
  87   If HiiHandle is NULL, then ASSERT().
  88   If String is NULL, then ASSERT().
  89
  90   @param[in]  HiiHandle           A handle that was previously registered in the
  91                                   HII Database.
  92   @param[in]  StringId            If zero, then a new string is created in the
  93                                   String Package associated with HiiHandle.  If
  94                                   non-zero, then the string specified by StringId
  95                                   is updated in the String Package  associated
  96                                   with HiiHandle.
  97   @param[in]  String              A pointer to the Null-terminated Unicode string
  98                                   to add or update in the String Package associated
  99                                   with HiiHandle.
 100   @param[in]  SupportedLanguages  A pointer to a Null-terminated ASCII string of
 101                                   language codes.  If this parameter is NULL, then
 102                                   String is added or updated in the String Package
 103                                   associated with HiiHandle for all the languages
 104                                   that the String Package supports.  If this
 105                                   parameter is not NULL, then then String is added
 106                                   or updated in the String Package associated with
 107                                   HiiHandle for the set oflanguages specified by
 108                                   SupportedLanguages.  The format of
 109                                   SupportedLanguages must follow the language
 110                                   format assumed the HII Database.
 111
 112   @retval 0      The string could not be added or updated in the String Package.
 113   @retval Other  The EFI_STRING_ID of the newly added or updated string.
 114
 115 **/
 116 EFI_STRING_ID
 117 EFIAPI
 118 HiiSetString (
 119   IN EFI_HII_HANDLE    HiiHandle,
 120   IN EFI_STRING_ID     StringId,            OPTIONAL
 121   IN CONST EFI_STRING  String,
 122   IN CONST CHAR8       *SupportedLanguages  OPTIONAL
 123   )
 124 ;
 125
 126 /**
 127   Retrieves a string from a string package in a specific language.  If the language
 128   is not specified, then a string from a string package in the current platform
 129   language is retrieved.  If the string can not be retrieved using the specified
 130   language or the current platform language, then the string is retrieved from
 131   the string package in the first language the string package supports.  The
 132   returned string is allocated using AllocatePool().  The caller is responsible
 133   for freeing the allocated buffer using FreePool().
 134
 135   If HiiHandle is NULL, then ASSERT().
 136   If StringId is 0, then ASSET.
 137
 138   @param[in]  HiiHandle  A handle that was previously registered in the HII Database.
 139   @param[in]  StringId   The identifier of the string to retrieved from the string
 140                          package associated with HiiHandle.
 141   @param[in]  Language   The language of the string to retrieve.  If this parameter
 142                          is NULL, then the current platform language is used.  The
 143                          format of Language must follow the language format assumed
 144                          the HII Database.
 145
 146   @retval NULL   The string specified by StringId is not present in the string package.
 147   @retval Other  The string was returned.
 148
 149 **/
 150 EFI_STRING
 151 EFIAPI
 152 HiiGetString (
 153   IN EFI_HII_HANDLE  HiiHandle,
 154   IN EFI_STRING_ID   StringId,
 155   IN CONST CHAR8     *Language  OPTIONAL
 156   )
 157 ;
 158
 159 /**
 160   Retrieves a string from a string package names by GUID in a specific language.
 161   If the language is not specified, then a string from a string package in the
 162   current platform  language is retrieved.  If the string can not be retrieved
 163   using the specified language or the current platform language, then the string
 164   is retrieved from the string package in the first language the string package
 165   supports.  The returned string is allocated using AllocatePool().  The caller
 166   is responsible for freeing the allocated buffer using FreePool().
 167
 168   If PackageListGuid is NULL, then ASSERT().
 169   If StringId is 0, then ASSERT.
 170
 171   @param[in]  PackageListGuid  The GUID of a package list that was previously
 172                                registered in the HII Database.
 173   @param[in]  StringId         The identifier of the string to retrieved from the
 174                                string package associated with PackageListGuid.
 175   @param[in]  Language         The language of the string to retrieve.  If this
 176                                parameter is NULL, then the current platform
 177                                language is used.  The format of Language must
 178                                follow the language format assumed the HII Database.
 179
 180   @retval NULL   The package list specified by PackageListGuid is not present in the
 181                  HII Database.
 182   @retval NULL   The string specified by StringId is not present in the string package.
 183   @retval Other  The string was returned.
 184
 185 **/
 186 EFI_STRING
 187 EFIAPI
 188 HiiGetPackageString (
 189   IN CONST EFI_GUID  *PackageListGuid,
 190   IN EFI_STRING_ID   StringId,
 191   IN CONST CHAR8     *Language  OPTIONAL
 192   )
 193 ;
 194
 195 /**
 196   Retrieves the array of all the HII Handles or the HII handle of a specific
 197   package list in the HII Database.
 198   This array is terminated with a NULL HII Handle.
 199   This function allocates the returned array using AllocatePool().
 200   The caller is responsible for freeing the array with FreePool().
 201
 202   @param[in]  PackageListGuid  An optional parameter that is used to request
 203                                an HII Handle that is associatd with a specific
 204                                Package List GUID.  If this parameter is NULL
 205                                then all the HII Handles in the HII Database
 206                                are returned.  If this parameter is not NULL
 207                                then at most 1 HII Handle is returned.
 208
 209   @retval NULL   No HII handles were found in the HII database
 210   @retval NULL   The array of HII Handles could not be retrieved
 211   @retval Other  A pointer to the NULL terminated array of HII Handles
 212
 213 **/
 214 EFI_HII_HANDLE *
 215 EFIAPI
 216 HiiGetHiiHandles (
 217   IN CONST EFI_GUID  *PackageListGuid  OPTIONAL
 218   )
 219 ;
 220
 221 /**
 222   Get next language from language code list (with separator ';').
 223
 224   If LangCode is NULL, then ASSERT.
 225   If Lang is NULL, then ASSERT.
 226
 227   @param  LangCode    On input: point to first language in the list. On
 228                                  output: point to next language in the list, or
 229                                  NULL if no more language in the list.
 230   @param  Lang           The first language in the list.
 231
 232 **/
 233 VOID
 234 EFIAPI
 235 HiiLibGetNextLanguage (
 236   IN OUT CHAR8      **LangCode,
 237   OUT CHAR8         *Lang
 238   )
 239 ;
 240
 241 /**
 242   Retrieves a pointer to the a Null-terminated ASCII string containing the list
 243   of languages that an HII handle in the HII Database supports.  The returned
 244   string is allocated using AllocatePool().  The caller is responsible for freeing
 245   the returned string using FreePool().  The format of the returned string follows
 246   the language format assumed the HII Database.
 247
 248   If HiiHandle is NULL, then ASSERT().
 249
 250   @param[in]  HiiHandle  A handle that was previously registered in the HII Database.
 251
 252   @retval NULL   HiiHandle is not registered in the HII database
 253   @retval NULL   There are not enough resources available to retrieve the suported
 254                  languages.
 255   @retval NULL   The list of suported languages could not be retrieved.
 256   @retval Other  A pointer to the Null-terminated ASCII string of supported languages.
 257
 258 **/
 259 CHAR8 *
 260 EFIAPI
 261 HiiGetSupportedLanguages (
 262   IN EFI_HII_HANDLE           HiiHandle
 263   )
 264 ;
 265
 266 /**
 267   Convert language code from RFC3066 to ISO639-2.
 268
 269   LanguageRfc3066 contain a single RFC 3066 code such as
 270   "en-US" or "fr-FR".
 271
 272   The LanguageRfc3066 must be a buffer large enough
 273   for ISO_639_2_ENTRY_SIZE characters.
 274
 275   If LanguageRfc3066 is NULL, then ASSERT.
 276   If LanguageIso639 is NULL, then ASSERT.
 277
 278   @param  LanguageRfc3066        RFC3066 language code.
 279   @param  LanguageIso639         ISO639-2 language code.
 280
 281   @retval EFI_SUCCESS            Language code converted.
 282   @retval EFI_NOT_FOUND          Language code not found.
 283
 284 **/
 285 EFI_STATUS
 286 EFIAPI
 287 ConvertRfc3066LanguageToIso639Language (
 288   IN  CHAR8   *LanguageRfc3066,
 289   OUT CHAR8   *LanguageIso639
 290   )
 291 ;
 292
 293 /**
 294   Convert language code from ISO639-2 to RFC3066 and return the converted language.
 295   Caller is responsible for freeing the allocated buffer.
 296
 297   LanguageIso639 contain a single ISO639-2 code such as
 298   "eng" or "fra".
 299
 300   If LanguageIso639 is NULL, then ASSERT.
 301   If LanguageRfc3066 is NULL, then ASSERT.
 302
 303   @param  LanguageIso639         ISO639-2 language code.
 304
 305   @return the allocated buffer or NULL, if the language is not found.
 306
 307 **/
 308 CHAR8*
 309 EFIAPI
 310 ConvertIso639LanguageToRfc3066Language (
 311   IN  CONST CHAR8   *LanguageIso639
 312   )
 313 ;
 314
 315 /**
 316   Convert language code list from RFC3066 to ISO639-2, e.g. "en-US;fr-FR" will
 317   be converted to "engfra".
 318
 319   If SupportedLanguages is NULL, then ASSERT.
 320
 321   @param  SupportedLanguages     The RFC3066 language list.
 322
 323   @return The ISO639-2 language list.
 324
 325 **/
 326 CHAR8 *
 327 EFIAPI
 328 Rfc3066ToIso639 (
 329   CHAR8  *SupportedLanguages
 330   )
 331 ;
 332
 333
 334 ////////////////////////////////////////////////////////
 335 ////////////////////////////////////////////////////////
 336 // HiiLib Functions
 337 ////////////////////////////////////////////////////////
 338 ////////////////////////////////////////////////////////
 339
 340 /**
 341   Registers a list of packages in the HII Database and returns the HII Handle
 342   associated with that registration.  If an HII Handle has already been registered
 343   with the same PackageListGuid, then NULL is returned.  If there are not enough
 344   resources to perform the registration, then NULL is returned.  If an empty list
 345   of packages is passed in, then NULL is returned.  If the size of the list of
 346   package is 0, then NULL is returned.
 347
 348   @param[in]  PackageListGuid  An optional parameter that is used to identify
 349                                the GUID of the package list.  If this parameter
 350                                is NULL, then gEfiCallerIdGuid is used.
 351   @param[in]  DeviceHandle     Optional. If not NULL, the Device Handle on which
 352                                an instance of DEVICE_PATH_PROTOCOL is installed.
 353                                This Device Handle uniquely defines the device that
 354                                the added packages are associated with.
 355   @param[in]  ...              The variable argument list that contains pointers
 356                                to packages terminated by a NULL.
 357
 358   @retval NULL   A HII Handle has already been registered in the HII Database with
 359                  the same PackageListGuid.
 360   @retval NULL   The HII Handle could not be created.
 361   @retval Other  The HII Handle associated with the newly registered package list.
 362
 363 **/
 364 EFI_HII_HANDLE
 365 EFIAPI
 366 HiiAddPackages (
 367   IN CONST EFI_GUID    *PackageListGuid,  OPTIONAL
 368   IN       EFI_HANDLE  DeviceHandle,      OPTIONAL
 369   ...
 370   );
 371
 372 /**
 373   Removes a package list from the HII Database.
 374
 375   If HiiHandle is NULL, then ASSERT().
 376   If HiiHandle is not a valid EFI_HII_HANDLE in the HII Database, then ASSERT().
 377
 378   @param[in]  HiiHandle  A handle that was previously registered in the HII Database.
 379
 380 **/
 381 VOID
 382 EFIAPI
 383 HiiRemovePackages (
 384   IN EFI_HII_HANDLE  HiiHandle
 385   );
 386
 387 /**
 388   Retrieves the array of all the HII Handles in the HII Database.
 389   This array is terminated with a NULL HII Handle.
 390   This function allocates the returned array using AllocatePool().
 391   The caller is responsible for freeing the array with FreePool().
 392
 393   @param[in]  PackageListGuid  An optional parameter that is used to request
 394                                an HII Handle that is associatd with a specific
 395                                Package List GUID.  If this parameter is NULL
 396                                then all the HII Handles in the HII Database
 397                                are returned.  If this parameter is not NULL
 398                                then at most 1 HII Handle is returned.
 399
 400   @retval NULL   There are no HII handles in the HII database
 401   @retval NULL   The array of HII Handles could not be retrieved
 402   @retval Other  A pointer to the NULL terminated array of HII Handles
 403
 404 **/
 405 EFI_HII_HANDLE *
 406 EFIAPI
 407 HiiGetHiiHandles (
 408   IN CONST EFI_GUID  *PackageListGuid  OPTIONAL
 409   );
 410
 411 /**
 412   Retrieves a pointer to the a Null-terminated ASCII string containing the list
 413   of languages that an HII handle in the HII Database supports.  The returned
 414   string is allocated using AllocatePool().  The caller is responsible for freeing
 415   the returned string using FreePool().  The format of the returned string follows
 416   the language format assumed the HII Database.
 417
 418   If HiiHandle is NULL, then ASSERT().
 419
 420   @param[in]  HiiHandle  A handle that was previously registered in the HII Database.
 421
 422   @retval NULL   HiiHandle is not registered in the HII database
 423   @retval NULL   There are not enough resources available to retrieve the suported
 424                  languages.
 425   @retval NULL   The list of suported languages could not be retrieved.
 426   @retval Other  A pointer to the Null-terminated ASCII string of supported languages.
 427
 428 **/
 429 CHAR8 *
 430 EFIAPI
 431 HiiGetSupportedLanguages (
 432   IN EFI_HII_HANDLE  HiiHandle
 433   );
 434
 435 /**
 436   Retrieves a string from a string package in a specific language.  If the language
 437   is not specified, then a string from a string package in the current platform
 438   language is retrieved.  If the string can not be retrieved using the specified
 439   language or the current platform language, then the string is retrieved from
 440   the string package in the first language the string package supports.  The
 441   returned string is allocated using AllocatePool().  The caller is responsible
 442   for freeing the allocated buffer using FreePool().
 443
 444   If HiiHandle is NULL, then ASSERT().
 445   If StringId is 0, then ASSET.
 446
 447   @param[in]  HiiHandle  A handle that was previously registered in the HII Database.
 448   @param[in]  StringId   The identifier of the string to retrieved from the string
 449                          package associated with HiiHandle.
 450   @param[in]  Language   The language of the string to retrieve.  If this parameter
 451                          is NULL, then the current platform language is used.  The
 452                          format of Language must follow the language format assumed
 453                          the HII Database.
 454
 455   @retval NULL   The string specified by StringId is not present in the string package.
 456   @retval Other  The string was returned.
 457
 458 **/
 459 EFI_STRING
 460 EFIAPI
 461 HiiGetString (
 462   IN EFI_HII_HANDLE  HiiHandle,
 463   IN EFI_STRING_ID   StringId,
 464   IN CONST CHAR8     *Language  OPTIONAL
 465   );
 466
 467 /**
 468   Retrieves a string from a string package names by GUID in a specific language.
 469   If the language is not specified, then a string from a string package in the
 470   current platform  language is retrieved.  If the string can not be retrieved
 471   using the specified language or the current platform language, then the string
 472   is retrieved from the string package in the first language the string package
 473   supports.  The returned string is allocated using AllocatePool().  The caller
 474   is responsible for freeing the allocated buffer using FreePool().
 475
 476   If PackageListGuid is NULL, then ASSERT().
 477   If StringId is 0, then ASSET.
 478
 479   @param[in]  PackageListGuid  The GUID of a package list that was previously
 480                                registered in the HII Database.
 481   @param[in]  StringId         The identifier of the string to retrieved from the
 482                                string package associated with PackageListGuid.
 483   @param[in]  Language         The language of the string to retrieve.  If this
 484                                parameter is NULL, then the current platform
 485                                language is used.  The format of Language must
 486                                follow the language format assumed the HII Database.
 487
 488   @retval NULL   The package list specified by PackageListGuid is not present in the
 489                  HII Database.
 490   @retval NULL   The string specified by StringId is not present in the string package.
 491   @retval Other  The string was returned.
 492
 493 **/
 494 EFI_STRING
 495 EFIAPI
 496 HiiGetPackageString (
 497   IN CONST EFI_GUID  *PackageListGuid,
 498   IN EFI_STRING_ID   StringId,
 499   IN CONST CHAR8     *Language  OPTIONAL
 500   );
 501
 502 /**
 503   This function create a new string in String Package or updates an existing
 504   string in a String Package.  If StringId is 0, then a new string is added to
 505   a String Package.  If StringId is not zero, then a string in String Package is
 506   updated.  If SupportedLanguages is NULL, then the string is added or updated
 507   for all the languages that the String Package supports.  If SupportedLanguages
 508   is not NULL, then the string is added or updated for the set of languages
 509   specified by SupportedLanguages.
 510
 511   If HiiHandle is NULL, then ASSERT().
 512   If String is NULL, then ASSERT().
 513
 514   @param[in]  HiiHandle           A handle that was previously registered in the
 515                                   HII Database.
 516   @param[in]  StringId            If zero, then a new string is created in the
 517                                   String Package associated with HiiHandle.  If
 518                                   non-zero, then the string specified by StringId
 519                                   is updated in the String Package  associated
 520                                   with HiiHandle.
 521   @param[in]  String              A pointer to the Null-terminated Unicode string
 522                                   to add or update in the String Package associated
 523                                   with HiiHandle.
 524   @param[in]  SupportedLanguages  A pointer to a Null-terminated ASCII string of
 525                                   language codes.  If this parameter is NULL, then
 526                                   String is added or updated in the String Package
 527                                   associated with HiiHandle for all the languages
 528                                   that the String Package supports.  If this
 529                                   parameter is not NULL, then then String is added
 530                                   or updated in the String Package associated with
 531                                   HiiHandle for the set oflanguages specified by
 532                                   SupportedLanguages.  The format of
 533                                   SupportedLanguages must follow the language
 534                                   format assumed the HII Database.
 535
 536   @retval 0      The string could not be added or updated in the String Package.
 537   @retval Other  The EFI_STRING_ID of the newly added or updated string.
 538
 539 **/
 540 EFI_STRING_ID
 541 EFIAPI
 542 HiiSetString (
 543   IN EFI_HII_HANDLE    HiiHandle,
 544   IN EFI_STRING_ID     StringId,            OPTIONAL
 545   IN CONST EFI_STRING  String,
 546   IN CONST CHAR8       *SupportedLanguages  OPTIONAL
 547   );
 548
 549 /**
 550   Validates the config data associated with an HII handle in the HII Database.
 551
 552   If HiiHandle is NULL, then ASSERT().
 553
 554   @param[in]  HiiHandle  A handle that was previously registered in the HII Database.
 555
 556   @retval TRUE   The config data associated with HiiHandle passes all validation
 557                  checks.
 558   @retval FALSE  The config data associated with HiiHandle failed one or more
 559                  validation checks.
 560
 561 **/
 562 BOOLEAN
 563 EFIAPI
 564 HiiValidateDataFromHiiHandle (
 565   IN EFI_HII_HANDLE  HiiHandle
 566   );
 567
 568 /**
 569   Allocates and returns a Null-terminated Unicode <ConfigHdr> string using routing
 570   information that includes a GUID, an optional Unicode string name, and a device
 571   path.  The string returned is allocated with AllocatePool().  The caller is
 572   responsible for freeing the allocated string with FreePool().
 573
 574   The format of a <ConfigHdr> is as follows:
 575
 576     GUID=<HexCh>32&NAME=<Char>NameLength&PATH=<HexChar>DevicePathSize<Null>
 577
 578   @param[in]  Guid          Pointer to an EFI_GUID that is the routing information
 579                             GUID.  Each of the 16 bytes in Guid is converted to
 580                             a 2 Unicode character hexidecimal string.  This is
 581                             an optional parameter that may be NULL.
 582   @param[in]  Name          Pointer to a Null-terminated Unicode string that is
 583                             the routing information NAME.  This is an optional
 584                             parameter that may be NULL.  Each 16-bit Unicode
 585                             character in Name is converted to a 4 character Unicode
 586                             hexidecimal string.
 587   @param[in]  DriverHandle  The driver handle which supports a Device Path Protocol
 588                             that is the routing information PATH.  Each byte of
 589                             the Device Path associated with DriverHandle is converted
 590                             to a 2 Unicode character hexidecimal string.
 591
 592   @retval NULL   DriverHandle does not support the Device Path Protocol.
 593   @retval NULL   DriverHandle does not support the Device Path Protocol.
 594   @retval Other  A pointer to the Null-terminate Unicode <ConfigHdr> string
 595
 596 **/
 597 EFI_STRING
 598 EFIAPI
 599 HiiConstructConfigHdr (
 600   IN CONST EFI_GUID  *Guid,  OPTIONAL
 601   IN CONST CHAR16    *Name,  OPTIONAL
 602   IN EFI_HANDLE      DriverHandle
 603   );
 604
 605 /**
 606   Allocates and returns a Null-terminated Unicode <ConfigAltResp> string.
 607
 608   If Guid is NULL, then ASSERT().
 609   If Name is NULL, then ASSERT().
 610   If BlockNameArray is NULL, then ASSERT().
 611
 612   @param[in] Guid               GUID of the buffer storage.
 613   @param[in] Name               Name of the buffer storage.
 614   @param[in] DriverHandle       The DriverHandle that support a Device Path
 615                                 Protocol.
 616   @param[in] BufferStorage      Content of the buffer storage.
 617   @param[in] BufferStorageSize  Length in bytes of the buffer storage.
 618   @param[in] BlockNameArray     Array generated by VFR compiler.  This array
 619                                 contains a UINT32 value that is the length
 620                                 of BlockNameArray in bytes, followed by pairs
 621                                 of 16-bit values that are the offset and length
 622                                 values used to contruct a <ConfigRequest> string.
 623   @param[in]  ...               A variable argument list that contains pairs of 16-bit
 624                                 ALTCFG identifiers and pointers to DefaultValueArrays.
 625                                 The variable argument list is terminated by a NULL
 626                                 DefaultValueArray pointer.  A DefaultValueArray
 627                                 contains a UINT32 value that is the length, in bytes,
 628                                 of the DefaultValueArray.  The UINT32 length value
 629                                 is followed by a series of records that contain
 630                                 a 16-bit WIDTH value followed by a byte array with
 631                                 WIDTH entries.  The records must be parsed from
 632                                 beginning to end until the UINT32 length limit
 633                                 is reached.
 634
 635   @retval NULL          There are not enough resources to process the request.
 636   @retval NULL          A <ConfigResp> could not be retrieved from the Config
 637                         Routing Protocol.
 638   @retval Other         A pointer to the Null-terminate Unicode <ConfigAltResp>
 639                         string.
 640
 641 **/
 642 EFI_STRING
 643 EFIAPI
 644 HiiConstructConfigAltResp (
 645   IN CONST EFI_GUID  *Guid,
 646   IN CONST CHAR16    *Name,
 647   IN EFI_HANDLE      DriverHandle,
 648   IN CONST VOID      *BufferStorage,
 649   IN UINTN           BufferStorageSize,
 650   IN CONST VOID      *BlockNameArray,
 651   ...
 652   );
 653
 654 /**
 655   Determines if the routing data specified by GUID and NAME match a <ConfigHdr>.
 656
 657   If ConfigHdr is NULL, then ASSERT().
 658
 659   @param[in] ConfigHdr  Either <ConfigRequest> or <ConfigResp>.
 660   @param[in] Guid       GUID of the storage.
 661   @param[in] Name       NAME of the storage.
 662
 663   @retval TRUE   Routing information matches <ConfigHdr>.
 664   @retval FALSE  Routing information does not match <ConfigHdr>.
 665
 666 **/
 667 BOOLEAN
 668 EFIAPI
 669 HiiIsConfigHdrMatch (
 670   IN CONST EFI_STRING  ConfigHdr,
 671   IN CONST EFI_GUID    *Guid,     OPTIONAL
 672   IN CONST CHAR16      *Name      OPTIONAL
 673   );
 674
 675 /**
 676   Retrieves uncommited data from the Form Browser and converts it to a binary
 677   buffer.  The returned buffer is allocated using AllocatePool().  The caller
 678   is responsible for freeing the returned buffer using FreePool().
 679
 680   @param[in]  VariableName  Pointer to a Null-terminated Unicode string.  This
 681                             is an optional parameter that may be NULL.
 682   @param[in]  VariableGuid  Pointer to an EFI_GUID structure.  This is an optional
 683                             parameter that may be NULL.
 684   @param[in]  BufferSize    Length in bytes of buffer to hold retrived data.
 685
 686   @retval NULL   The uncommitted data could not be retrieved.
 687   @retval Other  A pointer to a buffer containing the uncommitted data.
 688
 689 **/
 690 UINT8 *
 691 EFIAPI
 692 HiiGetBrowserData (
 693   IN CONST EFI_GUID  *VariableGuid,  OPTIONAL
 694   IN CONST CHAR16    *VariableName,  OPTIONAL
 695   IN UINTN           BlockSize
 696   );
 697
 698 /**
 699   Updates uncommitted data in the Form Browser.
 700
 701   If Buffer is NULL, then ASSERT().
 702
 703   @param[in]  VariableName    Pointer to a Null-terminated Unicode string.  This
 704                               is an optional parameter that may be NULL.
 705   @param[in]  VariableGuid    Pointer to an EFI_GUID structure.  This is an optional
 706                               parameter that may be NULL.
 707   @param[in]  BufferSize      Length, in bytes, of Buffer.
 708   @param[in]  Buffer          Buffer of data to commit.
 709   @param[in]  RequestElement  An optional field to specify which part of the
 710                               buffer data will be send back to Browser. If NULL,
 711                               the whole buffer of data will be committed to
 712                               Browser.
 713                               <RequestElement> ::= &OFFSET=<Number>&WIDTH=<Number>*
 714
 715   @retval FALSE  The uncommitted data could not be updated.
 716   @retval TRUE   The uncommitted data was updated.
 717
 718 **/
 719 BOOLEAN
 720 EFIAPI
 721 HiiSetBrowserData (
 722   IN CONST EFI_GUID  *VariableGuid, OPTIONAL
 723   IN CONST CHAR16    *VariableName, OPTIONAL
 724   IN UINTN           BufferSize,
 725   IN CONST UINT8     *Buffer,
 726   IN CONST CHAR16    *RequestElement  OPTIONAL
 727   );
 728
 729 /////////////////////////////////////////
 730 /////////////////////////////////////////
 731 /// IFR Functions
 732 /////////////////////////////////////////
 733 /////////////////////////////////////////
 734
 735 /**
 736   Returns a UINT64 value that contains bitfields for Hour, Minute, and Second.
 737   The lower 8-bits of Hour are placed in bits 0..7.  The lower 8-bits of Minute
 738   are placed in bits 8..15, and the lower 8-bits of Second are placed in bits
 739   16..23.  This format is selected because it can be easily translated to
 740   an EFI_HII_TIME structure in an EFI_IFR_TYPE_VALUE union.
 741
 742   @param  Hour    The hour value to be encoded.
 743   @param  Minute  The miniute value to be encoded.
 744   @param  Second  The second value to be encoded.
 745
 746   @return A 64-bit containing Hour, Minute, and Second.
 747 **/
 748 #define EFI_HII_TIME_UINT64(Hour, Minute, Second) \
 749   (UINT64)((Hour & 0xff) | ((Minute & 0xff) << 8) | ((Second & 0xff) << 16))
 750
 751 /**
 752   Returns a UINT64 value that contains bitfields for Year, Month, and Day.
 753   The lower 16-bits of Year are placed in bits 0..15.  The lower 8-bits of Month
 754   are placed in bits 16..23, and the lower 8-bits of Day are placed in bits
 755   24..31.  This format is selected because it can be easily translated to
 756   an EFI_HII_DATE structure in an EFI_IFR_TYPE_VALUE union.
 757
 758   @param  Year   The year value to be encoded.
 759   @param  Month  The month value to be encoded.
 760   @param  Day    The day value to be encoded.
 761
 762   @return A 64-bit containing Year, Month, and Day.
 763 **/
 764 #define EFI_HII_DATE_UINT64(Year, Month, Day) \
 765   (UINT64)((Year & 0xffff) | ((Month & 0xff) << 16) | ((Day & 0xff) << 24))
 766
 767 /**
 768   Allocates and returns a new OpCode Handle.  OpCode Handles must be freed with
 769   HiiFreeOpCodeHandle().
 770
 771   @retval NULL   There are not enough resources to allocate a new OpCode Handle.
 772   @retval Other  A new OpCode handle.
 773
 774 **/
 775 VOID *
 776 EFIAPI
 777 HiiAllocateOpCodeHandle (
 778   VOID
 779   );
 780
 781 /**
 782   Frees an OpCode Handle that was peviously allocated with HiiAllocateOpCodeHandle().
 783   When an OpCode Handle is freed, all of the opcodes associated with the OpCode
 784   Handle are also freed.
 785
 786   If OpCodeHandle is NULL, then ASSERT().
 787
 788 **/
 789 VOID
 790 EFIAPI
 791 HiiFreeOpCodeHandle (
 792   VOID  *OpCodeHandle
 793   );
 794
 795 /**
 796   Create EFI_IFR_END_OP opcode.
 797
 798   If OpCodeHandle is NULL, then ASSERT().
 799
 800   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 801
 802   @retval NULL   There is not enough space left in Buffer to add the opcode.
 803   @retval Other  A pointer to the created opcode.
 804
 805 **/
 806 UINT8 *
 807 EFIAPI
 808 HiiCreateEndOpCode (
 809   IN VOID  *OpCodeHandle
 810   );
 811
 812 /**
 813   Create EFI_IFR_ONE_OF_OPTION_OP opcode.
 814
 815   If OpCodeHandle is NULL, then ASSERT().
 816   If Type is invalid, then ASSERT().
 817   If Flags is invalid, then ASSERT().
 818
 819   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 820   @param[in]  StringId      StringId for the option
 821   @param[in]  Flags         Flags for the option
 822   @param[in]  Type          Type for the option
 823   @param[in]  Value         Value for the option
 824
 825   @retval NULL   There is not enough space left in Buffer to add the opcode.
 826   @retval Other  A pointer to the created opcode.
 827
 828 **/
 829 UINT8 *
 830 EFIAPI
 831 HiiCreateOneOfOptionOpCode (
 832   IN VOID    *OpCodeHandle,
 833   IN UINT16  StringId,
 834   IN UINT8   Flags,
 835   IN UINT8   Type,
 836   IN UINT64  Value
 837   );
 838
 839 /**
 840   Create EFI_IFR_DEFAULT_OP opcode.
 841
 842   If OpCodeHandle is NULL, then ASSERT().
 843   If Type is invalid, then ASSERT().
 844
 845   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 846   @param[in]  DefaultId     DefaultId for the default
 847   @param[in]  Type          Type for the default
 848   @param[in]  Value         Value for the default
 849
 850   @retval NULL   There is not enough space left in Buffer to add the opcode.
 851   @retval Other  A pointer to the created opcode.
 852
 853 **/
 854 UINT8 *
 855 EFIAPI
 856 HiiCreateDefaultOpCode (
 857   IN VOID    *OpCodeHandle,
 858   IN UINT16  DefaultId,
 859   IN UINT8   Type,
 860   IN UINT64  Value
 861   );
 862
 863 /**
 864   Create EFI_IFR_GUID opcode.
 865
 866   If OpCodeHandle is NULL, then ASSERT().
 867   If Guid is NULL, then ASSERT().
 868   If OpCodeSize < sizeof (EFI_IFR_GUID), then ASSERT().
 869
 870   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 871   @param[in]  Guid          Pointer to EFI_GUID of this guided opcode.
 872   @param[in]  GuidOpCode    Pointer to an EFI_IFR_GUID opcode.  This is an
 873                             optional parameter that may be NULL.  If this
 874                             parameter is NULL, then the GUID extension
 875                             region of the created opcode is filled with zeros.
 876                             If this parameter is not NULL, then the GUID
 877                             extension region of GuidData will be copied to
 878                             the GUID extension region of the created opcode.
 879   @param[in]  OpCodeSize    The size, in bytes, of created opcode.  This value
 880                             must be >= sizeof(EFI_IFR_GUID).
 881
 882   @retval NULL   There is not enough space left in Buffer to add the opcode.
 883   @retval Other  A pointer to the created opcode.
 884
 885 **/
 886 UINT8 *
 887 EFIAPI
 888 HiiCreateGuidOpCode (
 889   IN VOID            *OpCodeHandle,
 890   IN CONST EFI_GUID  *Guid,
 891   IN CONST VOID      *GuidOpCode,    OPTIONAL
 892   IN UINTN           OpCodeSize
 893   );
 894
 895 /**
 896   Create EFI_IFR_ACTION_OP opcode.
 897
 898   If OpCodeHandle is NULL, then ASSERT().
 899   If any reserved bits are set in QuestionFlags, then ASSERT().
 900
 901   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 902   @param[in]  QuestionId      Question ID
 903   @param[in]  Prompt          String ID for Prompt
 904   @param[in]  Help            String ID for Help
 905   @param[in]  QuestionFlags   Flags in Question Header
 906   @param[in]  QuestionConfig  String ID for configuration
 907
 908   @retval NULL   There is not enough space left in Buffer to add the opcode.
 909   @retval Other  A pointer to the created opcode.
 910
 911 **/
 912 UINT8 *
 913 EFIAPI
 914 HiiCreateActionOpCode (
 915   IN VOID             *OpCodeHandle,
 916   IN EFI_QUESTION_ID  QuestionId,
 917   IN EFI_STRING_ID    Prompt,
 918   IN EFI_STRING_ID    Help,
 919   IN UINT8            QuestionFlags,
 920   IN EFI_STRING_ID    QuestionConfig
 921   );
 922
 923 /**
 924   Create EFI_IFR_SUBTITLE_OP opcode.
 925
 926   If OpCodeHandle is NULL, then ASSERT().
 927   If any reserved bits are set in Flags, then ASSERT().
 928   If Scope > 1, then ASSERT().
 929
 930   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 931   @param[in]  Prompt      String ID for Prompt
 932   @param[in]  Help        String ID for Help
 933   @param[in]  Flags       Subtitle opcode flags
 934   @param[in]  Scope       1 if this opcpde is the beginning of a new scope.
 935                           0 if this opcode is within the current scope.
 936
 937   @retval NULL   There is not enough space left in Buffer to add the opcode.
 938   @retval Other  A pointer to the created opcode.
 939
 940 **/
 941 UINT8 *
 942 EFIAPI
 943 HiiCreateSubTitleOpCode (
 944   IN VOID           *OpCodeHandle,
 945   IN EFI_STRING_ID  Prompt,
 946   IN EFI_STRING_ID  Help,
 947   IN UINT8          Flags,
 948   IN UINT8          Scope
 949   );
 950
 951 /**
 952   Create EFI_IFR_REF_OP opcode.
 953
 954   If OpCodeHandle is NULL, then ASSERT().
 955   If any reserved bits are set in QuestionFlags, then ASSERT().
 956
 957   @param[in]  OpCodeHandle   Handle to the buffer of opcodes.
 958   @param[in]  FormId         Destination Form ID
 959   @param[in]  Prompt         String ID for Prompt
 960   @param[in]  Help           String ID for Help
 961   @param[in]  QuestionFlags  Flags in Question Header
 962   @param[in]  QuestionId     Question ID
 963
 964   @retval NULL   There is not enough space left in Buffer to add the opcode.
 965   @retval Other  A pointer to the created opcode.
 966
 967 **/
 968 UINT8 *
 969 EFIAPI
 970 HiiCreateGotoOpCode (
 971   IN VOID             *OpCodeHandle,
 972   IN EFI_FORM_ID      FormId,
 973   IN EFI_STRING_ID    Prompt,
 974   IN EFI_STRING_ID    Help,
 975   IN UINT8            QuestionFlags,
 976   IN EFI_QUESTION_ID  QuestionId
 977   );
 978
 979 /**
 980   Create EFI_IFR_CHECKBOX_OP opcode.
 981
 982   If OpCodeHandle is NULL, then ASSERT().
 983   If any reserved bits are set in QuestionFlags, then ASSERT().
 984   If any reserved bits are set in CheckBoxFlags, then ASSERT().
 985
 986   @param[in]  OpCodeHandle          Handle to the buffer of opcodes.
 987   @param[in]  QuestionId            Question ID
 988   @param[in]  VarStoreId            Storage ID
 989   @param[in]  VarOffset             Offset in Storage
 990   @param[in]  Prompt                String ID for Prompt
 991   @param[in]  Help                  String ID for Help
 992   @param[in]  QuestionFlags         Flags in Question Header
 993   @param[in]  CheckBoxFlags         Flags for checkbox opcode
 994   @param[in]  DefaultsOpCodeHandle  Handle for a buffer of DEFAULT opcodes.  This
 995                                     is an optional parameter that may be NULL.
 996
 997   @retval NULL   There is not enough space left in Buffer to add the opcode.
 998   @retval Other  A pointer to the created opcode.
 999
1000 **/
1001 UINT8 *
1002 EFIAPI
1003 HiiCreateCheckBoxOpCode (
1004   IN VOID             *OpCodeHandle,
1005   IN EFI_QUESTION_ID  QuestionId,
1006   IN EFI_VARSTORE_ID  VarStoreId,
1007   IN UINT16           VarOffset,
1008   IN EFI_STRING_ID    Prompt,
1009   IN EFI_STRING_ID    Help,
1010   IN UINT8            QuestionFlags,
1011   IN UINT8            CheckBoxFlags,
1012   IN VOID             *DefaultsOpCodeHandle  OPTIONAL
1013   );
1014
1015 /**
1016   Create EFI_IFR_NUMERIC_OP opcode.
1017
1018   If OpCodeHandle is NULL, then ASSERT().
1019   If any reserved bits are set in QuestionFlags, then ASSERT().
1020   If any reserved bits are set in NumericFlags, then ASSERT().
1021
1022   @param[in]  OpCodeHandle          Handle to the buffer of opcodes.
1023   @param[in]  QuestionId            Question ID
1024   @param[in]  VarStoreId            Storage ID
1025   @param[in]  VarOffset             Offset in Storage
1026   @param[in]  Prompt                String ID for Prompt
1027   @param[in]  Help                  String ID for Help
1028   @param[in]  QuestionFlags         Flags in Question Header
1029   @param[in]  NumericFlags          Flags for numeric opcode
1030   @param[in]  Minimum               Numeric minimum value
1031   @param[in]  Maximum               Numeric maximum value
1032   @param[in]  Step                  Numeric step for edit
1033   @param[in]  DefaultsOpCodeHandle  Handle for a buffer of DEFAULT opcodes.  This
1034                                     is an optional parameter that may be NULL.
1035
1036   @retval NULL   There is not enough space left in Buffer to add the opcode.
1037   @retval Other  A pointer to the created opcode.
1038
1039 **/
1040 UINT8 *
1041 EFIAPI
1042 HiiCreateNumericOpCode (
1043   IN VOID             *OpCodeHandle,
1044   IN EFI_QUESTION_ID  QuestionId,
1045   IN EFI_VARSTORE_ID  VarStoreId,
1046   IN UINT16           VarOffset,
1047   IN EFI_STRING_ID    Prompt,
1048   IN EFI_STRING_ID    Help,
1049   IN UINT8            QuestionFlags,
1050   IN UINT8            NumericFlags,
1051   IN UINT64           Minimum,
1052   IN UINT64           Maximum,
1053   IN UINT64           Step,
1054   IN VOID             *DefaultsOpCodeHandle  OPTIONAL
1055   );
1056
1057 /**
1058   Create EFI_IFR_STRING_OP opcode.
1059
1060   If OpCodeHandle is NULL, then ASSERT().
1061   If any reserved bits are set in QuestionFlags, then ASSERT().
1062   If any reserved bits are set in StringFlags, then ASSERT().
1063
1064   @param[in]  OpCodeHandle          Handle to the buffer of opcodes.
1065   @param[in]  QuestionId            Question ID
1066   @param[in]  VarStoreId            Storage ID
1067   @param[in]  VarOffset             Offset in Storage
1068   @param[in]  Prompt                String ID for Prompt
1069   @param[in]  Help                  String ID for Help
1070   @param[in]  QuestionFlags         Flags in Question Header
1071   @param[in]  StringFlags           Flags for string opcode
1072   @param[in]  MinSize               String minimum length
1073   @param[in]  MaxSize               String maximum length
1074   @param[in]  DefaultsOpCodeHandle  Handle for a buffer of DEFAULT opcodes.  This
1075                                     is an optional parameter that may be NULL.
1076
1077   @retval NULL   There is not enough space left in Buffer to add the opcode.
1078   @retval Other  A pointer to the created opcode.
1079
1080 **/
1081 UINT8 *
1082 EFIAPI
1083 HiiCreateStringOpCode (
1084   IN VOID             *OpCodeHandle,
1085   IN EFI_QUESTION_ID  QuestionId,
1086   IN EFI_VARSTORE_ID  VarStoreId,
1087   IN UINT16           VarOffset,
1088   IN EFI_STRING_ID    Prompt,
1089   IN EFI_STRING_ID    Help,
1090   IN UINT8            QuestionFlags,
1091   IN UINT8            StringFlags,
1092   IN UINT8            MinSize,
1093   IN UINT8            MaxSize,
1094   IN VOID             *DefaultsOpCodeHandle  OPTIONAL
1095   );
1096
1097 /**
1098   Create EFI_IFR_ONE_OF_OP opcode.
1099
1100   If OpCodeHandle is NULL, then ASSERT().
1101   If any reserved bits are set in QuestionFlags, then ASSERT().
1102   If any reserved bits are set in OneOfFlags, then ASSERT().
1103
1104   @param[in]  OpCodeHandle          Handle to the buffer of opcodes.
1105   @param[in]  QuestionId            Question ID
1106   @param[in]  VarStoreId            Storage ID
1107   @param[in]  VarOffset             Offset in Storage
1108   @param[in]  Prompt                String ID for Prompt
1109   @param[in]  Help                  String ID for Help
1110   @param[in]  QuestionFlags         Flags in Question Header
1111   @param[in]  OneOfFlags            Flags for oneof opcode
1112   @param[in]  OptionsOpCodeHandle   Handle for a buffer of ONE_OF_OPTION opcodes.
1113   @param[in]  DefaultsOpCodeHandle  Handle for a buffer of DEFAULT opcodes.  This
1114                                     is an optional parameter that may be NULL.
1115
1116   @retval NULL   There is not enough space left in Buffer to add the opcode.
1117   @retval Other  A pointer to the created opcode.
1118
1119 **/
1120 UINT8 *
1121 EFIAPI
1122 HiiCreateOneOfOpCode (
1123   IN VOID             *OpCodeHandle,
1124   IN EFI_QUESTION_ID  QuestionId,
1125   IN EFI_VARSTORE_ID  VarStoreId,
1126   IN UINT16           VarOffset,
1127   IN EFI_STRING_ID    Prompt,
1128   IN EFI_STRING_ID    Help,
1129   IN UINT8            QuestionFlags,
1130   IN UINT8            OneOfFlags,
1131   IN VOID             *OptionsOpCodeHandle,
1132   IN VOID             *DefaultsOpCodeHandle  OPTIONAL
1133   );
1134
1135 /**
1136   Create EFI_IFR_ORDERED_LIST_OP opcode.
1137
1138   If OpCodeHandle is NULL, then ASSERT().
1139   If any reserved bits are set in QuestionFlags, then ASSERT().
1140   If any reserved bits are set in OrderedListFlags, then ASSERT().
1141
1142   @param[in]  OpCodeHandle          Handle to the buffer of opcodes.
1143   @param[in]  QuestionId            Question ID
1144   @param[in]  VarStoreId            Storage ID
1145   @param[in]  VarOffset             Offset in Storage
1146   @param[in]  Prompt                String ID for Prompt
1147   @param[in]  Help                  String ID for Help
1148   @param[in]  QuestionFlags         Flags in Question Header
1149   @param[in]  OrderedListFlags      Flags for ordered list opcode
1150   @param[in]  DataType              Type for option value
1151   @param[in]  MaxContainers         Maximum count for options in this ordered list
1152   @param[in]  OptionsOpCodeHandle   Handle for a buffer of ONE_OF_OPTION opcodes.
1153   @param[in]  DefaultsOpCodeHandle  Handle for a buffer of DEFAULT opcodes.  This
1154                                     is an optional parameter that may be NULL.
1155
1156   @retval NULL   There is not enough space left in Buffer to add the opcode.
1157   @retval Other  A pointer to the created opcode.
1158
1159 **/
1160 UINT8 *
1161 EFIAPI
1162 HiiCreateOrderedListOpCode (
1163   IN VOID             *OpCodeHandle,
1164   IN EFI_QUESTION_ID  QuestionId,
1165   IN EFI_VARSTORE_ID  VarStoreId,
1166   IN UINT16           VarOffset,
1167   IN EFI_STRING_ID    Prompt,
1168   IN EFI_STRING_ID    Help,
1169   IN UINT8            QuestionFlags,
1170   IN UINT8            OrderedListFlags,
1171   IN UINT8            DataType,
1172   IN UINT8            MaxContainers,
1173   IN VOID             *OptionsOpCodeHandle,
1174   IN VOID             *DefaultsOpCodeHandle  OPTIONAL
1175   );
1176
1177 /**
1178   This function updates a form that has previously been registered with the HII
1179   Database.  This function will perform at most one update operation.
1180
1181   The form to update is specified by Handle, FormSetGuid, and FormId.  Binary
1182   comparisons of IFR opcodes are performed from the beginning of the form being
1183   updated until an IFR opcode is found that exactly matches the first IFR opcode
1184   specifed by StartOpCodeHandle.  The following rules are used to determine if
1185   an insert, replace, or delete operation is performed.
1186
1187   1) If no matches are found, then NULL is returned.
1188   2) If a match is found, and EndOpCodeHandle is NULL, then all of the IFR opcodes
1189      from StartOpcodeHandle except the first opcode are inserted immediately after
1190      the matching IFR opcode in the form beng updated.
1191   3) If a match is found, and EndOpCodeHandle is not NULL, then a search is made
1192      from the matching IFR opcode until an IFR opcode exatly matches the first
1193      IFR opcode specified by EndOpCodeHandle.  If no match is found for the first
1194      IFR opcode specified by EndOpCodeHandle, then NULL is returned.  If a match
1195      is found, then all of the IFR opcodes between the start match and the end
1196      match are deleted from the form being updated and all of the IFR opcodes
1197      from StartOpcodeHandle except the first opcode are inserted immediately after
1198      the matching start IFR opcode.  If StartOpCcodeHandle only contains one
1199      IFR instruction, then the result of ths operation will delete all of the IFR
1200      opcodes between the start end matches.
1201
1202   If HiiHandle is NULL, then ASSERT().
1203   If StartOpCodeHandle is NULL, then ASSERT().
1204
1205   @param[in]  HiiHandle          The HII Handle of the form to update.
1206   @param[in]  FormSetGuid        The Formset GUID of the form to update.  This
1207                                  is an optional parameter that may be NULL.
1208                                  If it is NULL, all FormSet will be updated.
1209   @param[in]  FormId             The ID of the form to update.
1210   @param[in]  StartOpCodeHandle  An OpCode Handle that contains the set of IFR
1211                                  opcodes to be inserted or replaced in the form.
1212                                  The first IFR instruction in StartOpCodeHandle
1213                                  is used to find matching IFR opcode in the
1214                                  form.
1215   @param[in]  EndOpCodeHandle    An OpCcode Handle that contains the IFR opcode
1216                                  that marks the end of a replace operation in
1217                                  the form.  This is an optional parameter that
1218                                  may be NULL.  If it is NULL, then an the IFR
1219                                  opcodes specified by StartOpCodeHandle are
1220                                  inserted into the form.
1221
1222   @retval EFI_OUT_OF_RESOURCES   No enough memory resource is allocated.
1223   @retval EFI_NOT_FOUND          The following cases will return EFI_NOT_FOUND.
1224                                  1) The form specified by HiiHandle, FormSetGuid,
1225                                  and FormId could not be found in the HII Database.
1226                                  2) No IFR opcodes in the target form match the first
1227                                  IFR opcode in StartOpCodeHandle.
1228                                  3) EndOpCOde is not NULL, and no IFR opcodes in the
1229                                  target form following a matching start opcode match
1230                                  the first IFR opcode in EndOpCodeHandle.
1231   @retval EFI_SUCCESS            The matched form is updated by StartOpcode.
1232
1233 **/
1234 EFI_STATUS
1235 EFIAPI
1236 HiiUpdateForm (
1237   IN EFI_HII_HANDLE  HiiHandle,
1238   IN EFI_GUID        *FormSetGuid,        OPTIONAL
1239   IN EFI_FORM_ID     FormId,
1240   IN VOID            *StartOpcodeHandle,
1241   IN VOID            *EndOpcodeHandle     OPTIONAL
1242   );
1243
1244 /**
1245   Configure the buffer accrording to ConfigBody strings in the format of
1246   <Length:4 bytes>, <Offset: 2 bytes>, <Width:2 bytes>, <Data:n bytes>.
1247   This ConfigBody strings is generated by EDKII UEFI VfrCompiler for the default
1248   values in a Form Set. The name of the ConfigBody strings is VfrMyIfrNVDataDefault0000
1249   constructed following this rule:
1250    "Vfr" + varstore.name + "Default" + defaultstore.attributes.
1251   Check the generated C file in Output for details.
1252
1253   @param  Buffer                 the start address of buffer.
1254   @param  BufferSize             the size of buffer.
1255   @param  Number                 the number of the ConfigBody strings.
1256   @param  ...                    the ConfigBody strings
1257
1258   @retval EFI_BUFFER_TOO_SMALL   the BufferSize is too small to operate.
1259   @retval EFI_INVALID_PARAMETER  Buffer is NULL or BufferSize is 0.
1260   @retval EFI_SUCCESS            Operation successful.
1261
1262 **/
1263 EFI_STATUS
1264 EFIAPI
1265 HiiIfrLibExtractDefault(
1266   IN VOID                         *Buffer,
1267   IN UINTN                        *BufferSize,
1268   UINTN                           Number,
1269   ...
1270   );
1271
1272 #endif