MdeModulePkg/Include/Library/HiiLib.h

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