MdeModulePkg/Include/Library/IfrSupportLib.h

   1 /** @file
   2   This library contains functions to do IFR opcode creation and utility functions
   3   to help module to interact with a UEFI Form Browser.
   4
   5   Copyright (c) 2007 - 2008, Intel Corporation
   6   All rights reserved. This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _IFR_SUPPORT_LIBRARY_H_
  17 #define _IFR_SUPPORT_LIBRARY_H_
  18
  19
  20 #include <Protocol/HiiFont.h>
  21 #include <Protocol/HiiImage.h>
  22 #include <Protocol/HiiString.h>
  23 #include <Protocol/HiiDatabase.h>
  24 #include <Protocol/HiiConfigRouting.h>
  25 #include <Protocol/HiiConfigAccess.h>
  26 #include <Protocol/FormBrowser2.h>
  27 #include <Protocol/SimpleTextOut.h>
  28
  29 #include <Guid/GlobalVariable.h>
  30
  31 //
  32 // The architectural variable "Lang" and "LangCodes" are deprecated in UEFI
  33 // specification. While, UEFI specification also states that these deprecated
  34 // variables may be provided for backwards compatibility.
  35
  36 #define EFI_LANGUAGE_VARIABLE           L"Lang"
  37 #define EFI_LANGUAGE_CODES_VARIABLE     L"LangCodes"
  38
  39 #define UEFI_LANGUAGE_VARIABLE          L"PlatformLang"
  40 #define UEFI_LANGUAGE_CODES_VARIABLE    L"PlatformLangCodes"
  41
  42 #define INVALID_VARSTORE_ID             0
  43
  44 #define QUESTION_FLAGS              (EFI_IFR_FLAG_READ_ONLY | EFI_IFR_FLAG_CALLBACK | EFI_IFR_FLAG_RESET_REQUIRED | EFI_IFR_FLAG_OPTIONS_ONLY)
  45 #define QUESTION_FLAGS_MASK         (~QUESTION_FLAGS)
  46
  47 #pragma pack(1)
  48 typedef struct {
  49   EFI_STRING_ID       StringToken;
  50   EFI_IFR_TYPE_VALUE  Value;
  51   UINT8               Flags;
  52 } IFR_OPTION;
  53 #pragma pack()
  54
  55 typedef struct {
  56   ///
  57   /// Buffer size allocated for Data.
  58   ///
  59   UINT32                BufferSize;
  60
  61   ///
  62   /// Offset in Data to append the newly created opcode binary.
  63   /// It will be adjusted automatically in Create***OpCode(), and should be
  64   /// initialized to 0 before invocation of a serial of Create***OpCode()
  65   ///
  66   UINT32                Offset;
  67
  68   ///
  69   /// The destination buffer for created op-codes
  70   ///
  71   UINT8                 *Data;
  72 } EFI_HII_UPDATE_DATA;
  73
  74
  75 /**
  76   Create EFI_IFR_END_OP opcode.
  77
  78   If Data is NULL or Data->Data is NULL, then ASSERT.
  79
  80   @param  Data                   Destination for the created opcode binary
  81
  82   @retval EFI_SUCCESS            Opcode is created successfully.
  83   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
  84
  85 **/
  86 EFI_STATUS
  87 EFIAPI
  88 CreateEndOpCode (
  89   IN OUT EFI_HII_UPDATE_DATA *Data
  90   )
  91 ;
  92
  93 /**
  94   Create EFI_IFR_DEFAULT_OP opcode.
  95
  96   If Data is NULL or Data->Data is NULL, then ASSERT.
  97
  98   @param  Value                  Value for the default
  99   @param  Type                   Type for the default
 100   @param  Data                   Destination for the created opcode binary
 101
 102   @retval EFI_SUCCESS            Opcode is created successfully.
 103   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 104   @retval EFI_INVALID_PARAMETER The type is not valid.
 105
 106 **/
 107 EFI_STATUS
 108 EFIAPI
 109 CreateDefaultOpCode (
 110   IN     EFI_IFR_TYPE_VALUE  *Value,
 111   IN     UINT8               Type,
 112   IN OUT EFI_HII_UPDATE_DATA *Data
 113   )
 114 ;
 115
 116 /**
 117   Create EFI_IFR_ACTION_OP opcode.
 118
 119   If Data is NULL or Data->Data is NULL, then ASSERT.
 120
 121   @param  QuestionId             Question ID
 122   @param  Prompt                 String ID for Prompt
 123   @param  Help                   String ID for Help
 124   @param  QuestionFlags          Flags in Question Header
 125   @param  QuestionConfig         String ID for configuration
 126   @param  Data                   Destination for the created opcode binary
 127
 128   @retval EFI_SUCCESS            Opcode is created successfully.
 129   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 130   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 131
 132 **/
 133 EFI_STATUS
 134 EFIAPI
 135 CreateActionOpCode (
 136   IN     EFI_QUESTION_ID      QuestionId,
 137   IN     EFI_STRING_ID        Prompt,
 138   IN     EFI_STRING_ID        Help,
 139   IN     UINT8                QuestionFlags,
 140   IN     EFI_STRING_ID        QuestionConfig,
 141   IN OUT EFI_HII_UPDATE_DATA  *Data
 142   )
 143 ;
 144
 145 /**
 146   Create EFI_IFR_SUBTITLE_OP opcode.
 147
 148   If Data is NULL or Data->Data is NULL, then ASSERT.
 149
 150   @param  Prompt                 String ID for Prompt
 151   @param  Help                   String ID for Help
 152   @param  Flags                  Subtitle opcode flags
 153   @param  Scope                  Subtitle Scope bit
 154   @param  Data                   Destination for the created opcode binary
 155
 156   @retval EFI_SUCCESS            Opcode is created successfully.
 157   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 158
 159 **/
 160 EFI_STATUS
 161 EFIAPI
 162 CreateSubTitleOpCode (
 163   IN      EFI_STRING_ID       Prompt,
 164   IN      EFI_STRING_ID       Help,
 165   IN      UINT8               Flags,
 166   IN      UINT8               Scope,
 167   IN OUT EFI_HII_UPDATE_DATA  *Data
 168   )
 169 ;
 170
 171 /**
 172   Create EFI_IFR_TEXT_OP opcode.
 173
 174   If Data is NULL or Data->Data is NULL, then ASSERT.
 175
 176   @param  Prompt                 String ID for Prompt
 177   @param  Help                   String ID for Help
 178   @param  TextTwo                String ID for text two
 179   @param  Data                   Destination for the created opcode binary
 180
 181   @retval EFI_SUCCESS            Opcode is created successfully.
 182   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 183
 184 **/
 185 EFI_STATUS
 186 EFIAPI
 187 CreateTextOpCode (
 188   IN      EFI_STRING_ID       Prompt,
 189   IN      EFI_STRING_ID       Help,
 190   IN      EFI_STRING_ID       TextTwo,
 191   IN OUT  EFI_HII_UPDATE_DATA *Data
 192   )
 193 ;
 194
 195 /**
 196   Create EFI_IFR_REF_OP opcode.
 197
 198   If Data is NULL or Data->Data is NULL, then ASSERT.
 199
 200   @param  FormId                 Destination Form ID
 201   @param  Prompt                 String ID for Prompt
 202   @param  Help                   String ID for Help
 203   @param  QuestionFlags          Flags in Question Header
 204   @param  QuestionId             Question ID
 205   @param  Data                   Destination for the created opcode binary
 206
 207   @retval EFI_SUCCESS            Opcode is created successfully.
 208   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 209   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 210
 211 **/
 212 EFI_STATUS
 213 EFIAPI
 214 CreateGotoOpCode (
 215   IN      EFI_FORM_ID         FormId,
 216   IN      EFI_STRING_ID       Prompt,
 217   IN      EFI_STRING_ID       Help,
 218   IN      UINT8               QuestionFlags,
 219   IN      EFI_QUESTION_ID     QuestionId,
 220   IN OUT  EFI_HII_UPDATE_DATA *Data
 221   )
 222 ;
 223
 224 /**
 225   Create EFI_IFR_ONE_OF_OPTION_OP opcode.
 226
 227   If Data is NULL or Data->Data is NULL, then ASSERT.
 228
 229   @param  OptionCount            The number of options.
 230   @param  OptionsList            The list of Options.
 231   @param  Type                   The data type.
 232   @param  Data                   Destination for the created opcode binary
 233
 234   @retval EFI_SUCCESS            Opcode is created successfully.
 235   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 236   @retval EFI_INVALID_PARAMETER If OptionCount is not zero but OptionsList is NULL.
 237
 238 **/
 239 EFI_STATUS
 240 EFIAPI
 241 CreateOneOfOptionOpCode (
 242   IN     UINTN                OptionCount,
 243   IN     IFR_OPTION           *OptionsList,
 244   IN     UINT8                Type,
 245   IN OUT EFI_HII_UPDATE_DATA  *Data
 246   )
 247 ;
 248
 249 /**
 250   Create EFI_IFR_ONE_OF_OP opcode.
 251
 252   If Data is NULL or Data->Data is NULL, then ASSERT.
 253
 254   @param  QuestionId             Question ID
 255   @param  VarStoreId             Storage ID
 256   @param  VarOffset              Offset in Storage
 257   @param  Prompt                 String ID for Prompt
 258   @param  Help                   String ID for Help
 259   @param  QuestionFlags          Flags in Question Header
 260   @param  OneOfFlags             Flags for oneof opcode
 261   @param  OptionsList            List of options
 262   @param  OptionCount            Number of options in option list
 263   @param  Data                   Destination for the created opcode binary
 264
 265   @retval EFI_SUCCESS            Opcode is created successfully.
 266   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 267   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 268
 269 **/
 270 EFI_STATUS
 271 EFIAPI
 272 CreateOneOfOpCode (
 273   IN     EFI_QUESTION_ID      QuestionId,
 274   IN     EFI_VARSTORE_ID      VarStoreId,
 275   IN     UINT16               VarOffset,
 276   IN     EFI_STRING_ID        Prompt,
 277   IN     EFI_STRING_ID        Help,
 278   IN     UINT8                QuestionFlags,
 279   IN     UINT8                OneOfFlags,
 280   IN     IFR_OPTION           *OptionsList,
 281   IN     UINTN                OptionCount,
 282   IN OUT EFI_HII_UPDATE_DATA  *Data
 283   )
 284 ;
 285
 286 /**
 287   Create EFI_IFR_ORDERED_LIST_OP opcode.
 288
 289   If Data is NULL or Data->Data is NULL, then ASSERT.
 290
 291   @param  QuestionId             Question ID
 292   @param  VarStoreId             Storage ID
 293   @param  VarOffset              Offset in Storage
 294   @param  Prompt                 String ID for Prompt
 295   @param  Help                   String ID for Help
 296   @param  QuestionFlags          Flags in Question Header
 297   @param  OrderedListFlags       Flags for ordered list opcode
 298   @param  DataType               Type for option value
 299   @param  MaxContainers          Maximum count for options in this ordered list
 300   @param  OptionsList            List of options
 301   @param  OptionCount            Number of options in option list
 302   @param  Data                   Destination for the created opcode binary
 303
 304   @retval EFI_SUCCESS            Opcode is created successfully.
 305   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 306   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 307
 308 **/
 309 EFI_STATUS
 310 EFIAPI
 311 CreateOrderedListOpCode (
 312   IN      EFI_QUESTION_ID     QuestionId,
 313   IN      EFI_VARSTORE_ID     VarStoreId,
 314   IN      UINT16              VarOffset,
 315   IN      EFI_STRING_ID       Prompt,
 316   IN      EFI_STRING_ID       Help,
 317   IN      UINT8               QuestionFlags,
 318   IN      UINT8               OrderedListFlags,
 319   IN      UINT8               DataType,
 320   IN      UINT8               MaxContainers,
 321   IN      IFR_OPTION          *OptionsList,
 322   IN      UINTN               OptionCount,
 323   IN OUT  EFI_HII_UPDATE_DATA *Data
 324   )
 325 ;
 326
 327 /**
 328   Create EFI_IFR_CHECKBOX_OP opcode.
 329
 330   If Data is NULL or Data->Data is NULL, then ASSERT.
 331
 332   @param  QuestionId             Question ID
 333   @param  VarStoreId             Storage ID
 334   @param  VarOffset              Offset in Storage
 335   @param  Prompt                 String ID for Prompt
 336   @param  Help                   String ID for Help
 337   @param  QuestionFlags          Flags in Question Header
 338   @param  CheckBoxFlags          Flags for checkbox opcode
 339   @param  Data                   Destination for the created opcode binary
 340
 341   @retval EFI_SUCCESS            Opcode is created successfully.
 342   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 343   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 344
 345 **/
 346 EFI_STATUS
 347 EFIAPI
 348 CreateCheckBoxOpCode (
 349   IN      EFI_QUESTION_ID     QuestionId,
 350   IN      EFI_VARSTORE_ID     VarStoreId,
 351   IN      UINT16              VarOffset,
 352   IN      EFI_STRING_ID       Prompt,
 353   IN      EFI_STRING_ID       Help,
 354   IN      UINT8               QuestionFlags,
 355   IN      UINT8               CheckBoxFlags,
 356   IN OUT EFI_HII_UPDATE_DATA  *Data
 357   )
 358 ;
 359
 360 /**
 361   Create EFI_IFR_NUMERIC_OP opcode.
 362
 363   If Data is NULL or Data->Data is NULL, then ASSERT.
 364
 365   @param  QuestionId             Question ID
 366   @param  VarStoreId             Storage ID
 367   @param  VarOffset              Offset in Storage
 368   @param  Prompt                 String ID for Prompt
 369   @param  Help                   String ID for Help
 370   @param  QuestionFlags          Flags in Question Header
 371   @param  NumericFlags           Flags for numeric opcode
 372   @param  Minimum                Numeric minimum value
 373   @param  Maximum                Numeric maximum value
 374   @param  Step                   Numeric step for edit
 375   @param  Default                Numeric default value
 376   @param  Data                   Destination for the created opcode binary
 377
 378   @retval EFI_SUCCESS            Opcode is created successfully.
 379   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 380   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 381
 382 **/
 383 EFI_STATUS
 384 EFIAPI
 385 CreateNumericOpCode (
 386   IN     EFI_QUESTION_ID     QuestionId,
 387   IN     EFI_VARSTORE_ID     VarStoreId,
 388   IN     UINT16              VarOffset,
 389   IN     EFI_STRING_ID       Prompt,
 390   IN     EFI_STRING_ID       Help,
 391   IN     UINT8               QuestionFlags,
 392   IN     UINT8               NumericFlags,
 393   IN     UINT64              Minimum,
 394   IN     UINT64              Maximum,
 395   IN     UINT64              Step,
 396   IN     UINT64              Default,
 397   IN OUT EFI_HII_UPDATE_DATA *Data
 398   )
 399 ;
 400
 401 /**
 402   Create EFI_IFR_STRING_OP opcode.
 403
 404   If Data is NULL or Data->Data is NULL, then ASSERT.
 405
 406   @param  QuestionId             Question ID
 407   @param  VarStoreId             Storage ID
 408   @param  VarOffset              Offset in Storage
 409   @param  Prompt                 String ID for Prompt
 410   @param  Help                   String ID for Help
 411   @param  QuestionFlags          Flags in Question Header
 412   @param  StringFlags            Flags for string opcode
 413   @param  MinSize                String minimum length
 414   @param  MaxSize                String maximum length
 415   @param  Data                   Destination for the created opcode binary
 416
 417   @retval EFI_SUCCESS            Opcode is created successfully.
 418   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 419   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 420
 421 **/
 422 EFI_STATUS
 423 EFIAPI
 424 CreateStringOpCode (
 425   IN      EFI_QUESTION_ID     QuestionId,
 426   IN      EFI_VARSTORE_ID     VarStoreId,
 427   IN      UINT16              VarOffset,
 428   IN      EFI_STRING_ID       Prompt,
 429   IN      EFI_STRING_ID       Help,
 430   IN      UINT8               QuestionFlags,
 431   IN      UINT8               StringFlags,
 432   IN      UINT8               MinSize,
 433   IN      UINT8               MaxSize,
 434   IN OUT EFI_HII_UPDATE_DATA  *Data
 435   )
 436 ;
 437 /**
 438     Construct <ConfigAltResp> for a buffer storage.
 439
 440     @param ConfigRequest           The Config request string. If set to NULL, all the
 441                                    configurable elements will be extracted from BlockNameArray.
 442     @param Progress                On return, points to a character in the Request.
 443     @param ConfigAltResp           The returned <ConfigAltResp>.
 444     @param Guid                    GUID of the buffer storage.
 445     @param Name                    Name of the buffer storage.
 446     @param DriverHandle            The DriverHandle which is used to invoke HiiDatabase
 447                                    protocol interface NewPackageList().
 448     @param BufferStorage           Content of the buffer storage.
 449     @param BufferStorageSize       Length in bytes of the buffer storage.
 450     @param BlockNameArray          Array generated by VFR compiler.
 451     @param NumberAltCfg            Number of Default value array generated by VFR compiler.
 452                                    The sequential input parameters will be number of
 453                                    AltCfgId and DefaultValueArray pairs. When set to 0,
 454                                    there will be no <AltResp>.
 455     @param  ...                    Variable argument list.
 456
 457     retval EFI_OUT_OF_RESOURCES  Run out of memory resource.
 458     retval EFI_INVALID_PARAMETER ConfigAltResp is NULL.
 459     retval EFI_SUCCESS           Operation successful.
 460
 461 **/
 462 EFI_STATUS
 463 ConstructConfigAltResp (
 464   IN  EFI_STRING                  ConfigRequest,  OPTIONAL
 465   OUT EFI_STRING                  *Progress,
 466   OUT EFI_STRING                  *ConfigAltResp,
 467   IN  EFI_GUID                    *Guid,
 468   IN  CHAR16                      *Name,
 469   IN  EFI_HANDLE                  *DriverHandle,
 470   IN  VOID                        *BufferStorage,
 471   IN  UINTN                       BufferStorageSize,
 472   IN  VOID                        *BlockNameArray, OPTIONAL
 473   IN  UINTN                       NumberAltCfg,
 474   ...
 475 //IN  UINT16                      AltCfgId,
 476 //IN  VOID                        *DefaultValueArray,
 477   )
 478 ;
 479
 480 /**
 481   Converts the unicode character of the string from uppercase to lowercase.
 482
 483   @param Str     String to be converted
 484
 485
 486 **/
 487 VOID
 488 EFIAPI
 489 ToLower (
 490   IN OUT CHAR16    *Str
 491   )
 492 ;
 493
 494 /**
 495   Converts binary buffer to a Unicode string. The byte buffer is in a reversed byte order
 496   compared with the byte order defined in BufToHexString().
 497
 498   @param  Str                    String for output
 499   @param  Buffer                 Binary buffer.
 500   @param  BufferSize             Size of the buffer in bytes.
 501
 502   @retval EFI_SUCCESS            The function completed successfully.
 503   @retval EFI_OUT_OF_RESOURCES   There is no enough available memory space.
 504
 505 **/
 506 EFI_STATUS
 507 EFIAPI
 508 BufInReverseOrderToHexString (
 509   IN OUT CHAR16    *Str,
 510   IN UINT8         *Buffer,
 511   IN UINTN         BufferSize
 512   )
 513 ;
 514
 515 /**
 516   Converts Hex String to binary buffer in reversed byte order to HexStringToBuf().
 517
 518   @param  Buffer                 Pointer to buffer that receives the data.
 519   @param  BufferSize             Length in bytes of the buffer to hold converted
 520                                  data. If routine return with EFI_SUCCESS,
 521                                  containing length of converted data. If routine
 522                                  return with EFI_BUFFER_TOO_SMALL, containg length
 523                                  of buffer desired.
 524   @param  Str                    String to be converted from.
 525
 526   @retval EFI_SUCCESS            The function completed successfully.
 527   @retval RETURN_BUFFER_TOO_SMALL   The input BufferSize is too small to hold the output. BufferSize
 528                                    will be updated to the size required for the converstion.
 529
 530 **/
 531 EFI_STATUS
 532 EFIAPI
 533 HexStringToBufInReverseOrder (
 534   IN OUT UINT8         *Buffer,
 535   IN OUT UINTN         *BufferSize,
 536   IN CHAR16            *Str
 537   )
 538 ;
 539
 540 /**
 541   Convert binary representation Config string (e.g. "0041004200430044") to the
 542   original string (e.g. "ABCD"). Config string appears in <ConfigHdr> (i.e.
 543   "&NAME=<string>"), or Name/Value pair in <ConfigBody> (i.e. "label=<string>").
 544
 545   @param UnicodeString  Original Unicode string.
 546   @param StrBufferLen   On input: Length in bytes of buffer to hold the Unicode string.
 547                                     Includes tailing '\0' character.
 548                                     On output:
 549                                       containing length of Unicode string buffer when returning EFI_SUCCESS;
 550                                       containg length of string buffer desired when returning EFI_BUFFER_TOO_SMALL.
 551   @param ConfigString   Binary representation of Unicode String, <string> := (<HexCh>4)+
 552
 553   @retval EFI_SUCCESS          Operation completes successfully.
 554   @retval EFI_BUFFER_TOO_SMALL The string buffer is too small.
 555
 556 **/
 557 EFI_STATUS
 558 EFIAPI
 559 ConfigStringToUnicode (
 560   IN OUT CHAR16                *UnicodeString,
 561   IN OUT UINTN                 *StrBufferLen,
 562   IN CHAR16                    *ConfigString
 563   )
 564 ;
 565
 566 /**
 567   Convert Unicode string to binary representation Config string, e.g.
 568   "ABCD" => "0041004200430044". Config string appears in <ConfigHdr> (i.e.
 569   "&NAME=<string>"), or Name/Value pair in <ConfigBody> (i.e. "label=<string>").
 570
 571   @param ConfigString   Binary representation of Unicode String, <string> := (<HexCh>4)+
 572   @param  StrBufferLen  On input: Length in bytes of buffer to hold the Unicode string.
 573                                     Includes tailing '\0' character.
 574                                     On output:
 575                                       If return EFI_SUCCESS, containing length of Unicode string buffer.
 576                                       If return EFI_BUFFER_TOO_SMALL, containg length of string buffer desired.
 577   @param  UnicodeString  Original Unicode string.
 578
 579   @retval EFI_SUCCESS           Operation completes successfully.
 580   @retval EFI_BUFFER_TOO_SMALL  The string buffer is too small.
 581
 582 **/
 583 EFI_STATUS
 584 EFIAPI
 585 UnicodeToConfigString (
 586   IN OUT CHAR16                *ConfigString,
 587   IN OUT UINTN                 *StrBufferLen,
 588   IN CHAR16                    *UnicodeString
 589   )
 590 ;
 591
 592 /**
 593   Construct <ConfigHdr> using routing information GUID/NAME/PATH.
 594
 595   @param  ConfigHdr              Pointer to the ConfigHdr string.
 596   @param  StrBufferLen           On input: Length in bytes of buffer to hold the
 597                                  ConfigHdr string. Includes tailing '\0' character.
 598                                  On output: If return EFI_SUCCESS, containing
 599                                  length of ConfigHdr string buffer. If return
 600                                  EFI_BUFFER_TOO_SMALL, containg length of string
 601                                  buffer desired.
 602   @param  Guid                   Routing information: GUID.
 603   @param  Name                   Routing information: NAME.
 604   @param  DriverHandle           Driver handle which contains the routing
 605                                  information: PATH.
 606
 607   @retval EFI_SUCCESS            Operation completes successfully.
 608   @retval EFI_BUFFER_TOO_SMALL   The ConfigHdr string buffer is too small.
 609
 610 **/
 611 EFI_STATUS
 612 EFIAPI
 613 ConstructConfigHdr (
 614   IN OUT CHAR16                *ConfigHdr,
 615   IN OUT UINTN                 *StrBufferLen,
 616   IN CONST EFI_GUID            *Guid,
 617   IN CHAR16                    *Name, OPTIONAL
 618   IN EFI_HANDLE                *DriverHandle
 619   )
 620
 621 ;
 622
 623 /**
 624   Determines if the Routing data (Guid and Name) is correct in <ConfigHdr>.
 625
 626   @param ConfigString  Either <ConfigRequest> or <ConfigResp>.
 627   @param StorageGuid   GUID of the storage.
 628   @param StorageName   Name of the stoarge.
 629
 630   @retval TRUE         Routing information is correct in ConfigString.
 631   @retval FALSE        Routing information is incorrect in ConfigString.
 632
 633 **/
 634 BOOLEAN
 635 IsConfigHdrMatch (
 636   IN EFI_STRING                ConfigString,
 637   IN EFI_GUID                  *StorageGuid, OPTIONAL
 638   IN CHAR16                    *StorageName  OPTIONAL
 639   )
 640 ;
 641
 642 /**
 643   Search BlockName "&OFFSET=Offset&WIDTH=Width" in a string.
 644
 645   @param  String                 The string to be searched in.
 646   @param  Offset                 Offset in BlockName.
 647   @param  Width                  Width in BlockName.
 648
 649   @retval TRUE                   Block name found.
 650   @retval FALSE                  Block name not found.
 651
 652 **/
 653 BOOLEAN
 654 EFIAPI
 655 FindBlockName (
 656   IN OUT CHAR16                *String,
 657   IN UINTN                     Offset,
 658   IN UINTN                     Width
 659   )
 660 ;
 661
 662 /**
 663   This routine is invoked by ConfigAccess.Callback() to retrived uncommitted data from Form Browser.
 664
 665   @param  VariableGuid           An optional field to indicate the target variable
 666                                  GUID name to use.
 667   @param  VariableName           An optional field to indicate the target
 668                                  human-readable variable name.
 669   @param  BufferSize             On input: Length in bytes of buffer to hold
 670                                  retrived data. On output: If return
 671                                  EFI_BUFFER_TOO_SMALL, containg length of buffer
 672                                  desired.
 673   @param  Buffer                 Buffer to hold retrived data.
 674
 675   @retval EFI_SUCCESS            Operation completes successfully.
 676   @retval EFI_BUFFER_TOO_SMALL   The intput buffer is too small.
 677
 678 **/
 679 EFI_STATUS
 680 EFIAPI
 681 GetBrowserData (
 682   IN CONST EFI_GUID          *VariableGuid, OPTIONAL
 683   IN CONST CHAR16            *VariableName, OPTIONAL
 684   IN OUT UINTN               *BufferSize,
 685   IN OUT UINT8               *Buffer
 686   )
 687 ;
 688
 689 /**
 690   This routine is invoked by ConfigAccess.Callback() to update uncommitted data of Form Browser.
 691
 692   @param  VariableGuid           An optional field to indicate the target variable
 693                                  GUID name to use.
 694   @param  VariableName           An optional field to indicate the target
 695                                  human-readable variable name.
 696   @param  BufferSize             Length in bytes of buffer to hold retrived data.
 697   @param  Buffer                 Buffer to hold retrived data.
 698   @param  RequestElement         An optional field to specify which part of the
 699                                  buffer data will be send back to Browser. If NULL,
 700                                  the whole buffer of data will be committed to
 701                                  Browser. <RequestElement> ::=
 702                                  &OFFSET=<Number>&WIDTH=<Number>*
 703
 704   @retval EFI_SUCCESS            Operation completes successfully.
 705   @retval Other                  Updating Browser uncommitted data failed.
 706
 707 **/
 708 EFI_STATUS
 709 EFIAPI
 710 SetBrowserData (
 711   IN CONST EFI_GUID          *VariableGuid, OPTIONAL
 712   IN CONST CHAR16            *VariableName, OPTIONAL
 713   IN UINTN                   BufferSize,
 714   IN CONST UINT8             *Buffer,
 715   IN CONST CHAR16            *RequestElement  OPTIONAL
 716   )
 717 ;
 718
 719 /**
 720   Draw a dialog and return the selected key.
 721
 722   @param  NumberOfLines          The number of lines for the dialog box
 723   @param  KeyValue               The EFI_KEY value returned if HotKey is TRUE..
 724   @param  String                 Pointer to the first string in the list
 725   @param  ...                    A series of (quantity == NumberOfLines - 1) text
 726                                  strings which will be used to construct the dialog
 727                                  box
 728
 729   @retval EFI_SUCCESS            Displayed dialog and received user interaction
 730   @retval EFI_INVALID_PARAMETER  One of the parameters was invalid.
 731
 732 **/
 733 EFI_STATUS
 734 EFIAPI
 735 IfrLibCreatePopUp (
 736   IN  UINTN                       NumberOfLines,
 737   OUT EFI_INPUT_KEY               *KeyValue,
 738   IN  CHAR16                      *String,
 739   ...
 740   )
 741 ;
 742
 743 /**
 744   Draw a dialog and return the selected key using Variable Argument List.
 745
 746   @param  NumberOfLines          The number of lines for the dialog box
 747   @param  KeyValue               The EFI_KEY value returned if HotKey is TRUE..
 748   @param  String                 The first String to be displayed in the Pop-Up.
 749   @param  Args                   VA_LIST marker for the variable argument list.
 750                                  A series of (quantity == NumberOfLines - 1) text
 751                                  strings which will be used to construct the dialog
 752                                  box
 753
 754   @retval EFI_SUCCESS            Displayed dialog and received user interaction
 755   @retval EFI_INVALID_PARAMETER  One of the parameters was invalid.
 756
 757 **/
 758 EFI_STATUS
 759 EFIAPI
 760 IfrLibCreatePopUp2 (
 761   IN  UINTN                       NumberOfLines,
 762   OUT EFI_INPUT_KEY               *KeyValue,
 763   IN  CHAR16                      *String,
 764   IN  VA_LIST                     Args
 765   )
 766 ;
 767
 768 /**
 769   Test if  a Unicode character is a hexadecimal digit. If true, the input
 770   Unicode character is converted to a byte.
 771
 772   This function tests if a Unicode character is a hexadecimal digit. If true, the input
 773   Unicode character is converted to a byte. For example, Unicode character
 774   L'A' will be converted to 0x0A.
 775
 776   If Digit is NULL, then ASSERT.
 777
 778   @param  Digit       The output hexadecimal digit.
 779
 780   @param  Char        The input Unicode character.
 781
 782   @retval TRUE        Char is in the range of Hexadecimal number. Digit is updated
 783                       to the byte value of the number.
 784   @retval FALSE       Char is not in the range of Hexadecimal number. Digit is keep
 785                       intact.
 786
 787 **/
 788 BOOLEAN
 789 EFIAPI
 790 IsHexDigit (
 791   OUT UINT8      *Digit,
 792   IN  CHAR16      Char
 793   )
 794 ;
 795
 796
 797 /**
 798   Convert binary buffer to a Unicode String in a specified sequence.
 799
 800   This function converts bytes in the memory block pointed by Buffer to a Unicode String Str.
 801   Each byte will be represented by two Unicode characters. For example, byte 0xA1 will
 802   be converted into two Unicode character L'A' and L'1'. In the output String, the Unicode Character
 803   for the Most Significant Nibble will be put before the Unicode Character for the Least Significant
 804   Nibble. The output string for the buffer containing a single byte 0xA1 will be L"A1".
 805   For a buffer with multiple bytes, the Unicode character produced by the first byte will be put into the
 806   the last character in the output string. The one next to first byte will be put into the
 807   character before the last character. This rules applies to the rest of the bytes. The Unicode
 808   character by the last byte will be put into the first character in the output string. For example,
 809   the input buffer for a 64-bits unsigned integer 0x12345678abcdef1234 will be converted to
 810   a Unicode string equal to L"12345678abcdef1234".
 811
 812   @param String                        On input, String is pointed to the buffer allocated for the convertion.
 813   @param StringLen                     The Length of String buffer to hold the output String. The length must include the tailing '\0' character.
 814                                        The StringLen required to convert a N bytes Buffer will be a least equal to or greater
 815                                        than 2*N + 1.
 816   @param Buffer                        The pointer to a input buffer.
 817   @param BufferSizeInBytes             Length in bytes of the input buffer.
 818
 819
 820   @retval  EFI_SUCCESS                 The convertion is successful. All bytes in Buffer has been convert to the corresponding
 821                                        Unicode character and placed into the right place in String.
 822   @retval  EFI_BUFFER_TOO_SMALL        StringSizeInBytes is smaller than 2 * N + 1the number of bytes required to
 823                                        complete the convertion.
 824 **/
 825 RETURN_STATUS
 826 EFIAPI
 827 BufToHexString (
 828   IN OUT       CHAR16               *String,
 829   IN OUT       UINTN                *StringLen,
 830   IN     CONST UINT8                *Buffer,
 831   IN           UINTN                BufferSizeInBytes
 832   )
 833 ;
 834
 835
 836 /**
 837   Convert a Unicode string consisting of hexadecimal characters to a output byte buffer.
 838
 839   This function converts a Unicode string consisting of characters in the range of Hexadecimal
 840   character (L'0' to L'9', L'A' to L'F' and L'a' to L'f') to a output byte buffer. The function will stop
 841   at the first non-hexadecimal character or the NULL character. The convertion process can be
 842   simply viewed as the reverse operations defined by BufToHexString. Two Unicode characters will be
 843   converted into one byte. The first Unicode character represents the Most Significant Nibble and the
 844   second Unicode character represents the Least Significant Nibble in the output byte.
 845   The first pair of Unicode characters represents the last byte in the output buffer. The second pair of Unicode
 846   characters represent the  the byte preceding the last byte. This rule applies to the rest pairs of bytes.
 847   The last pair represent the first byte in the output buffer.
 848
 849   For example, a Unciode String L"12345678" will be converted into a buffer wil the following bytes
 850   (first byte is the byte in the lowest memory address): "0x78, 0x56, 0x34, 0x12".
 851
 852   If String has N valid hexadecimal characters for conversion,  the caller must make sure Buffer is at least
 853   N/2 (if N is even) or (N+1)/2 (if N if odd) bytes.
 854
 855   If either Buffer, BufferSizeInBytes or String is NULL, then ASSERT ().
 856
 857   @param Buffer                      The output buffer allocated by the caller.
 858   @param BufferSizeInBytes           On input, the size in bytes of Buffer. On output, it is updated to
 859                                      contain the size of the Buffer which is actually used for the converstion.
 860                                      For Unicode string with 2*N hexadecimal characters (not including the
 861                                      tailing NULL character), N bytes of Buffer will be used for the output.
 862   @param String                      The input hexadecimal string.
 863   @param ConvertedStrLen             The number of hexadecimal characters used to produce content in output
 864                                      buffer Buffer.
 865
 866   @retval  RETURN_BUFFER_TOO_SMALL   The input BufferSizeInBytes is too small to hold the output. BufferSizeInBytes
 867                                      will be updated to the size required for the converstion.
 868   @retval  RETURN_SUCCESS            The convertion is successful or the first Unicode character from String
 869                                      is hexadecimal. If ConvertedStrLen is not NULL, it is updated
 870                                      to the number of hexadecimal character used for the converstion.
 871 **/
 872 RETURN_STATUS
 873 EFIAPI
 874 HexStringToBuf (
 875   OUT          UINT8                    *Buffer,
 876   IN OUT       UINTN                    *BufferSizeInBytes,
 877   IN     CONST CHAR16                   *String,
 878   OUT          UINTN                    *ConvertedStrLen  OPTIONAL
 879   )
 880 ;
 881
 882 #endif