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