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