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