Tools/Source/TianoTools/Include/Protocol/Hii.h

   1 /** @file
   2   This file defines the Human Interface Infrastructure protocol which will
   3   be used by resources which want to publish IFR/Font/String data and have it
   4   collected by the Configuration engine.
   5
   6   Copyright (c) 2006, Intel Corporation
   7   All rights reserved. This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15   Module Name:  Hii.h
  16
  17   @par Revision Reference:
  18   This protocol is defined in HII spec 0.92.
  19
  20 **/
  21
  22 #ifndef __HII_H__
  23 #define __HII_H__
  24
  25
  26 #define EFI_HII_PROTOCOL_GUID \
  27   { \
  28     0xea816d2c, 0xcee5, 0x4f02, {0x99, 0xb5, 0xd3, 0x90, 0x5c, 0xbb, 0xd0, 0x77 } \
  29   }
  30
  31 // BugBug:
  32 //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  33 // If UGA goes away we need to put this some place. I'm not sure where?
  34 //
  35 //typedef struct {
  36 //  UINT8 Blue;
  37 //  UINT8 Green;
  38 //  UINT8 Red;
  39 //  UINT8 Reserved;
  40 //} EFI_UGA_PIXEL;
  41
  42 //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  43 //
  44
  45 typedef struct _EFI_HII_PROTOCOL  EFI_HII_PROTOCOL;
  46
  47 //
  48 // Global definition
  49 //
  50 #define NARROW_CHAR         0xFFF0
  51 #define WIDE_CHAR           0xFFF1
  52 #define NON_BREAKING_CHAR   0xFFF2
  53 #define GLYPH_WIDTH         8
  54 #define GLYPH_HEIGHT        19
  55
  56 #define EFI_HII_FONT        1
  57 #define EFI_HII_STRING      2
  58 #define EFI_HII_IFR         3
  59 #define EFI_HII_KEYBOARD    4
  60 #define EFI_HII_HANDLES     5
  61 #define EFI_HII_VARIABLE    6
  62 #define EFI_HII_DEVICE_PATH 7
  63
  64
  65 // References to string tokens must use this macro to enable scanning for
  66 // token usages.
  67 //
  68 #define STRING_TOKEN(t) t
  69
  70 //
  71 // The following types are currently defined:
  72 //
  73 typedef UINT16  EFI_FORM_ID;
  74 typedef UINT16  EFI_FORM_LABEL;
  75
  76 #pragma pack(1)
  77
  78 typedef struct {
  79   UINT32  Length;
  80   UINT16  Type;
  81 } EFI_HII_PACK_HEADER;
  82
  83 //
  84 // A form list consists of a large variety of structure
  85 // possibilities so to represent the binary blob of data
  86 // associated with a package of forms, we will assume a
  87 // pointer to a self-describing data buffer.
  88 //
  89 typedef struct {
  90   EFI_HII_PACK_HEADER Header;
  91 } EFI_HII_IFR_PACK;
  92
  93 typedef struct {
  94   EFI_HII_PACK_HEADER Header;           // Must be filled in
  95   EFI_HANDLE          ImageHandle;      // Must be filled in
  96   EFI_HANDLE          DeviceHandle;     // Optional
  97   EFI_HANDLE          ControllerHandle; // Optional
  98   EFI_HANDLE          CallbackHandle;   // Optional
  99   EFI_HANDLE          COBExportHandle;  // Optional
 100 } EFI_HII_HANDLE_PACK;
 101
 102 //
 103 // ********************************************************
 104 // EFI_VARIABLE_CONTENTS
 105 // ********************************************************
 106 //
 107 typedef struct {
 108   EFI_HII_PACK_HEADER Header;
 109   EFI_GUID            VariableGuid;
 110   UINT32              VariableNameLength;
 111   UINT16              VariableId;
 112   //
 113   //  CHAR16                VariableName[]; //Null-terminated
 114   //
 115 } EFI_HII_VARIABLE_PACK;
 116
 117 //
 118 // ********************************************************
 119 // EFI_DEVICE_PATH_PACK
 120 // ********************************************************
 121 //
 122 typedef struct {
 123   EFI_HII_PACK_HEADER Header;
 124   //
 125   //  EFI_DEVICE_PATH       DevicePath[];
 126   //
 127 } EFI_HII_DEVICE_PATH_PACK;
 128
 129 //
 130 // ********************************************************
 131 // EFI_HII_DATA_TABLE
 132 // ********************************************************
 133 //
 134 typedef struct {
 135   EFI_HII_HANDLE  HiiHandle;
 136   EFI_GUID        PackageGuid;
 137   UINT32          DataTableSize;
 138   UINT32          IfrDataOffset;
 139   UINT32          StringDataOffset;
 140   UINT32          VariableDataOffset;
 141   UINT32          DevicePathOffset;
 142   UINT32          NumberOfVariableData;
 143   UINT32          NumberOfLanguages;
 144   //
 145   // EFI_HII_DEVICE_PATH_PACK DevicePath[];
 146   // EFI_HII_VARIABLE_PACK VariableData[];
 147   // EFI_HII_IFR_PACK IfrData;
 148   // EFI_HII_STRING_PACK StringData[];
 149   //
 150 } EFI_HII_DATA_TABLE;
 151
 152 //
 153 // ********************************************************
 154 // EFI_HII_EXPORT_TABLE
 155 // ********************************************************
 156 //
 157 typedef struct {
 158   UINT32    NumberOfHiiDataTables;
 159   EFI_GUID  Revision;
 160   //
 161   // EFI_HII_DATA_TABLE HiiDataTable[];
 162   //
 163 } EFI_HII_EXPORT_TABLE;
 164
 165 typedef struct {
 166   BOOLEAN               FormSetUpdate;      // If TRUE, next variable is significant
 167   EFI_PHYSICAL_ADDRESS  FormCallbackHandle; // If not 0, will update Formset with this info
 168   BOOLEAN               FormUpdate;         // If TRUE, next variable is significant
 169   UINT16                FormValue;          // specify which form is to be updated if FormUpdate value is TRUE.
 170   STRING_REF            FormTitle;          // If not 0, will update Form with this info
 171   UINT16                DataCount;          // The number of Data entries in this structure
 172   UINT8                 *Data;              // An array of 1+ op-codes, specified by DataCount
 173 } EFI_HII_UPDATE_DATA;
 174
 175 //
 176 // String attributes
 177 //
 178 #define LANG_RIGHT_TO_LEFT  0x00000001
 179
 180 //
 181 // A string package is used to localize strings to a particular
 182 // language.  The package is associated with a particular driver
 183 // or set of drivers.  Tools are used to associate tokens with
 184 // string references in forms and in programs.  These tokens are
 185 // language agnostic.  When paired with a language pack (directly
 186 // or indirectly), the string token resolves into an actual
 187 // UNICODE string.  The NumStringPointers determines how many
 188 // StringPointers (offset values) there are as well as the total
 189 // number of Strings that are defined.
 190 //
 191 typedef struct {
 192   EFI_HII_PACK_HEADER Header;
 193   RELOFST             LanguageNameString;
 194   RELOFST             PrintableLanguageName;
 195   UINT32              NumStringPointers;
 196   UINT32              Attributes;
 197   //
 198   //  RELOFST               StringPointers[];
 199   //  EFI_STRING            Strings[];
 200   //
 201 } EFI_HII_STRING_PACK;
 202
 203 //
 204 // Glyph Attributes
 205 //
 206 #define EFI_GLYPH_NON_SPACING   1
 207 #define EFI_GLYPH_WIDE          2
 208
 209 typedef struct {
 210   CHAR16  UnicodeWeight;
 211   UINT8   Attributes;
 212   UINT8   GlyphCol1[GLYPH_HEIGHT];
 213 } EFI_NARROW_GLYPH;
 214
 215 typedef struct {
 216   CHAR16  UnicodeWeight;
 217   UINT8   Attributes;
 218   UINT8   GlyphCol1[GLYPH_HEIGHT];
 219   UINT8   GlyphCol2[GLYPH_HEIGHT];
 220   UINT8   Pad[3];
 221 } EFI_WIDE_GLYPH;
 222
 223 //
 224 // A font list consists of a font header followed by a series
 225 // of glyph structures.  Note that fonts are not language specific.
 226 //
 227 typedef struct {
 228   EFI_HII_PACK_HEADER Header;
 229   UINT16              NumberOfNarrowGlyphs;
 230   UINT16              NumberOfWideGlyphs;
 231 } EFI_HII_FONT_PACK;
 232
 233 //
 234 // The IfrData in the EFI_HII_IFR_PACK structure definition
 235 // is variable length, and not really part of the header. To
 236 // simplify from code the size of the header, define an
 237 // identical structure that does not include the IfrData field.
 238 // Then use sizeof() this new structure to determine the
 239 // actual size of the header.
 240 //
 241 typedef struct {
 242   EFI_HII_PACK_HEADER Header;
 243 } EFI_HII_IFR_PACK_HEADER;
 244
 245 //
 246 // pedef EFI_HII_PACK_HEADER EFI_HII_IFR_PACK_HEADER;
 247 //
 248 typedef enum {
 249   EfiKeyLCtrl,
 250   EfiKeyA0,
 251   EfiKeyLAlt,
 252   EfiKeySpaceBar,
 253   EfiKeyA2,
 254   EfiKeyA3,
 255   EfiKeyA4,
 256   EfiKeyRCtrl,
 257   EfiKeyLeftArrow,
 258   EfiKeyDownArrow,
 259   EfiKeyRightArrow,
 260   EfiKeyZero,
 261   EfiKeyPeriod,
 262   EfiKeyEnter,
 263   EfiKeyLShift,
 264   EfiKeyB0,
 265   EfiKeyB1,
 266   EfiKeyB2,
 267   EfiKeyB3,
 268   EfiKeyB4,
 269   EfiKeyB5,
 270   EfiKeyB6,
 271   EfiKeyB7,
 272   EfiKeyB8,
 273   EfiKeyB9,
 274   EfiKeyB10,
 275   EfiKeyRshift,
 276   EfiKeyUpArrow,
 277   EfiKeyOne,
 278   EfiKeyTwo,
 279   EfiKeyThree,
 280   EfiKeyCapsLock,
 281   EfiKeyC1,
 282   EfiKeyC2,
 283   EfiKeyC3,
 284   EfiKeyC4,
 285   EfiKeyC5,
 286   EfiKeyC6,
 287   EfiKeyC7,
 288   EfiKeyC8,
 289   EfiKeyC9,
 290   EfiKeyC10,
 291   EfiKeyC11,
 292   EfiKeyC12,
 293   EfiKeyFour,
 294   EfiKeyFive,
 295   EfiKeySix,
 296   EfiKeyPlus,
 297   EfiKeyTab,
 298   EfiKeyD1,
 299   EfiKeyD2,
 300   EfiKeyD3,
 301   EfiKeyD4,
 302   EfiKeyD5,
 303   EfiKeyD6,
 304   EfiKeyD7,
 305   EfiKeyD8,
 306   EfiKeyD9,
 307   EfiKeyD10,
 308   EfiKeyD11,
 309   EfiKeyD12,
 310   EfiKeyD13,
 311   EfiKeyDel,
 312   EfiKeyEnd,
 313   EfiKeyPgDn,
 314   EfiKeySeven,
 315   EfiKeyEight,
 316   EfiKeyNine,
 317   EfiKeyE0,
 318   EfiKeyE1,
 319   EfiKeyE2,
 320   EfiKeyE3,
 321   EfiKeyE4,
 322   EfiKeyE5,
 323   EfiKeyE6,
 324   EfiKeyE7,
 325   EfiKeyE8,
 326   EfiKeyE9,
 327   EfiKeyE10,
 328   EfiKeyE11,
 329   EfiKeyE12,
 330   EfiKeyBackSpace,
 331   EfiKeyIns,
 332   EfiKeyHome,
 333   EfiKeyPgUp,
 334   EfiKeyNLck,
 335   EfiKeySlash,
 336   EfiKeyAsterisk,
 337   EfiKeyMinus,
 338   EfiKeyEsc,
 339   EfiKeyF1,
 340   EfiKeyF2,
 341   EfiKeyF3,
 342   EfiKeyF4,
 343   EfiKeyF5,
 344   EfiKeyF6,
 345   EfiKeyF7,
 346   EfiKeyF8,
 347   EfiKeyF9,
 348   EfiKeyF10,
 349   EfiKeyF11,
 350   EfiKeyF12,
 351   EfiKeyPrint,
 352   EfiKeySLck,
 353   EfiKeyPause
 354 } EFI_KEY;
 355
 356 typedef struct {
 357   EFI_KEY Key;
 358   CHAR16  Unicode;
 359   CHAR16  ShiftedUnicode;
 360   CHAR16  AltGrUnicode;
 361   CHAR16  ShiftedAltGrUnicode;
 362   UINT16  Modifier;
 363 } EFI_KEY_DESCRIPTOR;
 364
 365 //
 366 // This structure allows a sparse set of keys to be redefined
 367 // or a complete redefinition of the keyboard layout.  Most
 368 // keyboards have a lot of commonality in their layouts, therefore
 369 // only defining those keys that need to change from the default
 370 // minimizes the passed in information.
 371 //
 372 // Additionally, when an update occurs, the active keyboard layout
 373 // will be switched to the newly updated keyboard layout.  This
 374 // allows for situations that when a keyboard layout driver is
 375 // loaded as part of system initialization, the system will default
 376 // the keyboard behavior to the new layout.
 377 //
 378 // Each call to update the keyboard mapping should contain the
 379 // complete set of key descriptors to be updated, since every
 380 // call to the HII which contains an EFI_HII_KEYBOARD_PACK will
 381 // wipe the previous set of overrides.  A call to
 382 //
 383 typedef struct {
 384   EFI_HII_PACK_HEADER Header;
 385   EFI_KEY_DESCRIPTOR  *Descriptor;
 386   UINT8               DescriptorCount;
 387 } EFI_HII_KEYBOARD_PACK;
 388
 389 //
 390 // The EFI_HII_PACKAGES can contain different types of packages just
 391 // after the structure as inline data.
 392 //
 393 typedef struct {
 394   UINTN     NumberOfPackages;
 395   EFI_GUID  *GuidId;
 396   //
 397   // EFI_HII_HANDLE_PACK    *HandlePack;        // Only one pack.
 398   // EFI_HII_IFR_PACK       *IfrPack;           // Only one pack.
 399   // EFI_HII_FONT_PACK      *FontPack[];        // Multiple packs ok
 400   // EFI_HII_STRING_PACK    *StringPack[];      // Multiple packs ok
 401   // EFI_HII_KEYBOARD_PACK  *KeyboardPack[];    // Multiple packs ok
 402   //
 403 } EFI_HII_PACKAGES;
 404
 405 typedef struct _EFI_HII_VARIABLE_PACK_LIST {
 406   struct _EFI_HII_VARIABLE_PACK_LIST   *NextVariablePack;
 407   EFI_HII_VARIABLE_PACK                *VariablePack;
 408 } EFI_HII_VARIABLE_PACK_LIST;
 409
 410 #pragma pack()
 411
 412 /**
 413   Registers the various packs that are passed in via the Packages parameter.
 414
 415   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 416
 417   @param  Packages A pointer to an EFI_HII_PACKAGES package instance.
 418
 419   @param  Handle A pointer to the EFI_HII_HANDLE instance.
 420
 421   @retval EFI_SUCCESS Data was extracted from Packages, the database
 422   was updated with the data, and Handle returned successfully.
 423
 424   @retval EFI_INVALID_PARAMETER The content of Packages  was invalid.
 425
 426 **/
 427 typedef
 428 EFI_STATUS
 429 (EFIAPI *EFI_HII_NEW_PACK) (
 430   IN  EFI_HII_PROTOCOL    *This,
 431   IN  EFI_HII_PACKAGES    *Packages,
 432   OUT EFI_HII_HANDLE      *Handle
 433   );
 434
 435 /**
 436   Removes a package from the HII database.
 437
 438   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 439
 440   @param  Handle The handle that was registered to the data that is requested
 441   for removal.
 442
 443   @retval EFI_SUCCESS The data associated with the Handle was removed
 444   from the HII database.
 445
 446   @retval EFI_INVALID_PARAMETER The Handle was not valid.
 447
 448 **/
 449 typedef
 450 EFI_STATUS
 451 (EFIAPI *EFI_HII_REMOVE_PACK) (
 452   IN EFI_HII_PROTOCOL    *This,
 453   IN EFI_HII_HANDLE      Handle
 454   );
 455
 456 /**
 457   Determines the handles that are currently active in the database.
 458
 459   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 460
 461   @param  HandleBufferLength On input, a pointer to the length of the handle
 462   buffer. On output, the length of the handle buffer that is required
 463   for the handles found.
 464
 465   @param  Handle An array of EFI_HII_HANDLE instances returned.
 466
 467   @retval EFI_SUCCESS Handle was updated successfully.
 468
 469   @retval EFI_BUFFER_TOO_SMALL The HandleBufferLength parameter indicates
 470   that Handle is too small to support the number of handles.
 471
 472 **/
 473 typedef
 474 EFI_STATUS
 475 (EFIAPI *EFI_HII_FIND_HANDLES) (
 476   IN     EFI_HII_PROTOCOL *This,
 477   IN OUT UINT16           *HandleBufferLength,
 478   OUT    EFI_HII_HANDLE   *Handle
 479   );
 480
 481 /**
 482   Exports the contents of the database into a buffer.
 483
 484   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 485
 486   @param  Handle An EFI_HII_HANDLE that corresponds to the desired
 487   handle to export. If the value is 0, the entire database will be exported.
 488   In either case, the data will be exported in a format described by the
 489   structure definition of EFI_HII_EXPORT_TABLE.
 490
 491   @param  BufferSize
 492   On input, a pointer to the length of the buffer. On output, the length
 493   of the buffer that is required for the export data.
 494
 495   @param  Buffer A pointer to a buffer that will contain the results of the export function.
 496
 497   @retval EFI_SUCCESS The buffer was successfully filled with BufferSize amount of data.
 498
 499   @retval EFI_BUFFER_TOO_SMALL The value in BufferSize was too small to contain the export data.
 500
 501 **/
 502 typedef
 503 EFI_STATUS
 504 (EFIAPI *EFI_HII_EXPORT) (
 505   IN     EFI_HII_PROTOCOL *This,
 506   IN     EFI_HII_HANDLE   Handle,
 507   IN OUT UINTN            *BufferSize,
 508   OUT    VOID             *Buffer
 509   );
 510
 511 /**
 512   Remove any new strings that were added after the initial string export
 513   for this handle.
 514
 515   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 516
 517   @param  Handle The handle on which the string resides.
 518
 519   @retval EFI_SUCCESS Remove strings from the handle successfully.
 520
 521   @retval EFI_INVALID_PARAMETER The Handle was unknown.
 522
 523 **/
 524 typedef
 525 EFI_STATUS
 526 (EFIAPI *EFI_HII_RESET_STRINGS) (
 527   IN     EFI_HII_PROTOCOL   *This,
 528   IN     EFI_HII_HANDLE     Handle
 529   );
 530
 531 /**
 532   Tests if all of the characters in a string have corresponding font characters.
 533
 534   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 535
 536   @param  StringToTest A pointer to a Unicode string.
 537
 538   @param  FirstMissing A pointer to an index into the string. On input,
 539   the index of the first character in the StringToTest to examine. On exit,
 540   the index of the first character encountered for which a glyph is unavailable.
 541   If all glyphs in the string are available, the index is the index of the
 542   terminator of the string.
 543
 544   @param  GlyphBufferSize A pointer to a value. On output, if the function
 545   returns EFI_SUCCESS, it contains the amount of memory that is required to
 546   store the string¡¯s glyph equivalent.
 547
 548   @retval EFI_SUCCESS All glyphs are available. Note that an empty string
 549   always returns this value.
 550
 551   @retval EFI_NOT_FOUND A glyph was not found for a character.
 552
 553 **/
 554 typedef
 555 EFI_STATUS
 556 (EFIAPI *EFI_HII_TEST_STRING) (
 557   IN     EFI_HII_PROTOCOL  *This,
 558   IN     CHAR16            *StringToTest,
 559   IN OUT UINT32            *FirstMissing,
 560   OUT    UINT32            *GlyphBufferSize
 561   );
 562
 563 /**
 564   Translates a Unicode character into the corresponding font glyph.
 565
 566   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 567
 568   @param  Source A pointer to a Unicode string.
 569
 570   @param  Index On input, the offset into the string from which to fetch
 571   the character.On successful completion, the index is updated to the first
 572   character past the character(s) making up the just extracted glyph.
 573
 574   @param  GlyphBuffer Pointer to an array where the glyphs corresponding
 575   to the characters in the source may be stored. GlyphBuffer is assumed
 576   to be wide enough to accept a wide glyph character.
 577
 578   @param  BitWidth If EFI_SUCCESS was returned, the UINT16 pointed to by
 579   this value is filled with the length of the glyph in pixels. It is unchanged
 580   if the call was unsuccessful.
 581
 582   @param  InternalStatus The cell pointed to by this parameter must be
 583   initialized to zero prior to invoking the call the first time for any string.
 584
 585   @retval EFI_SUCCESS It worked.
 586
 587   @retval EFI_NOT_FOUND A glyph for a character was not found.
 588
 589 **/
 590 typedef
 591 EFI_STATUS
 592 (EFIAPI *EFI_HII_GET_GLYPH) (
 593   IN     EFI_HII_PROTOCOL  *This,
 594   IN     CHAR16            *Source,
 595   IN OUT UINT16            *Index,
 596   OUT    UINT8             **GlyphBuffer,
 597   OUT    UINT16            *BitWidth,
 598   IN OUT UINT32            *InternalStatus
 599   );
 600
 601 /**
 602   Translates a glyph into the format required for input to the Universal
 603   Graphics Adapter (UGA) Block Transfer (BLT) routines.
 604
 605   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 606
 607   @param  GlyphBuffer A pointer to the buffer that contains glyph data.
 608
 609   @param  Foreground The foreground setting requested to be used for the
 610   generated BltBuffer data.
 611
 612   @param  Background The background setting requested to be used for the
 613   generated BltBuffer data.
 614
 615   @param  Count The entry in the BltBuffer upon which to act.
 616
 617   @param  Width The width in bits of the glyph being converted.
 618
 619   @param  Height The height in bits of the glyph being converted
 620
 621   @param  BltBuffer A pointer to the buffer that contains the data that is
 622   ready to be used by the UGA BLT routines.
 623
 624   @retval EFI_SUCCESS It worked.
 625
 626   @retval EFI_NOT_FOUND A glyph for a character was not found.
 627
 628 **/
 629 typedef
 630 EFI_STATUS
 631 (EFIAPI *EFI_HII_GLYPH_TO_BLT) (
 632   IN     EFI_HII_PROTOCOL   *This,
 633   IN     UINT8              *GlyphBuffer,
 634   IN     EFI_UGA_PIXEL      Foreground,
 635   IN     EFI_UGA_PIXEL      Background,
 636   IN     UINTN              Count,
 637   IN     UINTN              Width,
 638   IN     UINTN              Height,
 639   IN OUT EFI_UGA_PIXEL      *BltBuffer
 640   );
 641
 642 /**
 643   Allows a new string to be added to an already existing string package.
 644
 645   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 646
 647   @param  Pointer to a NULL-terminated string containing a single ISO 639-2
 648   language identifier, indicating the language in which the string is translated.
 649
 650   @param  Handle The handle of the language pack to which the string is to be added.
 651
 652   @param  Reference The identifier of the string to be added. If the reference
 653   value is zero, then the string will be assigned a new identifier on that
 654   handle for the language specified. Otherwise, the string will be updated
 655   with the NewString Value.
 656
 657   @param  NewString The string to be added.
 658
 659   @retval EFI_SUCCESS The string was effectively registered.
 660
 661   @retval EFI_INVALID_PARAMETER The Handle was unknown.
 662
 663 **/
 664 typedef
 665 EFI_STATUS
 666 (EFIAPI *EFI_HII_NEW_STRING) (
 667   IN     EFI_HII_PROTOCOL      *This,
 668   IN     CHAR16                *Language,
 669   IN     EFI_HII_HANDLE        Handle,
 670   IN OUT STRING_REF            *Reference,
 671   IN     CHAR16                *NewString
 672   );
 673
 674 /**
 675   Allows a program to determine the primary languages that are supported
 676   on a given handle.
 677
 678   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 679
 680   @param  Handle The handle on which the strings reside.
 681
 682   @param  LanguageString A string allocated by GetPrimaryLanguages() that
 683   contains a list of all primary languages registered on the handle.
 684
 685   @retval EFI_SUCCESS LanguageString was correctly returned.
 686
 687   @retval EFI_INVALID_PARAMETER The Handle was unknown.
 688
 689 **/
 690 typedef
 691 EFI_STATUS
 692 (EFIAPI *EFI_HII_GET_PRI_LANGUAGES) (
 693   IN  EFI_HII_PROTOCOL    *This,
 694   IN  EFI_HII_HANDLE      Handle,
 695   OUT EFI_STRING          *LanguageString
 696   );
 697
 698 /**
 699   Allows a program to determine which secondary languages are supported
 700   on a given handle for a given primary language.
 701
 702   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 703
 704   @param  Handle The handle on which the strings reside.
 705
 706   @param  PrimaryLanguage Pointer to a NULL-terminated string containing a single
 707   ISO 639-2 language identifier, indicating the primary language.
 708
 709   @param  LanguageString A string allocated by GetSecondaryLanguages()
 710   containing a list of all secondary languages registered on the handle.
 711
 712   @retval EFI_SUCCESS LanguageString was correctly returned.
 713
 714   @retval EFI_INVALID_PARAMETER The Handle was unknown.
 715
 716 **/
 717 typedef
 718 EFI_STATUS
 719 (EFIAPI *EFI_HII_GET_SEC_LANGUAGES) (
 720   IN  EFI_HII_PROTOCOL    *This,
 721   IN  EFI_HII_HANDLE      Handle,
 722   IN  CHAR16              *PrimaryLanguage,
 723   OUT EFI_STRING          *LanguageString
 724   );
 725
 726 /**
 727   Extracts a string from a package already registered with the EFI HII database.
 728
 729   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 730
 731   @param  Handle The handle on which the string resides.
 732
 733   @param  Token The string token assigned to the string.
 734
 735   @param  Raw If TRUE, the string is returned unedited in the internal
 736   storage format described above. If false, the string returned is edited
 737   by replacing <cr> with <space> and by removing special characters such
 738   as the <wide> prefix.
 739
 740   @param  LanguageString Pointer to a NULL-terminated string containing a
 741   single ISO 639-2 language identifier, indicating the language to print.
 742   If the LanguageString is empty (starts with a NULL), the default system
 743   language will be used to determine the language.
 744
 745   @param  BufferLength Length of the StringBuffer.
 746
 747   @param  StringBuffer The buffer designed to receive the characters in the string.
 748
 749   @retval EFI_SUCCESS StringBuffer is filled with a NULL-terminated string.
 750
 751   @retval EFI_INVALID_PARAMETER The handle or string token is unknown.
 752
 753   @retval EFI_BUFFER_TOO_SMALL The buffer provided was not large enough to
 754   allow the entire string to be stored.
 755
 756 **/
 757 typedef
 758 EFI_STATUS
 759 (EFIAPI *EFI_HII_GET_STRING) (
 760   IN     EFI_HII_PROTOCOL  *This,
 761   IN     EFI_HII_HANDLE    Handle,
 762   IN     STRING_REF        Token,
 763   IN     BOOLEAN           Raw,
 764   IN     CHAR16            *LanguageString,
 765   IN OUT UINTN             *BufferLength,
 766   OUT    EFI_STRING        StringBuffer
 767   );
 768
 769 /**
 770   Allows a program to extract a part of a string of not more than a given width.
 771
 772   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 773
 774   @param  Handle The handle on which the string resides.
 775
 776   @param  Token The string token assigned to the string.
 777
 778   @param  Index On input, the offset into the string where the line is to start.
 779   On output, the index is updated to point to beyond the last character returned
 780   in the call.
 781
 782   @param  LineWidth The maximum width of the line in units of narrow glyphs.
 783
 784   @param  LanguageString Pointer to a NULL-terminated string containing a
 785   single ISO 639-2 language identifier, indicating the language to print.
 786
 787   @param  BufferLength Pointer to the length of the StringBuffer.
 788
 789   @param  StringBuffer The buffer designed to receive the characters in the string.
 790
 791   @retval EFI_SUCCESS StringBuffer filled with characters that will fit on the line.
 792
 793   @retval EFI_NOT_FOUND The font glyph for at least one of the characters in
 794   the string is not in the font database.
 795
 796   @retval EFI_BUFFER_TOO_SMALL The buffer provided was not large enough
 797   to allow the entire string to be stored.
 798
 799 **/
 800 typedef
 801 EFI_STATUS
 802 (EFIAPI *EFI_HII_GET_LINE) (
 803   IN     EFI_HII_PROTOCOL  *This,
 804   IN     EFI_HII_HANDLE    Handle,
 805   IN     STRING_REF        Token,
 806   IN OUT UINT16            *Index,
 807   IN     UINT16            LineWidth,
 808   IN     CHAR16            *LanguageString,
 809   IN OUT UINT16            *BufferLength,
 810   OUT    EFI_STRING        StringBuffer
 811   );
 812
 813 /**
 814   Allows a program to extract a form or form package that has previously
 815   been registered with the HII database.
 816
 817   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 818
 819   @param  Handle Handle on which the form resides.
 820
 821   @param  FormId The ID of the form to return. If the ID is zero,
 822   the entire form package is returned.
 823
 824   @param  BufferLength On input, the length of the Buffer. On output,
 825   the length of the returned buffer,
 826
 827   @param  Buffer The buffer designed to receive the form(s).
 828
 829   @retval EFI_SUCCESS Buffer filled with the requested forms. BufferLength
 830   was updated.
 831
 832   @retval EFI_INVALID_PARAMETER The handle is unknown.
 833
 834   @retval EFI_NOT_FOUND A form on the requested handle cannot be found with
 835   the requested FormId.
 836
 837   @retval EFI_BUFFER_TOO_SMALL The buffer provided was not large enough
 838   to allow the form to be stored.
 839
 840 **/
 841 typedef
 842 EFI_STATUS
 843 (EFIAPI *EFI_HII_GET_FORMS) (
 844   IN     EFI_HII_PROTOCOL  *This,
 845   IN     EFI_HII_HANDLE    Handle,
 846   IN     EFI_FORM_ID       FormId,
 847   IN OUT UINTN             *BufferLength,
 848   OUT    UINT8             *Buffer
 849   );
 850
 851 /**
 852   Extracts the defaults that are associated with a given handle in the HII database.
 853
 854   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 855
 856   @param  Handle The HII handle from which will have default data retrieved.
 857
 858   @param  DefaultMask The mask used to specify some type of default override when extracting
 859   the default image data.
 860
 861   @param  VariablePackList A indirect pointer to the first entry of a link list with
 862   type EFI_HII_VARIABLE_PACK_LIST.
 863
 864   @retval EFI_SUCCESS The VariablePackList was populated with the appropriate
 865   default setting data.
 866
 867   @retval EFI_NOT_FOUND The IFR does not have any explicit or default map(s).
 868
 869   @retval EFI_INVALID_PARAMETER The HII database entry associated with Handle
 870   contain invalid data.
 871
 872 **/
 873 typedef
 874 EFI_STATUS
 875 (EFIAPI *EFI_HII_GET_DEFAULT_IMAGE) (
 876   IN     EFI_HII_PROTOCOL           *This,
 877   IN     EFI_HII_HANDLE             Handle,
 878   IN     UINTN                      DefaultMask,
 879   OUT    EFI_HII_VARIABLE_PACK_LIST **VariablePackList
 880   );
 881
 882 /**
 883   Allows the caller to update a form or form package that has previously been
 884   registered with the EFI HII database.
 885
 886   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 887
 888   @param  Handle Handle of the package where the form to be updated resides.
 889
 890   @param  Label The label inside the form package where the update is to take place.
 891
 892   @param  AddData If TRUE, adding data at a given Label; otherwise,
 893   if FALSE, removing data at a given Label.
 894
 895   @param  Data The buffer containing the new tags to insert after the Label
 896
 897   @retval EFI_SUCCESS The form was updated with the new tags.
 898
 899   @retval EFI_INVALID_PARAMETER The buffer for the buffer length does not
 900   contain an integral number of tags.
 901
 902   @retval EFI_NOT_FOUND The Handle, Label, or FormId was not found.
 903
 904 **/
 905 typedef
 906 EFI_STATUS
 907 (EFIAPI *EFI_HII_UPDATE_FORM) (
 908   IN EFI_HII_PROTOCOL     *This,
 909   IN EFI_HII_HANDLE       Handle,
 910   IN EFI_FORM_LABEL       Label,
 911   IN BOOLEAN              AddData,
 912   IN EFI_HII_UPDATE_DATA  *Data
 913   );
 914
 915 /**
 916   Retrieves the current keyboard layout.
 917
 918   @param  This A pointer to the EFI_HII_PROTOCOL instance.
 919
 920   @param  DescriptorCount A pointer to the number of Descriptor entries being
 921   described in the keyboard layout being retrieved.
 922
 923   @param  Descriptor A pointer to a buffer containing an array of EFI_KEY_DESCRIPTOR
 924   entries. Each entry will reflect the definition of a specific physical key.
 925
 926   @retval EFI_SUCCESS The keyboard layout was retrieved successfully.
 927
 928 **/
 929 typedef
 930 EFI_STATUS
 931 (EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT) (
 932   IN     EFI_HII_PROTOCOL    *This,
 933   OUT    UINT16              *DescriptorCount,
 934   OUT    EFI_KEY_DESCRIPTOR  *Descriptor
 935   );
 936
 937 /**
 938   @par Protocol Description:
 939   The HII Protocol manages the HII database, which is a repository for data
 940   having to do with fonts, strings, forms, keyboards, and other future human
 941   interface items.
 942
 943   @param NewPack
 944   Extracts the various packs from a package list.
 945
 946   @param RemovePack
 947   Removes a package from the HII database.
 948
 949   @param FindHandles
 950   Determines the handles that are currently active in the database.
 951
 952   @param ExportDatabase
 953   Export the entire contents of the database to a buffer.
 954
 955   @param TestString
 956   Tests if all of the characters in a string have corresponding font characters.
 957
 958   @param GetGlyph
 959   Translates a Unicode character into the corresponding font glyph.
 960
 961   @param GlyphToBlt
 962   Converts a glyph value into a format that is ready for a UGA BLT command.
 963
 964   @param NewString
 965   Allows a new string to be added to an already existing string package.
 966
 967   @param GetPrimaryLanguages
 968   Allows a program to determine the primary languages that are supported
 969   on a given handle.
 970
 971   @param GetSecondaryLanguages
 972   Allows a program to determine which secondary languages are supported
 973   on a given handle for a given primary language.
 974
 975   @param GetString
 976   Extracts a string from a package that is already registered with the
 977   EFI HII database.
 978
 979   @param ResetString
 980   Remove any new strings that were added after the initial string export
 981   for this handle.
 982
 983   @param GetLine
 984   Allows a program to extract a part of a string of not more than a given width.
 985
 986   @param GetForms
 987   Allows a program to extract a form or form package that has been previously registered.
 988
 989   @param GetDefaultImage
 990   Allows a program to extract the nonvolatile image that represents the default storage image.
 991
 992   @param UpdateForm
 993   Allows a program to update a previously registered form.
 994
 995   @param GetKeyboardLayout
 996   Allows a program to extract the current keyboard layout.
 997
 998 **/
 999 struct _EFI_HII_PROTOCOL {
1000   EFI_HII_NEW_PACK            NewPack;
1001   EFI_HII_REMOVE_PACK         RemovePack;
1002   EFI_HII_FIND_HANDLES        FindHandles;
1003   EFI_HII_EXPORT              ExportDatabase;
1004
1005   EFI_HII_TEST_STRING         TestString;
1006   EFI_HII_GET_GLYPH           GetGlyph;
1007   EFI_HII_GLYPH_TO_BLT        GlyphToBlt;
1008
1009   EFI_HII_NEW_STRING          NewString;
1010   EFI_HII_GET_PRI_LANGUAGES   GetPrimaryLanguages;
1011   EFI_HII_GET_SEC_LANGUAGES   GetSecondaryLanguages;
1012   EFI_HII_GET_STRING          GetString;
1013   EFI_HII_RESET_STRINGS       ResetStrings;
1014   EFI_HII_GET_LINE            GetLine;
1015   EFI_HII_GET_FORMS           GetForms;
1016   EFI_HII_GET_DEFAULT_IMAGE   GetDefaultImage;
1017   EFI_HII_UPDATE_FORM         UpdateForm;
1018
1019   EFI_HII_GET_KEYBOARD_LAYOUT GetKeyboardLayout;
1020 };
1021
1022 extern EFI_GUID gEfiHiiProtocolGuid;
1023
1024 #endif