MdePkg/Include/Library/IfrSupportLib.h

   1 /** @file
   2   The file contain all library functions and definitions for IFR opcode creation and
   3   related Form Browser utility Operations.
   4
   5   Copyright (c) 2007, 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 // If "LANG_SUPPORT" is defined, "Lang" and "LangCodes" will be produced;
  36 // If "LANG_SUPPORT" is undefined, "Lang" and "LangCodes" will not be produced.
  37 //
  38 #define LANG_SUPPORT
  39
  40 #define EFI_LANGUAGE_VARIABLE           L"Lang"
  41 #define EFI_LANGUAGE_CODES_VARIABLE     L"LangCodes"
  42
  43 #define UEFI_LANGUAGE_VARIABLE          L"PlatformLang"
  44 #define UEFI_LANGUAGE_CODES_VARIABLE    L"PlatformLangCodes"
  45
  46 //
  47 // Limited buffer size recommended by RFC4646 (4.3.  Length Considerations)
  48 // (42 characters plus a NULL terminator)
  49 //
  50 #define RFC_3066_ENTRY_SIZE             (42 + 1)
  51 #define ISO_639_2_ENTRY_SIZE            3
  52
  53 #define INVALID_VARSTORE_ID             0
  54
  55 #define QUESTION_FLAGS              (EFI_IFR_FLAG_READ_ONLY | EFI_IFR_FLAG_CALLBACK | EFI_IFR_FLAG_RESET_REQUIRED | EFI_IFR_FLAG_OPTIONS_ONLY)
  56 #define QUESTION_FLAGS_MASK         (~QUESTION_FLAGS)
  57
  58 extern EFI_HII_DATABASE_PROTOCOL *gIfrLibHiiDatabase;
  59 extern EFI_HII_STRING_PROTOCOL   *gIfrLibHiiString;
  60
  61 #pragma pack(1)
  62 typedef struct {
  63   EFI_STRING_ID       StringToken;
  64   EFI_IFR_TYPE_VALUE  Value;
  65   UINT8               Flags;
  66 } IFR_OPTION;
  67 #pragma pack()
  68
  69 typedef struct {
  70   //
  71   // Buffer size allocated for Data.
  72   //
  73   UINT32                BufferSize;
  74
  75   //
  76   // Offset in Data to append the newly created opcode binary.
  77   // It will be adjusted automatically in Create***OpCode(), and should be
  78   // initialized to 0 before invocation of a serial of Create***OpCode()
  79   //
  80   UINT32                Offset;
  81
  82   //
  83   // The destination buffer for created op-codes
  84   //
  85   UINT8                 *Data;
  86 } EFI_HII_UPDATE_DATA;
  87
  88
  89 /**
  90   Create EFI_IFR_END_OP opcode.
  91
  92   If Data is NULL or Data->Data is NULL, then ASSERT.
  93
  94   @param  Data                   Destination for the created opcode binary
  95
  96   @retval EFI_SUCCESS            Opcode create success
  97   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
  98
  99 **/
 100 EFI_STATUS
 101 EFIAPI
 102 CreateEndOpCode (
 103   IN OUT EFI_HII_UPDATE_DATA *Data
 104   )
 105 ;
 106
 107 /**
 108   Create EFI_IFR_DEFAULT_OP opcode.
 109
 110   @param  Value                  Value for the default
 111   @param  Type                   Type for the default
 112   @param  Data                   Destination for the created opcode binary
 113
 114   @retval EFI_SUCCESS            Opcode create success
 115   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 116   @retval EFI_INVALID_PARAMETER The type is not valid.
 117
 118 **/
 119 EFI_STATUS
 120 EFIAPI
 121 CreateDefaultOpCode (
 122   IN     EFI_IFR_TYPE_VALUE  *Value,
 123   IN     UINT8               Type,
 124   IN OUT EFI_HII_UPDATE_DATA *Data
 125   )
 126 ;
 127
 128 /**
 129   Create EFI_IFR_ACTION_OP opcode.
 130
 131   @param  QuestionId             Question ID
 132   @param  Prompt                 String ID for Prompt
 133   @param  Help                   String ID for Help
 134   @param  QuestionFlags          Flags in Question Header
 135   @param  QuestionConfig         String ID for configuration
 136   @param  Data                   Destination for the created opcode binary
 137
 138   @retval EFI_SUCCESS            Opcode create success
 139   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 140   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 141
 142 **/
 143 EFI_STATUS
 144 EFIAPI
 145 CreateActionOpCode (
 146   IN     EFI_QUESTION_ID      QuestionId,
 147   IN     EFI_STRING_ID        Prompt,
 148   IN     EFI_STRING_ID        Help,
 149   IN     UINT8                QuestionFlags,
 150   IN     EFI_STRING_ID        QuestionConfig,
 151   IN OUT EFI_HII_UPDATE_DATA  *Data
 152   )
 153 ;
 154
 155 /**
 156   Create EFI_IFR_SUBTITLE_OP opcode.
 157
 158   @param  Prompt                 String ID for Prompt
 159   @param  Help                   String ID for Help
 160   @param  Flags                  Subtitle opcode flags
 161   @param  Scope                  Subtitle Scope bit
 162   @param  Data                   Destination for the created opcode binary
 163
 164   @retval EFI_SUCCESS            Opcode create success
 165   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 166
 167 **/
 168 EFI_STATUS
 169 EFIAPI
 170 CreateSubTitleOpCode (
 171   IN      EFI_STRING_ID       Prompt,
 172   IN      EFI_STRING_ID       Help,
 173   IN      UINT8               Flags,
 174   IN      UINT8               Scope,
 175   IN OUT EFI_HII_UPDATE_DATA  *Data
 176   )
 177 ;
 178
 179 /**
 180   Create EFI_IFR_TEXT_OP opcode.
 181
 182   @param  Prompt                 String ID for Prompt
 183   @param  Help                   String ID for Help
 184   @param  TextTwo                String ID for text two
 185   @param  Data                   Destination for the created opcode binary
 186
 187   @retval EFI_SUCCESS            Opcode create success
 188   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 189
 190 **/
 191 EFI_STATUS
 192 EFIAPI
 193 CreateTextOpCode (
 194   IN      EFI_STRING_ID       Prompt,
 195   IN      EFI_STRING_ID       Help,
 196   IN      EFI_STRING_ID       TextTwo,
 197   IN OUT  EFI_HII_UPDATE_DATA *Data
 198   )
 199 ;
 200
 201 /**
 202   Create EFI_IFR_REF_OP opcode.
 203
 204   @param  FormId                 Destination Form ID
 205   @param  Prompt                 String ID for Prompt
 206   @param  Help                   String ID for Help
 207   @param  QuestionFlags          Flags in Question Header
 208   @param  QuestionId             Question ID
 209   @param  Data                   Destination for the created opcode binary
 210
 211   @retval EFI_SUCCESS            Opcode create success
 212   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 213   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 214
 215 **/
 216 EFI_STATUS
 217 EFIAPI
 218 CreateGotoOpCode (
 219   IN      EFI_FORM_ID         FormId,
 220   IN      EFI_STRING_ID       Prompt,
 221   IN      EFI_STRING_ID       Help,
 222   IN      UINT8               QuestionFlags,
 223   IN      EFI_QUESTION_ID     QuestionId,
 224   IN OUT  EFI_HII_UPDATE_DATA *Data
 225   )
 226 ;
 227
 228 /**
 229   Create EFI_IFR_ONE_OF_OPTION_OP opcode.
 230
 231   @param  QuestionId             Question ID
 232   @param  OptionList             The list of Options.
 233   @param  Type                   The data type.
 234   @param  Data                   Destination for the created opcode binary
 235
 236   @retval EFI_SUCCESS            Opcode create success
 237   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 238
 239 **/
 240 EFI_STATUS
 241 EFIAPI
 242 CreateOneOfOptionOpCode (
 243   IN     UINTN                OptionCount,
 244   IN     IFR_OPTION           *OptionsList,
 245   IN     UINT8                Type,
 246   IN OUT EFI_HII_UPDATE_DATA  *Data
 247   )
 248 ;
 249
 250 /**
 251   Create EFI_IFR_ONE_OF_OP opcode.
 252
 253   @param  QuestionId             Question ID
 254   @param  VarStoreId             Storage ID
 255   @param  VarOffset              Offset in Storage
 256   @param  Prompt                 String ID for Prompt
 257   @param  Help                   String ID for Help
 258   @param  QuestionFlags          Flags in Question Header
 259   @param  OneOfFlags             Flags for oneof opcode
 260   @param  OptionsList            List of options
 261   @param  OptionCount            Number of options in option list
 262   @param  Data                   Destination for the created opcode binary
 263
 264   @retval EFI_SUCCESS            Opcode create success
 265   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 266   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 267
 268 **/
 269 EFI_STATUS
 270 EFIAPI
 271 CreateOneOfOpCode (
 272   IN     EFI_QUESTION_ID      QuestionId,
 273   IN     EFI_VARSTORE_ID      VarStoreId,
 274   IN     UINT16               VarOffset,
 275   IN     EFI_STRING_ID        Prompt,
 276   IN     EFI_STRING_ID        Help,
 277   IN     UINT8                QuestionFlags,
 278   IN     UINT8                OneOfFlags,
 279   IN     IFR_OPTION           *OptionsList,
 280   IN     UINTN                OptionCount,
 281   IN OUT EFI_HII_UPDATE_DATA  *Data
 282   )
 283 ;
 284
 285 /**
 286   Create EFI_IFR_ORDERED_LIST_OP opcode.
 287
 288   @param  QuestionId             Question ID
 289   @param  VarStoreId             Storage ID
 290   @param  VarOffset              Offset in Storage
 291   @param  Prompt                 String ID for Prompt
 292   @param  Help                   String ID for Help
 293   @param  QuestionFlags          Flags in Question Header
 294   @param  Flags                  Flags for ordered list opcode
 295   @param  DataType               Type for option value
 296   @param  MaxContainers          Maximum count for options in this ordered list
 297   @param  OptionsList            List of options
 298   @param  OptionCount            Number of options in option list
 299   @param  Data                   Destination for the created opcode binary
 300
 301   @retval EFI_SUCCESS            Opcode create success
 302   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 303   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 304
 305 **/
 306 EFI_STATUS
 307 EFIAPI
 308 CreateOrderedListOpCode (
 309   IN      EFI_QUESTION_ID     QuestionId,
 310   IN      EFI_VARSTORE_ID     VarStoreId,
 311   IN      UINT16              VarOffset,
 312   IN      EFI_STRING_ID       Prompt,
 313   IN      EFI_STRING_ID       Help,
 314   IN      UINT8               QuestionFlags,
 315   IN      UINT8               Flags,
 316   IN      UINT8               DataType,
 317   IN      UINT8               MaxContainers,
 318   IN      IFR_OPTION          *OptionsList,
 319   IN     UINTN                OptionCount,
 320   IN OUT EFI_HII_UPDATE_DATA  *Data
 321   )
 322 ;
 323
 324 /**
 325   Create EFI_IFR_CHECKBOX_OP opcode.
 326
 327   @param  QuestionId             Question ID
 328   @param  VarStoreId             Storage ID
 329   @param  VarOffset              Offset in Storage
 330   @param  Prompt                 String ID for Prompt
 331   @param  Help                   String ID for Help
 332   @param  QuestionFlags          Flags in Question Header
 333   @param  CheckBoxFlags          Flags for checkbox opcode
 334   @param  Data                   Destination for the created opcode binary
 335
 336   @retval EFI_SUCCESS            Opcode create success
 337   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 338   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 339
 340 **/
 341 EFI_STATUS
 342 EFIAPI
 343 CreateCheckBoxOpCode (
 344   IN      EFI_QUESTION_ID     QuestionId,
 345   IN      EFI_VARSTORE_ID     VarStoreId,
 346   IN      UINT16              VarOffset,
 347   IN      EFI_STRING_ID       Prompt,
 348   IN      EFI_STRING_ID       Help,
 349   IN      UINT8               QuestionFlags,
 350   IN      UINT8               CheckBoxFlags,
 351   IN OUT EFI_HII_UPDATE_DATA  *Data
 352   )
 353 ;
 354
 355 /**
 356   Create EFI_IFR_NUMERIC_OP opcode.
 357
 358   @param  QuestionId             Question ID
 359   @param  VarStoreId             Storage ID
 360   @param  VarOffset              Offset in Storage
 361   @param  Prompt                 String ID for Prompt
 362   @param  Help                   String ID for Help
 363   @param  QuestionFlags          Flags in Question Header
 364   @param  NumericFlags           Flags for numeric opcode
 365   @param  Minimum                Numeric minimum value
 366   @param  Maximum                Numeric maximum value
 367   @param  Step                   Numeric step for edit
 368   @param  Default                Numeric default value
 369   @param  Data                   Destination for the created opcode binary
 370
 371   @retval EFI_SUCCESS            Opcode create success
 372   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 373   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 374
 375 **/
 376 EFI_STATUS
 377 EFIAPI
 378 CreateNumericOpCode (
 379   IN     EFI_QUESTION_ID     QuestionId,
 380   IN     EFI_VARSTORE_ID     VarStoreId,
 381   IN     UINT16              VarOffset,
 382   IN     EFI_STRING_ID       Prompt,
 383   IN     EFI_STRING_ID       Help,
 384   IN     UINT8               QuestionFlags,
 385   IN     UINT8               NumericFlags,
 386   IN     UINT64              Minimum,
 387   IN     UINT64              Maximum,
 388   IN     UINT64              Step,
 389   IN     UINT64              Default,
 390   IN OUT EFI_HII_UPDATE_DATA *Data
 391   )
 392 ;
 393
 394 /**
 395   Create EFI_IFR_STRING_OP opcode.
 396
 397   @param  QuestionId             Question ID
 398   @param  VarStoreId             Storage ID
 399   @param  VarOffset              Offset in Storage
 400   @param  Prompt                 String ID for Prompt
 401   @param  Help                   String ID for Help
 402   @param  QuestionFlags          Flags in Question Header
 403   @param  StringFlags            Flags for string opcode
 404   @param  MinSize                String minimum length
 405   @param  MaxSize                String maximum length
 406   @param  Data                   Destination for the created opcode binary
 407
 408   @retval EFI_SUCCESS            Opcode create success
 409   @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
 410   @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
 411
 412 **/
 413 EFI_STATUS
 414 EFIAPI
 415 CreateStringOpCode (
 416   IN      EFI_QUESTION_ID     QuestionId,
 417   IN      EFI_VARSTORE_ID     VarStoreId,
 418   IN      UINT16              VarOffset,
 419   IN      EFI_STRING_ID       Prompt,
 420   IN      EFI_STRING_ID       Help,
 421   IN      UINT8               QuestionFlags,
 422   IN      UINT8               StringFlags,
 423   IN      UINT8               MinSize,
 424   IN      UINT8               MaxSize,
 425   IN OUT EFI_HII_UPDATE_DATA  *Data
 426   )
 427 ;
 428
 429 /**
 430   Converts binary buffer to Unicode string in reversed byte order to BufToHexString().
 431
 432   @param  Str                    String for output
 433   @param  Buffer                 Binary buffer.
 434   @param  BufferSize             Size of the buffer in bytes.
 435
 436   @retval EFI_SUCCESS            The function completed successfully.
 437
 438 **/
 439 EFI_STATUS
 440 EFIAPI
 441 BufferToHexString (
 442   IN OUT CHAR16    *Str,
 443   IN UINT8         *Buffer,
 444   IN UINTN         BufferSize
 445   )
 446 ;
 447
 448 /**
 449   Converts Hex String to binary buffer in reversed byte order to HexStringToBuf().
 450
 451   @param  Buffer                 Pointer to buffer that receives the data.
 452   @param  BufferSize             Length in bytes of the buffer to hold converted
 453                                  data. If routine return with EFI_SUCCESS,
 454                                  containing length of converted data. If routine
 455                                  return with EFI_BUFFER_TOO_SMALL, containg length
 456                                  of buffer desired.
 457   @param  Str                    String to be converted from.
 458
 459   @retval EFI_SUCCESS            The function completed successfully.
 460
 461 **/
 462 EFI_STATUS
 463 EFIAPI
 464 HexStringToBuffer (
 465   IN OUT UINT8         *Buffer,
 466   IN OUT UINTN         *BufferSize,
 467   IN CHAR16            *Str
 468   )
 469 ;
 470
 471 /**
 472   Construct <ConfigHdr> using routing information GUID/NAME/PATH.
 473
 474   @param  ConfigHdr              Pointer to the ConfigHdr string.
 475   @param  StrBufferLen           On input: Length in bytes of buffer to hold the
 476                                  ConfigHdr string. Includes tailing '\0' character.
 477                                  On output: If return EFI_SUCCESS, containing
 478                                  length of ConfigHdr string buffer. If return
 479                                  EFI_BUFFER_TOO_SMALL, containg length of string
 480                                  buffer desired.
 481   @param  Guid                   Routing information: GUID.
 482   @param  Name                   Routing information: NAME.
 483   @param  DriverHandle           Driver handle which contains the routing
 484                                  information: PATH.
 485
 486   @retval EFI_SUCCESS            Routine success.
 487   @retval EFI_BUFFER_TOO_SMALL   The ConfigHdr string buffer is too small.
 488
 489 **/
 490 EFI_STATUS
 491 EFIAPI
 492 ConstructConfigHdr (
 493   IN OUT CHAR16                *ConfigHdr,
 494   IN OUT UINTN                 *StrBufferLen,
 495   IN EFI_GUID                  *Guid,
 496   IN CHAR16                    *Name, OPTIONAL
 497   IN EFI_HANDLE                *DriverHandle
 498   )
 499
 500 ;
 501
 502 /**
 503   Search BlockName "&OFFSET=Offset&WIDTH=Width" in a string.
 504
 505   @param  String                 The string to be searched in.
 506   @param  Offset                 Offset in BlockName.
 507   @param  Width                  Width in BlockName.
 508
 509   @retval TRUE                   Block name found.
 510   @retval FALSE                  Block name not found.
 511
 512 **/
 513 BOOLEAN
 514 EFIAPI
 515 FindBlockName (
 516   IN OUT CHAR16                *String,
 517   UINTN                        Offset,
 518   UINTN                        Width
 519   )
 520 ;
 521
 522 /**
 523   This routine is invoked by ConfigAccess.Callback() to retrived uncommitted data from Form Browser.
 524
 525   @param  VariableGuid           An optional field to indicate the target variable
 526                                  GUID name to use.
 527   @param  VariableName           An optional field to indicate the target
 528                                  human-readable variable name.
 529   @param  BufferSize             On input: Length in bytes of buffer to hold
 530                                  retrived data. On output: If return
 531                                  EFI_BUFFER_TOO_SMALL, containg length of buffer
 532                                  desired.
 533   @param  Buffer                 Buffer to hold retrived data.
 534
 535   @retval EFI_SUCCESS            Routine success.
 536   @retval EFI_BUFFER_TOO_SMALL   The intput buffer is too small.
 537
 538 **/
 539 EFI_STATUS
 540 EFIAPI
 541 GetBrowserData (
 542   EFI_GUID                   *VariableGuid, OPTIONAL
 543   CHAR16                     *VariableName, OPTIONAL
 544   UINTN                      *BufferSize,
 545   UINT8                      *Buffer
 546   )
 547 ;
 548
 549 /**
 550   This routine is invoked by ConfigAccess.Callback() to update uncommitted data of Form Browser.
 551
 552   @param  VariableGuid           An optional field to indicate the target variable
 553                                  GUID name to use.
 554   @param  VariableName           An optional field to indicate the target
 555                                  human-readable variable name.
 556   @param  BufferSize             Length in bytes of buffer to hold retrived data.
 557   @param  Buffer                 Buffer to hold retrived data.
 558   @param  RequestElement         An optional field to specify which part of the
 559                                  buffer data will be send back to Browser. If NULL,
 560                                  the whole buffer of data will be committed to
 561                                  Browser. <RequestElement> ::=
 562                                  &OFFSET=<Number>&WIDTH=<Number>*
 563
 564   @retval EFI_SUCCESS            Routine success.
 565   @retval Other                  Updating Browser uncommitted data failed.
 566
 567 **/
 568 EFI_STATUS
 569 EFIAPI
 570 SetBrowserData (
 571   EFI_GUID                   *VariableGuid, OPTIONAL
 572   CHAR16                     *VariableName, OPTIONAL
 573   UINTN                      BufferSize,
 574   UINT8                      *Buffer,
 575   CHAR16                     *RequestElement  OPTIONAL
 576   )
 577 ;
 578
 579 /**
 580   Draw a dialog and return the selected key.
 581
 582   @param  NumberOfLines          The number of lines for the dialog box
 583   @param  KeyValue               The EFI_KEY value returned if HotKey is TRUE..
 584   @param  String                 Pointer to the first string in the list
 585   @param  ...                    A series of (quantity == NumberOfLines) text
 586                                  strings which will be used to construct the dialog
 587                                  box
 588
 589   @retval EFI_SUCCESS            Displayed dialog and received user interaction
 590   @retval EFI_INVALID_PARAMETER  One of the parameters was invalid.
 591
 592 **/
 593
 594 EFI_STATUS
 595 EFIAPI
 596 IfrLibCreatePopUp (
 597   IN  UINTN                       NumberOfLines,
 598   OUT EFI_INPUT_KEY               *KeyValue,
 599   IN  CHAR16                      *String,
 600   ...
 601   )
 602 ;
 603
 604 #endif