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