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.
 361
 362   @param[in]  VariableName  Pointer to a Null-terminated Unicode string.  This
 363                             is an optional parameter that may be NULL.
 364   @param[in]  VariableGuid  Pointer to an EFI_GUID structure.  This is an optional
 365                             parameter that may be NULL.
 366   @param[in]  BufferSize    Length in bytes of buffer to hold retrived data.
 367   @param[out] Block         Buffer of data to be updated.
 368
 369   @retval FALSE  The uncommitted data could not be retrieved.
 370   @retval TRUE   The uncommitted data was retrieved.
 371
 372 **/
 373 BOOLEAN
 374 EFIAPI
 375 HiiGetBrowserData (
 376   IN CONST EFI_GUID  *VariableGuid,  OPTIONAL
 377   IN CONST CHAR16    *VariableName,  OPTIONAL
 378   IN UINTN           BlockSize,
 379   OUT UINT8          *Block
 380   );
 381
 382 /**
 383   Updates uncommitted data in the Form Browser.
 384
 385   If Buffer is NULL, then ASSERT().
 386
 387   @param[in]  VariableName    Pointer to a Null-terminated Unicode string.  This
 388                               is an optional parameter that may be NULL.
 389   @param[in]  VariableGuid    Pointer to an EFI_GUID structure.  This is an optional
 390                               parameter that may be NULL.
 391   @param[in]  BufferSize      Length, in bytes, of Buffer.
 392   @param[in]  Buffer          Buffer of data to commit.
 393   @param[in]  RequestElement  An optional field to specify which part of the
 394                               buffer data will be send back to Browser. If NULL,
 395                               the whole buffer of data will be committed to
 396                               Browser.
 397                               <RequestElement> ::= &OFFSET=<Number>&WIDTH=<Number>*
 398
 399   @retval FALSE  The uncommitted data could not be updated.
 400   @retval TRUE   The uncommitted data was updated.
 401
 402 **/
 403 BOOLEAN
 404 EFIAPI
 405 HiiSetBrowserData (
 406   IN CONST EFI_GUID  *VariableGuid, OPTIONAL
 407   IN CONST CHAR16    *VariableName, OPTIONAL
 408   IN UINTN           BufferSize,
 409   IN CONST UINT8     *Buffer,
 410   IN CONST CHAR16    *RequestElement  OPTIONAL
 411   );
 412
 413 /////////////////////////////////////////
 414 /////////////////////////////////////////
 415 /// IFR Functions
 416 /////////////////////////////////////////
 417 /////////////////////////////////////////
 418
 419 /**
 420   Returns a UINT64 value that contains bitfields for Hour, Minute, and Second.
 421   The lower 8-bits of Hour are placed in bits 0..7.  The lower 8-bits of Minute
 422   are placed in bits 8..15, and the lower 8-bits of Second are placed in bits
 423   16..23.  This format is selected because it can be easily translated to
 424   an EFI_HII_TIME structure in an EFI_IFR_TYPE_VALUE union.
 425
 426   @param  Hour    The hour value to be encoded.
 427   @param  Minute  The miniute value to be encoded.
 428   @param  Second  The second value to be encoded.
 429
 430   @return A 64-bit containing Hour, Minute, and Second.
 431 **/
 432 #define EFI_HII_TIME_UINT64(Hour, Minute, Second) \
 433   (UINT64)((Hour & 0xff) | ((Minute & 0xff) << 8) | ((Second & 0xff) << 16))
 434
 435 /**
 436   Returns a UINT64 value that contains bitfields for Year, Month, and Day.
 437   The lower 16-bits of Year are placed in bits 0..15.  The lower 8-bits of Month
 438   are placed in bits 16..23, and the lower 8-bits of Day are placed in bits
 439   24..31.  This format is selected because it can be easily translated to
 440   an EFI_HII_DATE structure in an EFI_IFR_TYPE_VALUE union.
 441
 442   @param  Year   The year value to be encoded.
 443   @param  Month  The month value to be encoded.
 444   @param  Day    The day value to be encoded.
 445
 446   @return A 64-bit containing Year, Month, and Day.
 447 **/
 448 #define EFI_HII_DATE_UINT64(Year, Month, Day) \
 449   (UINT64)((Year & 0xffff) | ((Month & 0xff) << 16) | ((Day & 0xff) << 24))
 450
 451 /**
 452   Allocates and returns a new OpCode Handle.  OpCode Handles must be freed with
 453   HiiFreeOpCodeHandle().
 454
 455   @retval NULL   There are not enough resources to allocate a new OpCode Handle.
 456   @retval Other  A new OpCode handle.
 457
 458 **/
 459 VOID *
 460 EFIAPI
 461 HiiAllocateOpCodeHandle (
 462   VOID
 463   );
 464
 465 /**
 466   Frees an OpCode Handle that was peviously allocated with HiiAllocateOpCodeHandle().
 467   When an OpCode Handle is freed, all of the opcodes associated with the OpCode
 468   Handle are also freed.
 469
 470   If OpCodeHandle is NULL, then ASSERT().
 471
 472 **/
 473 VOID
 474 EFIAPI
 475 HiiFreeOpCodeHandle (
 476   VOID  *OpCodeHandle
 477   );
 478
 479 /**
 480   Create EFI_IFR_END_OP opcode.
 481
 482   If OpCodeHandle is NULL, then ASSERT().
 483
 484   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 485
 486   @retval NULL   There is not enough space left in Buffer to add the opcode.
 487   @retval Other  A pointer to the created opcode.
 488
 489 **/
 490 UINT8 *
 491 EFIAPI
 492 HiiCreateEndOpCode (
 493   IN VOID  *OpCodeHandle
 494   );
 495
 496 /**
 497   Create EFI_IFR_ONE_OF_OPTION_OP opcode.
 498
 499   If OpCodeHandle is NULL, then ASSERT().
 500   If Type is invalid, then ASSERT().
 501   If Flags is invalid, then ASSERT().
 502
 503   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 504   @param[in]  StringId      StringId for the option
 505   @param[in]  Flags         Flags for the option
 506   @param[in]  Type          Type for the option
 507   @param[in]  Value         Value for the option
 508
 509   @retval NULL   There is not enough space left in Buffer to add the opcode.
 510   @retval Other  A pointer to the created opcode.
 511
 512 **/
 513 UINT8 *
 514 EFIAPI
 515 HiiCreateOneOfOptionOpCode (
 516   IN VOID    *OpCodeHandle,
 517   IN UINT16  StringId,
 518   IN UINT8   Flags,
 519   IN UINT8   Type,
 520   IN UINT64  Value
 521   );
 522
 523 /**
 524   Create EFI_IFR_DEFAULT_OP opcode.
 525
 526   If OpCodeHandle is NULL, then ASSERT().
 527   If Type is invalid, then ASSERT().
 528
 529   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 530   @param[in]  DefaultId     DefaultId for the default
 531   @param[in]  Type          Type for the default
 532   @param[in]  Value         Value for the default
 533
 534   @retval NULL   There is not enough space left in Buffer to add the opcode.
 535   @retval Other  A pointer to the created opcode.
 536
 537 **/
 538 UINT8 *
 539 EFIAPI
 540 HiiCreateDefaultOpCode (
 541   IN VOID    *OpCodeHandle,
 542   IN UINT16  DefaultId,
 543   IN UINT8   Type,
 544   IN UINT64  Value
 545   );
 546
 547 /**
 548   Create EFI_IFR_GUID opcode.
 549
 550   If OpCodeHandle is NULL, then ASSERT().
 551   If Guid is NULL, then ASSERT().
 552   If OpCodeSize < sizeof (EFI_IFR_GUID), then ASSERT().
 553
 554   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 555   @param[in]  Guid          Pointer to EFI_GUID of this guided opcode.
 556   @param[in]  GuidOpCode    Pointer to an EFI_IFR_GUID opcode.  This is an
 557                             optional parameter that may be NULL.  If this
 558                             parameter is NULL, then the GUID extension
 559                             region of the created opcode is filled with zeros.
 560                             If this parameter is not NULL, then the GUID
 561                             extension region of GuidData will be copied to
 562                             the GUID extension region of the created opcode.
 563   @param[in]  OpCodeSize    The size, in bytes, of created opcode.  This value
 564                             must be >= sizeof(EFI_IFR_GUID).
 565
 566   @retval NULL   There is not enough space left in Buffer to add the opcode.
 567   @retval Other  A pointer to the created opcode.
 568
 569 **/
 570 UINT8 *
 571 EFIAPI
 572 HiiCreateGuidOpCode (
 573   IN VOID            *OpCodeHandle,
 574   IN CONST EFI_GUID  *Guid,
 575   IN CONST VOID      *GuidOpCode,    OPTIONAL
 576   IN UINTN           OpCodeSize
 577   );
 578
 579 /**
 580   Create EFI_IFR_ACTION_OP opcode.
 581
 582   If OpCodeHandle is NULL, then ASSERT().
 583   If any reserved bits are set in QuestionFlags, then ASSERT().
 584
 585   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 586   @param[in]  QuestionId      Question ID
 587   @param[in]  Prompt          String ID for Prompt
 588   @param[in]  Help            String ID for Help
 589   @param[in]  QuestionFlags   Flags in Question Header
 590   @param[in]  QuestionConfig  String ID for configuration
 591
 592   @retval NULL   There is not enough space left in Buffer to add the opcode.
 593   @retval Other  A pointer to the created opcode.
 594
 595 **/
 596 UINT8 *
 597 EFIAPI
 598 HiiCreateActionOpCode (
 599   IN VOID             *OpCodeHandle,
 600   IN EFI_QUESTION_ID  QuestionId,
 601   IN EFI_STRING_ID    Prompt,
 602   IN EFI_STRING_ID    Help,
 603   IN UINT8            QuestionFlags,
 604   IN EFI_STRING_ID    QuestionConfig
 605   );
 606
 607 /**
 608   Create EFI_IFR_SUBTITLE_OP opcode.
 609
 610   If OpCodeHandle is NULL, then ASSERT().
 611   If any reserved bits are set in Flags, then ASSERT().
 612   If Scope > 1, then ASSERT().
 613
 614   @param[in]  OpCodeHandle  Handle to the buffer of opcodes.
 615   @param[in]  Prompt      String ID for Prompt
 616   @param[in]  Help        String ID for Help
 617   @param[in]  Flags       Subtitle opcode flags
 618   @param[in]  Scope       1 if this opcpde is the beginning of a new scope.
 619                           0 if this opcode is within the current scope.
 620
 621   @retval NULL   There is not enough space left in Buffer to add the opcode.
 622   @retval Other  A pointer to the created opcode.
 623
 624 **/
 625 UINT8 *
 626 EFIAPI
 627 HiiCreateSubTitleOpCode (
 628   IN VOID           *OpCodeHandle,
 629   IN EFI_STRING_ID  Prompt,
 630   IN EFI_STRING_ID  Help,
 631   IN UINT8          Flags,
 632   IN UINT8          Scope
 633   );
 634
 635 /**
 636   Create EFI_IFR_REF_OP opcode.
 637
 638   If OpCodeHandle is NULL, then ASSERT().
 639   If any reserved bits are set in QuestionFlags, then ASSERT().
 640
 641   @param[in]  OpCodeHandle   Handle to the buffer of opcodes.
 642   @param[in]  FormId         Destination Form ID
 643   @param[in]  Prompt         String ID for Prompt
 644   @param[in]  Help           String ID for Help
 645   @param[in]  QuestionFlags  Flags in Question Header
 646   @param[in]  QuestionId     Question ID
 647
 648   @retval NULL   There is not enough space left in Buffer to add the opcode.
 649   @retval Other  A pointer to the created opcode.
 650
 651 **/
 652 UINT8 *
 653 EFIAPI
 654 HiiCreateGotoOpCode (
 655   IN VOID             *OpCodeHandle,
 656   IN EFI_FORM_ID      FormId,
 657   IN EFI_STRING_ID    Prompt,
 658   IN EFI_STRING_ID    Help,
 659   IN UINT8            QuestionFlags,
 660   IN EFI_QUESTION_ID  QuestionId
 661   );
 662
 663 /**
 664   Create EFI_IFR_CHECKBOX_OP opcode.
 665
 666   If OpCodeHandle is NULL, then ASSERT().
 667   If any reserved bits are set in QuestionFlags, then ASSERT().
 668   If any reserved bits are set in CheckBoxFlags, then ASSERT().
 669
 670   @param[in]  OpCodeHandle          Handle to the buffer of opcodes.
 671   @param[in]  QuestionId            Question ID
 672   @param[in]  VarStoreId            Storage ID
 673   @param[in]  VarOffset             Offset in Storage
 674   @param[in]  Prompt                String ID for Prompt
 675   @param[in]  Help                  String ID for Help
 676   @param[in]  QuestionFlags         Flags in Question Header
 677   @param[in]  CheckBoxFlags         Flags for checkbox opcode
 678   @param[in]  DefaultsOpCodeHandle  Handle for a buffer of DEFAULT opcodes.  This
 679                                     is an optional parameter that may be NULL.
 680
 681   @retval NULL   There is not enough space left in Buffer to add the opcode.
 682   @retval Other  A pointer to the created opcode.
 683
 684 **/
 685 UINT8 *
 686 EFIAPI
 687 HiiCreateCheckBoxOpCode (
 688   IN VOID             *OpCodeHandle,
 689   IN EFI_QUESTION_ID  QuestionId,
 690   IN EFI_VARSTORE_ID  VarStoreId,
 691   IN UINT16           VarOffset,
 692   IN EFI_STRING_ID    Prompt,
 693   IN EFI_STRING_ID    Help,
 694   IN UINT8            QuestionFlags,
 695   IN UINT8            CheckBoxFlags,
 696   IN VOID             *DefaultsOpCodeHandle  OPTIONAL
 697   );
 698
 699 /**
 700   Create EFI_IFR_NUMERIC_OP opcode.
 701
 702   If OpCodeHandle is NULL, then ASSERT().
 703   If any reserved bits are set in QuestionFlags, then ASSERT().
 704   If any reserved bits are set in NumericFlags, then ASSERT().
 705
 706   @param[in]  OpCodeHandle          Handle to the buffer of opcodes.
 707   @param[in]  QuestionId            Question ID
 708   @param[in]  VarStoreId            Storage ID
 709   @param[in]  VarOffset             Offset in Storage
 710   @param[in]  Prompt                String ID for Prompt
 711   @param[in]  Help                  String ID for Help
 712   @param[in]  QuestionFlags         Flags in Question Header
 713   @param[in]  NumericFlags          Flags for numeric opcode
 714   @param[in]  Minimum               Numeric minimum value
 715   @param[in]  Maximum               Numeric maximum value
 716   @param[in]  Step                  Numeric step for edit
 717   @param[in]  DefaultsOpCodeHandle  Handle for a buffer of DEFAULT opcodes.  This
 718                                     is an optional parameter that may be NULL.
 719
 720   @retval NULL   There is not enough space left in Buffer to add the opcode.
 721   @retval Other  A pointer to the created opcode.
 722
 723 **/
 724 UINT8 *
 725 EFIAPI
 726 HiiCreateNumericOpCode (
 727   IN VOID             *OpCodeHandle,
 728   IN EFI_QUESTION_ID  QuestionId,
 729   IN EFI_VARSTORE_ID  VarStoreId,
 730   IN UINT16           VarOffset,
 731   IN EFI_STRING_ID    Prompt,
 732   IN EFI_STRING_ID    Help,
 733   IN UINT8            QuestionFlags,
 734   IN UINT8            NumericFlags,
 735   IN UINT64           Minimum,
 736   IN UINT64           Maximum,
 737   IN UINT64           Step,
 738   IN VOID             *DefaultsOpCodeHandle  OPTIONAL
 739   );
 740
 741 /**
 742   Create EFI_IFR_STRING_OP opcode.
 743
 744   If OpCodeHandle is NULL, then ASSERT().
 745   If any reserved bits are set in QuestionFlags, then ASSERT().
 746   If any reserved bits are set in StringFlags, then ASSERT().
 747
 748   @param[in]  OpCodeHandle          Handle to the buffer of opcodes.
 749   @param[in]  QuestionId            Question ID
 750   @param[in]  VarStoreId            Storage ID
 751   @param[in]  VarOffset             Offset in Storage
 752   @param[in]  Prompt                String ID for Prompt
 753   @param[in]  Help                  String ID for Help
 754   @param[in]  QuestionFlags         Flags in Question Header
 755   @param[in]  StringFlags           Flags for string opcode
 756   @param[in]  MinSize               String minimum length
 757   @param[in]  MaxSize               String maximum length
 758   @param[in]  DefaultsOpCodeHandle  Handle for a buffer of DEFAULT opcodes.  This
 759                                     is an optional parameter that may be NULL.
 760
 761   @retval NULL   There is not enough space left in Buffer to add the opcode.
 762   @retval Other  A pointer to the created opcode.
 763
 764 **/
 765 UINT8 *
 766 EFIAPI
 767 HiiCreateStringOpCode (
 768   IN VOID             *OpCodeHandle,
 769   IN EFI_QUESTION_ID  QuestionId,
 770   IN EFI_VARSTORE_ID  VarStoreId,
 771   IN UINT16           VarOffset,
 772   IN EFI_STRING_ID    Prompt,
 773   IN EFI_STRING_ID    Help,
 774   IN UINT8            QuestionFlags,
 775   IN UINT8            StringFlags,
 776   IN UINT8            MinSize,
 777   IN UINT8            MaxSize,
 778   IN VOID             *DefaultsOpCodeHandle  OPTIONAL
 779   );
 780
 781 /**
 782   Create EFI_IFR_ONE_OF_OP opcode.
 783
 784   If OpCodeHandle is NULL, then ASSERT().
 785   If any reserved bits are set in QuestionFlags, then ASSERT().
 786   If any reserved bits are set in OneOfFlags, then ASSERT().
 787
 788   @param[in]  OpCodeHandle          Handle to the buffer of opcodes.
 789   @param[in]  QuestionId            Question ID
 790   @param[in]  VarStoreId            Storage ID
 791   @param[in]  VarOffset             Offset in Storage
 792   @param[in]  Prompt                String ID for Prompt
 793   @param[in]  Help                  String ID for Help
 794   @param[in]  QuestionFlags         Flags in Question Header
 795   @param[in]  OneOfFlags            Flags for oneof opcode
 796   @param[in]  OptionsOpCodeHandle   Handle for a buffer of ONE_OF_OPTION opcodes.
 797   @param[in]  DefaultsOpCodeHandle  Handle for a buffer of DEFAULT opcodes.  This
 798                                     is an optional parameter that may be NULL.
 799
 800   @retval NULL   There is not enough space left in Buffer to add the opcode.
 801   @retval Other  A pointer to the created opcode.
 802
 803 **/
 804 UINT8 *
 805 EFIAPI
 806 HiiCreateOneOfOpCode (
 807   IN VOID             *OpCodeHandle,
 808   IN EFI_QUESTION_ID  QuestionId,
 809   IN EFI_VARSTORE_ID  VarStoreId,
 810   IN UINT16           VarOffset,
 811   IN EFI_STRING_ID    Prompt,
 812   IN EFI_STRING_ID    Help,
 813   IN UINT8            QuestionFlags,
 814   IN UINT8            OneOfFlags,
 815   IN VOID             *OptionsOpCodeHandle,
 816   IN VOID             *DefaultsOpCodeHandle  OPTIONAL
 817   );
 818
 819 /**
 820   Create EFI_IFR_ORDERED_LIST_OP opcode.
 821
 822   If OpCodeHandle is NULL, then ASSERT().
 823   If any reserved bits are set in QuestionFlags, then ASSERT().
 824   If any reserved bits are set in OrderedListFlags, then ASSERT().
 825
 826   @param[in]  OpCodeHandle          Handle to the buffer of opcodes.
 827   @param[in]  QuestionId            Question ID
 828   @param[in]  VarStoreId            Storage ID
 829   @param[in]  VarOffset             Offset in Storage
 830   @param[in]  Prompt                String ID for Prompt
 831   @param[in]  Help                  String ID for Help
 832   @param[in]  QuestionFlags         Flags in Question Header
 833   @param[in]  OrderedListFlags      Flags for ordered list opcode
 834   @param[in]  DataType              Type for option value
 835   @param[in]  MaxContainers         Maximum count for options in this ordered list
 836   @param[in]  OptionsOpCodeHandle   Handle for a buffer of ONE_OF_OPTION opcodes.
 837   @param[in]  DefaultsOpCodeHandle  Handle for a buffer of DEFAULT opcodes.  This
 838                                     is an optional parameter that may be NULL.
 839
 840   @retval NULL   There is not enough space left in Buffer to add the opcode.
 841   @retval Other  A pointer to the created opcode.
 842
 843 **/
 844 UINT8 *
 845 EFIAPI
 846 HiiCreateOrderedListOpCode (
 847   IN VOID             *OpCodeHandle,
 848   IN EFI_QUESTION_ID  QuestionId,
 849   IN EFI_VARSTORE_ID  VarStoreId,
 850   IN UINT16           VarOffset,
 851   IN EFI_STRING_ID    Prompt,
 852   IN EFI_STRING_ID    Help,
 853   IN UINT8            QuestionFlags,
 854   IN UINT8            OrderedListFlags,
 855   IN UINT8            DataType,
 856   IN UINT8            MaxContainers,
 857   IN VOID             *OptionsOpCodeHandle,
 858   IN VOID             *DefaultsOpCodeHandle  OPTIONAL
 859   );
 860
 861 /**
 862   This function updates a form that has previously been registered with the HII
 863   Database.  This function will perform at most one update operation.
 864
 865   The form to update is specified by Handle, FormSetGuid, and FormId.  Binary
 866   comparisons of IFR opcodes are performed from the beginning of the form being
 867   updated until an IFR opcode is found that exactly matches the first IFR opcode
 868   specifed by StartOpCodeHandle.  The following rules are used to determine if
 869   an insert, replace, or delete operation is performed.
 870
 871   1) If no matches are found, then NULL is returned.
 872   2) If a match is found, and EndOpCodeHandle is NULL, then all of the IFR opcodes
 873      from StartOpcodeHandle except the first opcode are inserted immediately after
 874      the matching IFR opcode in the form beng updated.
 875   3) If a match is found, and EndOpCodeHandle is not NULL, then a search is made
 876      from the matching IFR opcode until an IFR opcode exatly matches the first
 877      IFR opcode specified by EndOpCodeHandle.  If no match is found for the first
 878      IFR opcode specified by EndOpCodeHandle, then NULL is returned.  If a match
 879      is found, then all of the IFR opcodes between the start match and the end
 880      match are deleted from the form being updated and all of the IFR opcodes
 881      from StartOpcodeHandle except the first opcode are inserted immediately after
 882      the matching start IFR opcode.  If StartOpCcodeHandle only contains one
 883      IFR instruction, then the result of ths operation will delete all of the IFR
 884      opcodes between the start end matches.
 885
 886   If HiiHandle is NULL, then ASSERT().
 887   If StartOpCodeHandle is NULL, then ASSERT().
 888
 889   @param[in]  HiiHandle          The HII Handle of the form to update.
 890   @param[in]  FormSetGuid        The Formset GUID of the form to update.  This
 891                                  is an optional parameter that may be NULL.
 892                                  If it is NULL, all FormSet will be updated.
 893   @param[in]  FormId             The ID of the form to update.
 894   @param[in]  StartOpCodeHandle  An OpCode Handle that contains the set of IFR
 895                                  opcodes to be inserted or replaced in the form.
 896                                  The first IFR instruction in StartOpCodeHandle
 897                                  is used to find matching IFR opcode in the
 898                                  form.
 899   @param[in]  EndOpCodeHandle    An OpCcode Handle that contains the IFR opcode
 900                                  that marks the end of a replace operation in
 901                                  the form.  This is an optional parameter that
 902                                  may be NULL.  If it is NULL, then an the IFR
 903                                  opcodes specified by StartOpCodeHandle are
 904                                  inserted into the form.
 905
 906   @retval EFI_OUT_OF_RESOURCES   No enough memory resource is allocated.
 907   @retval EFI_NOT_FOUND          The following cases will return EFI_NOT_FOUND.
 908                                  1) The form specified by HiiHandle, FormSetGuid,
 909                                  and FormId could not be found in the HII Database.
 910                                  2) No IFR opcodes in the target form match the first
 911                                  IFR opcode in StartOpCodeHandle.
 912                                  3) EndOpCOde is not NULL, and no IFR opcodes in the
 913                                  target form following a matching start opcode match
 914                                  the first IFR opcode in EndOpCodeHandle.
 915   @retval EFI_SUCCESS            The matched form is updated by StartOpcode.
 916
 917 **/
 918 EFI_STATUS
 919 EFIAPI
 920 HiiUpdateForm (
 921   IN EFI_HII_HANDLE  HiiHandle,
 922   IN EFI_GUID        *FormSetGuid,        OPTIONAL
 923   IN EFI_FORM_ID     FormId,
 924   IN VOID            *StartOpcodeHandle,
 925   IN VOID            *EndOpcodeHandle     OPTIONAL
 926   );
 927
 928 /**
 929   Configure the buffer accrording to ConfigBody strings in the format of
 930   <Length:4 bytes>, <Offset: 2 bytes>, <Width:2 bytes>, <Data:n bytes>.
 931   This ConfigBody strings is generated by EDKII UEFI VfrCompiler for the default
 932   values in a Form Set. The name of the ConfigBody strings is VfrMyIfrNVDataDefault0000
 933   constructed following this rule:
 934    "Vfr" + varstore.name + "Default" + defaultstore.attributes.
 935   Check the generated C file in Output for details.
 936
 937   @param  Buffer                 the start address of buffer.
 938   @param  BufferSize             the size of buffer.
 939   @param  Number                 the number of the ConfigBody strings.
 940   @param  ...                    the ConfigBody strings
 941
 942   @retval EFI_BUFFER_TOO_SMALL   the BufferSize is too small to operate.
 943   @retval EFI_INVALID_PARAMETER  Buffer is NULL or BufferSize is 0.
 944   @retval EFI_SUCCESS            Operation successful.
 945
 946 **/
 947 EFI_STATUS
 948 EFIAPI
 949 HiiIfrLibExtractDefault(
 950   IN VOID                         *Buffer,
 951   IN UINTN                        *BufferSize,
 952   UINTN                           Number,
 953   ...
 954   );
 955
 956 #endif