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