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