MdeModulePkg/Universal/HiiDatabaseDxe/HiiDatabase.h

   1 /** @file
   2 Private structures definitions in HiiDatabase.
   3
   4 Copyright (c) 2007 - 2008, Intel Corporation
   5 All rights reserved. This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __HII_DATABASE_PRIVATE_H__
  16 #define __HII_DATABASE_PRIVATE_H__
  17
  18 #include <Uefi.h>
  19
  20 #include <Protocol/ConsoleControl.h>
  21 #include <Protocol/DevicePath.h>
  22 #include <Protocol/HiiFont.h>
  23 #include <Protocol/HiiImage.h>
  24 #include <Protocol/HiiString.h>
  25 #include <Protocol/HiiDatabase.h>
  26 #include <Protocol/HiiConfigRouting.h>
  27 #include <Protocol/HiiConfigAccess.h>
  28 #include <Protocol/SimpleTextOut.h>
  29
  30 #include <Guid/HiiKeyBoardLayout.h>
  31
  32
  33 #include <Library/DebugLib.h>
  34 #include <Library/BaseMemoryLib.h>
  35 #include <Library/UefiDriverEntryPoint.h>
  36 #include <Library/UefiBootServicesTableLib.h>
  37 #include <Library/BaseLib.h>
  38 #include <Library/DevicePathLib.h>
  39 #include <Library/MemoryAllocationLib.h>
  40 #include <Library/IfrSupportLib.h>
  41 #include <Library/HiiLib.h>
  42 #include <Library/PcdLib.h>
  43
  44 #define HII_DATABASE_NOTIFY_GUID \
  45   { \
  46     0xc1c76, 0xd79e, 0x42fe, {0x86, 0xb, 0x8b, 0xe8, 0x7b, 0x3e, 0x7a, 0x78} \
  47   }
  48
  49 #define MAX_STRING_LENGTH                  1024
  50 #define MAX_FONT_NAME_LEN                  256
  51 #define NARROW_BASELINE                    15
  52 #define WIDE_BASELINE                      14
  53 #define SYS_FONT_INFO_MASK                 0x37
  54 #define REPLACE_UNKNOWN_GLYPH              0xFFFD
  55 #define PROPORTIONAL_GLYPH                 0x80
  56 #define NARROW_GLYPH                       0x40
  57
  58 #define BITMAP_LEN_1_BIT(Width, Height)  (((Width) + 7) / 8 * (Height))
  59 #define BITMAP_LEN_4_BIT(Width, Height)  (((Width) + 1) / 2 * (Height))
  60 #define BITMAP_LEN_8_BIT(Width, Height)  ((Width) * (Height))
  61 #define BITMAP_LEN_24_BIT(Width, Height) ((Width) * (Height) * 3)
  62
  63 //
  64 // Storage types
  65 //
  66 #define EFI_HII_VARSTORE_BUFFER            0
  67 #define EFI_HII_VARSTORE_NAME_VALUE        1
  68 #define EFI_HII_VARSTORE_EFI_VARIABLE      2
  69
  70 #define HII_FORMSET_STORAGE_SIGNATURE           EFI_SIGNATURE_32 ('H', 'S', 'T', 'G')
  71 typedef struct {
  72   UINTN               Signature;
  73   LIST_ENTRY          Entry;
  74
  75   EFI_HII_HANDLE      HiiHandle;
  76   EFI_HANDLE          DriverHandle;
  77
  78   UINT8               Type;   // EFI_HII_VARSTORE_BUFFER, EFI_HII_VARSTORE_NAME_VALUE, EFI_HII_VARSTORE_EFI_VARIABLE
  79   EFI_GUID            Guid;
  80   CHAR16              *Name;
  81   UINT16              Size;
  82 } HII_FORMSET_STORAGE;
  83
  84 #define HII_FORMSET_STORAGE_FROM_LINK(a)  CR (a, HII_FORMSET_STORAGE, Link, HII_FORMSET_STORAGE_SIGNATURE)
  85
  86
  87 //
  88 // String Package definitions
  89 //
  90 #define HII_STRING_PACKAGE_SIGNATURE    EFI_SIGNATURE_32 ('h','i','s','p')
  91 typedef struct _HII_STRING_PACKAGE_INSTANCE {
  92   UINTN                                 Signature;
  93   EFI_HII_STRING_PACKAGE_HDR            *StringPkgHdr;
  94   UINT8                                 *StringBlock;
  95   LIST_ENTRY                            StringEntry;
  96   LIST_ENTRY                            FontInfoList;  // local font info list
  97   UINT8                                 FontId;
  98 } HII_STRING_PACKAGE_INSTANCE;
  99
 100 //
 101 // Form Package definitions
 102 //
 103 #define HII_IFR_PACKAGE_SIGNATURE       EFI_SIGNATURE_32 ('h','f','r','p')
 104 typedef struct _HII_IFR_PACKAGE_INSTANCE {
 105   UINTN                                 Signature;
 106   EFI_HII_PACKAGE_HEADER                FormPkgHdr;
 107   UINT8                                 *IfrData;
 108   LIST_ENTRY                            IfrEntry;
 109 } HII_IFR_PACKAGE_INSTANCE;
 110
 111 //
 112 // Simple Font Package definitions
 113 //
 114 #define HII_S_FONT_PACKAGE_SIGNATURE    EFI_SIGNATURE_32 ('h','s','f','p')
 115 typedef struct _HII_SIMPLE_FONT_PACKAGE_INSTANCE {
 116   UINTN                                 Signature;
 117   EFI_HII_SIMPLE_FONT_PACKAGE_HDR       *SimpleFontPkgHdr;
 118   LIST_ENTRY                            SimpleFontEntry;
 119 } HII_SIMPLE_FONT_PACKAGE_INSTANCE;
 120
 121 //
 122 // Font Package definitions
 123 //
 124 #define HII_FONT_PACKAGE_SIGNATURE      EFI_SIGNATURE_32 ('h','i','f','p')
 125 typedef struct _HII_FONT_PACKAGE_INSTANCE {
 126   UINTN                                 Signature;
 127   EFI_HII_FONT_PACKAGE_HDR              *FontPkgHdr;
 128   UINT8                                 *GlyphBlock;
 129   LIST_ENTRY                            FontEntry;
 130   LIST_ENTRY                            GlyphInfoList;
 131 } HII_FONT_PACKAGE_INSTANCE;
 132
 133 #define HII_GLYPH_INFO_SIGNATURE        EFI_SIGNATURE_32 ('h','g','i','s')
 134 typedef struct _HII_GLYPH_INFO {
 135   UINTN                                 Signature;
 136   LIST_ENTRY                            Entry;
 137   CHAR16                                CharId;
 138   EFI_HII_GLYPH_INFO                    Cell;
 139 } HII_GLYPH_INFO;
 140
 141 #define HII_FONT_INFO_SIGNATURE         EFI_SIGNATURE_32 ('h','l','f','i')
 142 typedef struct _HII_FONT_INFO {
 143   UINTN                                 Signature;
 144   LIST_ENTRY                            Entry;
 145   LIST_ENTRY                            *GlobalEntry;
 146   UINT8                                 FontId;
 147 } HII_FONT_INFO;
 148
 149 #define HII_GLOBAL_FONT_INFO_SIGNATURE  EFI_SIGNATURE_32 ('h','g','f','i')
 150 typedef struct _HII_GLOBAL_FONT_INFO {
 151   UINTN                                 Signature;
 152   LIST_ENTRY                            Entry;
 153   HII_FONT_PACKAGE_INSTANCE             *FontPackage;
 154   UINTN                                 FontInfoSize;
 155   EFI_FONT_INFO                         *FontInfo;
 156 } HII_GLOBAL_FONT_INFO;
 157
 158 //
 159 // Image Package definitions
 160 //
 161
 162 #define HII_PIXEL_MASK                  0x80
 163
 164 typedef struct _HII_IMAGE_PACKAGE_INSTANCE {
 165   EFI_HII_IMAGE_PACKAGE_HDR             ImagePkgHdr;
 166   UINT32                                ImageBlockSize;
 167   UINT32                                PaletteInfoSize;
 168   UINT8                                 *ImageBlock;
 169   UINT8                                 *PaletteBlock;
 170 } HII_IMAGE_PACKAGE_INSTANCE;
 171
 172 //
 173 // Keyboard Layout Pacakge definitions
 174 //
 175 #define HII_KB_LAYOUT_PACKAGE_SIGNATURE EFI_SIGNATURE_32 ('h','k','l','p')
 176 typedef struct _HII_KEYBOARD_LAYOUT_PACKAGE_INSTANCE {
 177   UINTN                                 Signature;
 178   UINT8                                 *KeyboardPkg;
 179   LIST_ENTRY                            KeyboardEntry;
 180 } HII_KEYBOARD_LAYOUT_PACKAGE_INSTANCE;
 181
 182 //
 183 // Guid Package definitions
 184 //
 185 #define HII_GUID_PACKAGE_SIGNATURE      EFI_SIGNATURE_32 ('h','i','g','p')
 186 typedef struct _HII_GUID_PACKAGE_INSTANCE {
 187   UINTN                                 Signature;
 188   UINT8                                 *GuidPkg;
 189   LIST_ENTRY                            GuidEntry;
 190 } HII_GUID_PACKAGE_INSTANCE;
 191
 192 //
 193 // A package list can contain only one or less than one device path package.
 194 // This rule also applies to image package since ImageId can not be duplicate.
 195 //
 196 typedef struct _HII_DATABASE_PACKAGE_LIST_INSTANCE {
 197   EFI_HII_PACKAGE_LIST_HEADER           PackageListHdr;
 198   LIST_ENTRY                            GuidPkgHdr;
 199   LIST_ENTRY                            FormPkgHdr;
 200   LIST_ENTRY                            KeyboardLayoutHdr;
 201   LIST_ENTRY                            StringPkgHdr;
 202   LIST_ENTRY                            FontPkgHdr;
 203   HII_IMAGE_PACKAGE_INSTANCE            *ImagePkg;
 204   LIST_ENTRY                            SimpleFontPkgHdr;
 205   UINT8                                 *DevicePathPkg;
 206 } HII_DATABASE_PACKAGE_LIST_INSTANCE;
 207
 208 #define HII_HANDLE_SIGNATURE            EFI_SIGNATURE_32 ('h','i','h','l')
 209
 210 typedef struct {
 211   UINTN               Signature;
 212   LIST_ENTRY          Handle;
 213   UINTN               Key;
 214 } HII_HANDLE;
 215
 216 #define HII_DATABASE_RECORD_SIGNATURE   EFI_SIGNATURE_32 ('h','i','d','r')
 217
 218 typedef struct _HII_DATABASE_RECORD {
 219   UINTN                                 Signature;
 220   HII_DATABASE_PACKAGE_LIST_INSTANCE    *PackageList;
 221   EFI_HANDLE                            DriverHandle;
 222   EFI_HII_HANDLE                        Handle;
 223   LIST_ENTRY                            DatabaseEntry;
 224 } HII_DATABASE_RECORD;
 225
 226 #define HII_DATABASE_NOTIFY_SIGNATURE   EFI_SIGNATURE_32 ('h','i','d','n')
 227
 228 typedef struct _HII_DATABASE_NOTIFY {
 229   UINTN                                 Signature;
 230   EFI_HANDLE                            NotifyHandle;
 231   UINT8                                 PackageType;
 232   EFI_GUID                              *PackageGuid;
 233   EFI_HII_DATABASE_NOTIFY               PackageNotifyFn;
 234   EFI_HII_DATABASE_NOTIFY_TYPE          NotifyType;
 235   LIST_ENTRY                            DatabaseNotifyEntry;
 236 } HII_DATABASE_NOTIFY;
 237
 238 #define HII_DATABASE_PRIVATE_DATA_SIGNATURE EFI_SIGNATURE_32 ('H', 'i', 'D', 'p')
 239
 240 typedef struct _HII_DATABASE_PRIVATE_DATA {
 241   UINTN                                 Signature;
 242   LIST_ENTRY                            DatabaseList;
 243   LIST_ENTRY                            DatabaseNotifyList;
 244   EFI_HII_FONT_PROTOCOL                 HiiFont;
 245   EFI_HII_IMAGE_PROTOCOL                HiiImage;
 246   EFI_HII_STRING_PROTOCOL               HiiString;
 247   EFI_HII_DATABASE_PROTOCOL             HiiDatabase;
 248   EFI_HII_CONFIG_ROUTING_PROTOCOL       ConfigRouting;
 249   LIST_ENTRY                            HiiHandleList;
 250   INTN                                  HiiHandleCount;
 251   LIST_ENTRY                            FontInfoList;  // global font info list
 252   UINTN                                 Attribute;     // default system color
 253   EFI_GUID                              CurrentLayoutGuid;
 254   EFI_HII_KEYBOARD_LAYOUT               *CurrentLayout;
 255 } HII_DATABASE_PRIVATE_DATA;
 256
 257 #define HII_FONT_DATABASE_PRIVATE_DATA_FROM_THIS(a) \
 258   CR (a, \
 259       HII_DATABASE_PRIVATE_DATA, \
 260       HiiFont, \
 261       HII_DATABASE_PRIVATE_DATA_SIGNATURE \
 262       )
 263
 264 #define HII_IMAGE_DATABASE_PRIVATE_DATA_FROM_THIS(a) \
 265   CR (a, \
 266       HII_DATABASE_PRIVATE_DATA, \
 267       HiiImage, \
 268       HII_DATABASE_PRIVATE_DATA_SIGNATURE \
 269       )
 270
 271 #define HII_STRING_DATABASE_PRIVATE_DATA_FROM_THIS(a) \
 272   CR (a, \
 273       HII_DATABASE_PRIVATE_DATA, \
 274       HiiString, \
 275       HII_DATABASE_PRIVATE_DATA_SIGNATURE \
 276       )
 277
 278 #define HII_DATABASE_DATABASE_PRIVATE_DATA_FROM_THIS(a) \
 279   CR (a, \
 280       HII_DATABASE_PRIVATE_DATA, \
 281       HiiDatabase, \
 282       HII_DATABASE_PRIVATE_DATA_SIGNATURE \
 283       )
 284
 285 #define CONFIG_ROUTING_DATABASE_PRIVATE_DATA_FROM_THIS(a) \
 286   CR (a, \
 287       HII_DATABASE_PRIVATE_DATA, \
 288       ConfigRouting, \
 289       HII_DATABASE_PRIVATE_DATA_SIGNATURE \
 290       )
 291
 292 //
 293 // Internal function prototypes.
 294 //
 295
 296 /**
 297   This function checks whether a handle is a valid EFI_HII_HANDLE.
 298
 299   @param  Handle                  Pointer to a EFI_HII_HANDLE
 300
 301   @retval TRUE                    Valid
 302   @retval FALSE                   Invalid
 303
 304 **/
 305 BOOLEAN
 306 IsHiiHandleValid (
 307   EFI_HII_HANDLE Handle
 308   );
 309
 310
 311 /**
 312   This function checks whether EFI_FONT_INFO exists in current database. If
 313   FontInfoMask is specified, check what options can be used to make a match.
 314   Note that the masks relate to where the system default should be supplied
 315   are ignored by this function.
 316
 317   @param  Private                 Hii database private structure.
 318   @param  FontInfo                Points to EFI_FONT_INFO structure.
 319   @param  FontInfoMask            If not NULL, describes what options can be used
 320                                   to make a match between the font requested and
 321                                   the font available. The caller must guarantee
 322                                   this mask is valid.
 323   @param  FontHandle              On entry, Points to the font handle returned by a
 324                                   previous  call to GetFontInfo() or NULL to start
 325                                   with the first font.
 326   @param  GlobalFontInfo          If not NULL, output the corresponding globa font
 327                                   info.
 328
 329   @retval TRUE                    Existed
 330   @retval FALSE                   Not existed
 331
 332 **/
 333 BOOLEAN
 334 IsFontInfoExisted (
 335   IN  HII_DATABASE_PRIVATE_DATA *Private,
 336   IN  EFI_FONT_INFO             *FontInfo,
 337   IN  EFI_FONT_INFO_MASK        *FontInfoMask,   OPTIONAL
 338   IN  EFI_FONT_HANDLE           FontHandle,      OPTIONAL
 339   OUT HII_GLOBAL_FONT_INFO      **GlobalFontInfo OPTIONAL
 340   );
 341
 342
 343 /**
 344   Retrieve system default font and color.
 345
 346   @param  Private                 HII database driver private data.
 347   @param  FontInfo                Points to system default font output-related
 348                                   information. It's caller's responsibility to free
 349                                   this buffer.
 350   @param  FontInfoSize            If not NULL, output the size of buffer FontInfo.
 351
 352   @retval EFI_SUCCESS             Cell information is added to the GlyphInfoList.
 353   @retval EFI_OUT_OF_RESOURCES    The system is out of resources to accomplish the
 354                                   task.
 355   @retval EFI_INVALID_PARAMETER   Any input parameter is invalid.
 356
 357 **/
 358 EFI_STATUS
 359 GetSystemFont (
 360   IN  HII_DATABASE_PRIVATE_DATA      *Private,
 361   OUT EFI_FONT_DISPLAY_INFO          **FontInfo,
 362   OUT UINTN                          *FontInfoSize OPTIONAL
 363   );
 364
 365
 366 /**
 367   Parse all string blocks to find a String block specified by StringId.
 368   If StringId = (EFI_STRING_ID) (-1), find out all EFI_HII_SIBT_FONT blocks
 369   within this string package and backup its information.
 370   If StringId = 0, output the string id of last string block (EFI_HII_SIBT_END).
 371
 372   @param  Private                 Hii database private structure.
 373   @param  StringPackage           Hii string package instance.
 374   @param  StringId                The string's id, which is unique within
 375                                   PackageList.
 376   @param  BlockType               Output the block type of found string block.
 377   @param  StringBlockAddr         Output the block address of found string block.
 378   @param  StringTextOffset        Offset, relative to the found block address, of
 379                                   the  string text information.
 380   @param  LastStringId            Output the last string id when StringId = 0.
 381
 382   @retval EFI_SUCCESS             The string text and font is retrieved
 383                                   successfully.
 384   @retval EFI_NOT_FOUND           The specified text or font info can not be found
 385                                   out.
 386   @retval EFI_OUT_OF_RESOURCES    The system is out of resources to accomplish the
 387                                   task.
 388
 389 **/
 390 EFI_STATUS
 391 FindStringBlock (
 392   IN HII_DATABASE_PRIVATE_DATA        *Private,
 393   IN  HII_STRING_PACKAGE_INSTANCE     *StringPackage,
 394   IN  EFI_STRING_ID                   StringId,
 395   OUT UINT8                           *BlockType, OPTIONAL
 396   OUT UINT8                           **StringBlockAddr, OPTIONAL
 397   OUT UINTN                           *StringTextOffset, OPTIONAL
 398   OUT EFI_STRING_ID                   *LastStringId OPTIONAL
 399   );
 400
 401
 402 /**
 403   Parse all glyph blocks to find a glyph block specified by CharValue.
 404   If CharValue = (CHAR16) (-1), collect all default character cell information
 405   within this font package and backup its information.
 406
 407   @param  FontPackage             Hii string package instance.
 408   @param  CharValue               Unicode character value, which identifies a glyph
 409                                   block.
 410   @param  GlyphBuffer             Output the corresponding bitmap data of the found
 411                                   block. It is the caller's responsiblity to free
 412                                   this buffer.
 413   @param  Cell                    Output cell information of the encoded bitmap.
 414   @param  GlyphBufferLen          If not NULL, output the length of GlyphBuffer.
 415
 416   @retval EFI_SUCCESS             The bitmap data is retrieved successfully.
 417   @retval EFI_NOT_FOUND           The specified CharValue does not exist in current
 418                                   database.
 419   @retval EFI_OUT_OF_RESOURCES    The system is out of resources to accomplish the
 420                                   task.
 421
 422 **/
 423 EFI_STATUS
 424 FindGlyphBlock (
 425   IN  HII_FONT_PACKAGE_INSTANCE      *FontPackage,
 426   IN  CHAR16                         CharValue,
 427   OUT UINT8                          **GlyphBuffer, OPTIONAL
 428   OUT EFI_HII_GLYPH_INFO             *Cell, OPTIONAL
 429   OUT UINTN                          *GlyphBufferLen OPTIONAL
 430   );
 431
 432 //
 433 // EFI_HII_FONT_PROTOCOL protocol interfaces
 434 //
 435
 436
 437 /**
 438   Renders a string to a bitmap or to the display.
 439
 440   @param  This                    A pointer to the EFI_HII_FONT_PROTOCOL instance.
 441   @param  Flags                   Describes how the string is to be drawn.
 442   @param  String                  Points to the null-terminated string to be
 443                                   displayed.
 444   @param  StringInfo              Points to the string output information,
 445                                   including the color and font.  If NULL, then the
 446                                   string will be output in the default system font
 447                                   and color.
 448   @param  Blt                     If this points to a non-NULL on entry, this
 449                                   points to the image, which is Width pixels   wide
 450                                   and Height pixels high. The string will be drawn
 451                                   onto this image and
 452                                   EFI_HII_OUT_FLAG_CLIP is implied. If this points
 453                                   to a NULL on entry, then a              buffer
 454                                   will be allocated to hold the generated image and
 455                                   the pointer updated on exit. It is the caller's
 456                                   responsibility to free this buffer.
 457   @param  BltX                    Together with BltX, Specifies the offset from the left and top edge
 458                                   of the image of the first character cell in the
 459                                   image.
 460   @param  BltY                    Together with BltY, Specifies the offset from the left and top edge
 461                                   of the image of the first character cell in the
 462                                   image.
 463   @param  RowInfoArray            If this is non-NULL on entry, then on exit, this
 464                                   will point to an allocated buffer    containing
 465                                   row information and RowInfoArraySize will be
 466                                   updated to contain the        number of elements.
 467                                   This array describes the characters which were at
 468                                   least partially drawn and the heights of the
 469                                   rows. It is the caller's responsibility to free
 470                                   this buffer.
 471   @param  RowInfoArraySize        If this is non-NULL on entry, then on exit it
 472                                   contains the number of elements in RowInfoArray.
 473   @param  ColumnInfoArray         If this is non-NULL, then on return it will be
 474                                   filled with the horizontal offset for each
 475                                   character in the string on the row where it is
 476                                   displayed. Non-printing characters will     have
 477                                   the offset ~0. The caller is responsible to
 478                                   allocate a buffer large enough so that    there
 479                                   is one entry for each character in the string,
 480                                   not including the null-terminator. It is possible
 481                                   when character display is normalized that some
 482                                   character cells overlap.
 483
 484   @retval EFI_SUCCESS             The string was successfully rendered.
 485   @retval EFI_OUT_OF_RESOURCES    Unable to allocate an output buffer for
 486                                   RowInfoArray or Blt.
 487   @retval EFI_INVALID_PARAMETER The String or Blt.
 488   @retval EFI_INVALID_PARAMETER Flags were invalid combination..
 489
 490 **/
 491 EFI_STATUS
 492 EFIAPI
 493 HiiStringToImage (
 494   IN  CONST EFI_HII_FONT_PROTOCOL    *This,
 495   IN  EFI_HII_OUT_FLAGS              Flags,
 496   IN  CONST EFI_STRING               String,
 497   IN  CONST EFI_FONT_DISPLAY_INFO    *StringInfo       OPTIONAL,
 498   IN  OUT EFI_IMAGE_OUTPUT           **Blt,
 499   IN  UINTN                          BltX,
 500   IN  UINTN                          BltY,
 501   OUT EFI_HII_ROW_INFO               **RowInfoArray    OPTIONAL,
 502   OUT UINTN                          *RowInfoArraySize OPTIONAL,
 503   OUT UINTN                          *ColumnInfoArray  OPTIONAL
 504   );
 505
 506
 507 /**
 508   Render a string to a bitmap or the screen containing the contents of the specified string.
 509
 510   @param  This                    A pointer to the EFI_HII_FONT_PROTOCOL instance.
 511   @param  Flags                   Describes how the string is to be drawn.
 512   @param  PackageList             The package list in the HII database to search
 513                                   for the specified string.
 514   @param  StringId                The string's id, which is unique within
 515                                   PackageList.
 516   @param  Language                Points to the language for the retrieved string.
 517                                   If NULL, then the current system language is
 518                                   used.
 519   @param  StringInfo              Points to the string output information,
 520                                   including the color and font.  If NULL, then the
 521                                   string will be output in the default system font
 522                                   and color.
 523   @param  Blt                     If this points to a non-NULL on entry, this
 524                                   points to the image, which is Width pixels   wide
 525                                   and Height pixels high. The string will be drawn
 526                                   onto this image and
 527                                   EFI_HII_OUT_FLAG_CLIP is implied. If this points
 528                                   to a NULL on entry, then a              buffer
 529                                   will be allocated to hold the generated image and
 530                                   the pointer updated on exit. It is the caller's
 531                                   responsibility to free this buffer.
 532   @param  BltX                    Together with BltX, Specifies the offset from the left and top edge
 533                                   of the image of the first character cell in the
 534                                   image.
 535   @param  BltY                    Together with BltY, Specifies the offset from the left and top edge
 536                                   of the image of the first character cell in the
 537                                   image.
 538   @param  RowInfoArray            If this is non-NULL on entry, then on exit, this
 539                                   will point to an allocated buffer    containing
 540                                   row information and RowInfoArraySize will be
 541                                   updated to contain the        number of elements.
 542                                   This array describes the characters which were at
 543                                   least partially drawn and the heights of the
 544                                   rows. It is the caller's responsibility to free
 545                                   this buffer.
 546   @param  RowInfoArraySize        If this is non-NULL on entry, then on exit it
 547                                   contains the number of elements in RowInfoArray.
 548   @param  ColumnInfoArray         If this is non-NULL, then on return it will be
 549                                   filled with the horizontal offset for each
 550                                   character in the string on the row where it is
 551                                   displayed. Non-printing characters will     have
 552                                   the offset ~0. The caller is responsible to
 553                                   allocate a buffer large enough so that    there
 554                                   is one entry for each character in the string,
 555                                   not including the null-terminator. It is possible
 556                                   when character display is normalized that some
 557                                   character cells overlap.
 558
 559   @retval EFI_SUCCESS             The string was successfully rendered.
 560   @retval EFI_OUT_OF_RESOURCES    Unable to allocate an output buffer for
 561                                   RowInfoArray or Blt.
 562   @retval EFI_INVALID_PARAMETER The Blt or PackageList was NULL.
 563   @retval EFI_INVALID_PARAMETER Flags were invalid combination.
 564   @retval EFI_NOT_FOUND         The specified PackageList is not in the Database or the stringid is not
 565                           in the specified PackageList.
 566
 567 **/
 568 EFI_STATUS
 569 EFIAPI
 570 HiiStringIdToImage (
 571   IN  CONST EFI_HII_FONT_PROTOCOL    *This,
 572   IN  EFI_HII_OUT_FLAGS              Flags,
 573   IN  EFI_HII_HANDLE                 PackageList,
 574   IN  EFI_STRING_ID                  StringId,
 575   IN  CONST CHAR8*                   Language,
 576   IN  CONST EFI_FONT_DISPLAY_INFO    *StringInfo       OPTIONAL,
 577   IN  OUT EFI_IMAGE_OUTPUT           **Blt,
 578   IN  UINTN                          BltX,
 579   IN  UINTN                          BltY,
 580   OUT EFI_HII_ROW_INFO               **RowInfoArray    OPTIONAL,
 581   OUT UINTN                          *RowInfoArraySize OPTIONAL,
 582   OUT UINTN                          *ColumnInfoArray  OPTIONAL
 583   );
 584
 585
 586 /**
 587   Convert the glyph for a single character into a bitmap.
 588
 589   @param  This                    A pointer to the EFI_HII_FONT_PROTOCOL instance.
 590   @param  Char                    Character to retrieve.
 591   @param  StringInfo              Points to the string font and color information
 592                                   or NULL if the string should use the default
 593                                   system font and color.
 594   @param  Blt                     Thus must point to a NULL on entry. A buffer will
 595                                   be allocated to hold the output and the pointer
 596                                   updated on exit. It is the caller's
 597                                   responsibility to free this buffer.
 598   @param  Baseline                Number of pixels from the bottom of the bitmap to
 599                                   the baseline.
 600
 601   @retval EFI_SUCCESS             Glyph bitmap created.
 602   @retval EFI_OUT_OF_RESOURCES    Unable to allocate the output buffer Blt.
 603   @retval EFI_WARN_UNKNOWN_GLYPH  The glyph was unknown and was replaced with the
 604                                   glyph for Unicode character 0xFFFD.
 605   @retval EFI_INVALID_PARAMETER   Blt is NULL or *Blt is not NULL.
 606
 607 **/
 608 EFI_STATUS
 609 EFIAPI
 610 HiiGetGlyph (
 611   IN  CONST EFI_HII_FONT_PROTOCOL    *This,
 612   IN  CHAR16                         Char,
 613   IN  CONST EFI_FONT_DISPLAY_INFO    *StringInfo,
 614   OUT EFI_IMAGE_OUTPUT               **Blt,
 615   OUT UINTN                          *Baseline OPTIONAL
 616   );
 617
 618
 619 /**
 620   This function iterates through fonts which match the specified font, using
 621   the specified criteria. If String is non-NULL, then all of the characters in
 622   the string must exist in order for a candidate font to be returned.
 623
 624   @param  This                    A pointer to the EFI_HII_FONT_PROTOCOL instance.
 625   @param  FontHandle              On entry, points to the font handle returned by a
 626                                    previous call to GetFontInfo() or NULL to start
 627                                   with the  first font. On return, points to the
 628                                   returned font handle or points to NULL if there
 629                                   are no more matching fonts.
 630   @param  StringInfoIn            Upon entry, points to the font to return
 631                                   information about. If NULL, then the information about the system default
 632                                   font will be returned.
 633   @param  StringInfoOut           Upon return, contains the matching font's
 634                                   information.  If NULL, then no information is
 635                                   returned. It's caller's responsibility to free
 636                                   this buffer.
 637   @param  String                  Points to the string which will be tested to
 638                                   determine  if all characters are available. If
 639                                   NULL, then any font  is acceptable.
 640
 641   @retval EFI_SUCCESS             Matching font returned successfully.
 642   @retval EFI_NOT_FOUND           No matching font was found.
 643   @retval EFI_INVALID_PARAMETER   StringInfoIn is NULL.
 644   @retval EFI_INVALID_PARAMETER  StringInfoIn->FontInfoMask is an invalid combination.
 645   @retval EFI_OUT_OF_RESOURCES    There were insufficient resources to complete the
 646                                   request.
 647 **/
 648 EFI_STATUS
 649 EFIAPI
 650 HiiGetFontInfo (
 651   IN  CONST EFI_HII_FONT_PROTOCOL    *This,
 652   IN  OUT   EFI_FONT_HANDLE          *FontHandle,
 653   IN  CONST EFI_FONT_DISPLAY_INFO    *StringInfoIn, OPTIONAL
 654   OUT       EFI_FONT_DISPLAY_INFO    **StringInfoOut,
 655   IN  CONST EFI_STRING               String OPTIONAL
 656   );
 657
 658 //
 659 // EFI_HII_IMAGE_PROTOCOL interfaces
 660 //
 661
 662
 663 /**
 664   This function adds the image Image to the group of images owned by PackageList, and returns
 665   a new image identifier (ImageId).
 666
 667   @param  This                    A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 668   @param  PackageList             Handle of the package list where this image will
 669                                   be added.
 670   @param  ImageId                 On return, contains the new image id, which is
 671                                   unique within PackageList.
 672   @param  Image                   Points to the image.
 673
 674   @retval EFI_SUCCESS             The new image was added successfully.
 675   @retval EFI_NOT_FOUND           The specified PackageList could not be found in
 676                                   database.
 677   @retval EFI_OUT_OF_RESOURCES    Could not add the image due to lack of resources.
 678   @retval EFI_INVALID_PARAMETER   Image is NULL or ImageId is NULL.
 679
 680 **/
 681 EFI_STATUS
 682 EFIAPI
 683 HiiNewImage (
 684   IN  CONST EFI_HII_IMAGE_PROTOCOL   *This,
 685   IN  EFI_HII_HANDLE                 PackageList,
 686   OUT EFI_IMAGE_ID                   *ImageId,
 687   IN  CONST EFI_IMAGE_INPUT          *Image
 688   );
 689
 690
 691 /**
 692   This function retrieves the image specified by ImageId which is associated with
 693   the specified PackageList and copies it into the buffer specified by Image.
 694
 695   @param  This                    A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 696   @param  PackageList             Handle of the package list where this image will
 697                                   be searched.
 698   @param  ImageId                 The image's id,, which is unique within
 699                                   PackageList.
 700   @param  Image                   Points to the image.
 701
 702   @retval EFI_SUCCESS             The new image was returned successfully.
 703   @retval EFI_NOT_FOUND           The image specified by ImageId is not available.
 704                                                  The specified PackageList is not in the database.
 705   @retval EFI_BUFFER_TOO_SMALL    The buffer specified by ImageSize is too small to
 706                                   hold the image.
 707   @retval EFI_INVALID_PARAMETER   The Image or ImageSize was NULL.
 708   @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there was not
 709                                                        enough memory.
 710
 711 **/
 712 EFI_STATUS
 713 EFIAPI
 714 HiiGetImage (
 715   IN  CONST EFI_HII_IMAGE_PROTOCOL   *This,
 716   IN  EFI_HII_HANDLE                 PackageList,
 717   IN  EFI_IMAGE_ID                   ImageId,
 718   OUT EFI_IMAGE_INPUT                *Image
 719   );
 720
 721
 722 /**
 723   This function updates the image specified by ImageId in the specified PackageListHandle to
 724   the image specified by Image.
 725
 726   @param  This                    A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 727   @param  PackageList             The package list containing the images.
 728   @param  ImageId                 The image's id,, which is unique within
 729                                   PackageList.
 730   @param  Image                   Points to the image.
 731
 732   @retval EFI_SUCCESS             The new image was updated successfully.
 733   @retval EFI_NOT_FOUND           The image specified by ImageId is not in the
 734                                                 database. The specified PackageList is not in the database.
 735   @retval EFI_INVALID_PARAMETER   The Image was NULL.
 736
 737 **/
 738 EFI_STATUS
 739 EFIAPI
 740 HiiSetImage (
 741   IN CONST EFI_HII_IMAGE_PROTOCOL    *This,
 742   IN EFI_HII_HANDLE                  PackageList,
 743   IN EFI_IMAGE_ID                    ImageId,
 744   IN CONST EFI_IMAGE_INPUT           *Image
 745   );
 746
 747
 748 /**
 749   This function renders an image to a bitmap or the screen using the specified
 750   color and options. It draws the image on an existing bitmap, allocates a new
 751   bitmap or uses the screen. The images can be clipped.
 752
 753   @param  This                    A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 754   @param  Flags                   Describes how the image is to be drawn.
 755   @param  Image                   Points to the image to be displayed.
 756   @param  Blt                     If this points to a non-NULL on entry, this
 757                                   points to the image, which is Width pixels wide
 758                                   and Height pixels high.  The image will be drawn
 759                                   onto this image and  EFI_HII_DRAW_FLAG_CLIP is
 760                                   implied. If this points to a  NULL on entry, then
 761                                   a buffer will be allocated to hold  the generated
 762                                   image and the pointer updated on exit. It is the
 763                                   caller's responsibility to free this buffer.
 764   @param  BltX                    Specifies the offset from the left and top edge
 765                                   of the  output image of the first pixel in the
 766                                   image.
 767   @param  BltY                    Specifies the offset from the left and top edge
 768                                   of the  output image of the first pixel in the
 769                                   image.
 770
 771   @retval EFI_SUCCESS             The image was successfully drawn.
 772   @retval EFI_OUT_OF_RESOURCES    Unable to allocate an output buffer for Blt.
 773   @retval EFI_INVALID_PARAMETER   The Image or Blt was NULL.
 774   @retval EFI_INVALID_PARAMETER   Any combination of Flags is invalid.
 775
 776 **/
 777 EFI_STATUS
 778 EFIAPI
 779 HiiDrawImage (
 780   IN CONST EFI_HII_IMAGE_PROTOCOL    *This,
 781   IN EFI_HII_DRAW_FLAGS              Flags,
 782   IN CONST EFI_IMAGE_INPUT           *Image,
 783   IN OUT EFI_IMAGE_OUTPUT            **Blt,
 784   IN UINTN                           BltX,
 785   IN UINTN                           BltY
 786   );
 787
 788
 789 /**
 790   This function renders an image to a bitmap or the screen using the specified
 791   color and options. It draws the image on an existing bitmap, allocates a new
 792   bitmap or uses the screen. The images can be clipped.
 793
 794   @param  This                    A pointer to the EFI_HII_IMAGE_PROTOCOL instance.
 795   @param  Flags                   Describes how the image is to be drawn.
 796   @param  PackageList             The package list in the HII database to search
 797                                   for the  specified image.
 798   @param  ImageId                 The image's id, which is unique within
 799                                   PackageList.
 800   @param  Blt                     If this points to a non-NULL on entry, this
 801                                   points to the image, which is Width pixels wide
 802                                   and Height pixels high. The image will be drawn
 803                                   onto this image and
 804                                   EFI_HII_DRAW_FLAG_CLIP is implied. If this points
 805                                   to a  NULL on entry, then a buffer will be
 806                                   allocated to hold  the generated image and the
 807                                   pointer updated on exit. It is the caller's
 808                                   responsibility to free this buffer.
 809   @param  BltX                    Specifies the offset from the left and top edge
 810                                   of the  output image of the first pixel in the
 811                                   image.
 812   @param  BltY                    Specifies the offset from the left and top edge
 813                                   of the  output image of the first pixel in the
 814                                   image.
 815
 816   @retval EFI_SUCCESS             The image was successfully drawn.
 817   @retval EFI_OUT_OF_RESOURCES    Unable to allocate an output buffer for Blt.
 818   @retval EFI_INVALID_PARAMETER  The Blt was NULL.
 819   @retval EFI_NOT_FOUND          The image specified by ImageId is not in the database.
 820                            The specified PackageList is not in the database.
 821
 822 **/
 823 EFI_STATUS
 824 EFIAPI
 825 HiiDrawImageId (
 826   IN CONST EFI_HII_IMAGE_PROTOCOL    *This,
 827   IN EFI_HII_DRAW_FLAGS              Flags,
 828   IN EFI_HII_HANDLE                  PackageList,
 829   IN EFI_IMAGE_ID                    ImageId,
 830   IN OUT EFI_IMAGE_OUTPUT            **Blt,
 831   IN UINTN                           BltX,
 832   IN UINTN                           BltY
 833   )
 834
 835 ;
 836
 837 //
 838 // EFI_HII_STRING_PROTOCOL
 839 //
 840
 841
 842 /**
 843   This function adds the string String to the group of strings owned by PackageList, with the
 844   specified font information StringFontInfo and returns a new string id.
 845
 846   @param  This                    A pointer to the EFI_HII_STRING_PROTOCOL
 847                                   instance.
 848   @param  PackageList             Handle of the package list where this string will
 849                                   be added.
 850   @param  StringId                On return, contains the new strings id, which is
 851                                   unique within PackageList.
 852   @param  Language                Points to the language for the new string.
 853   @param  LanguageName            Points to the printable language name to
 854                                   associate with the passed in  Language field.If
 855                                   LanguageName is not NULL and the string package
 856                                   header's LanguageName  associated with a given
 857                                   Language is not zero, the LanguageName being
 858                                   passed  in will be ignored.
 859   @param  String                  Points to the new null-terminated string.
 860   @param  StringFontInfo          Points to the new string's font information or
 861                                   NULL if the string should have the default system
 862                                   font, size and style.
 863
 864   @retval EFI_SUCCESS             The new string was added successfully.
 865   @retval EFI_NOT_FOUND           The specified PackageList could not be found in
 866                                   database.
 867   @retval EFI_OUT_OF_RESOURCES    Could not add the string due to lack of
 868                                   resources.
 869   @retval EFI_INVALID_PARAMETER   String is NULL or StringId is NULL or Language is
 870                                   NULL.
 871
 872 **/
 873 EFI_STATUS
 874 EFIAPI
 875 HiiNewString (
 876   IN  CONST EFI_HII_STRING_PROTOCOL   *This,
 877   IN  EFI_HII_HANDLE                  PackageList,
 878   OUT EFI_STRING_ID                   *StringId,
 879   IN  CONST CHAR8                     *Language,
 880   IN  CONST CHAR16                    *LanguageName, OPTIONAL
 881   IN  CONST EFI_STRING                String,
 882   IN  CONST EFI_FONT_INFO             *StringFontInfo OPTIONAL
 883   );
 884
 885
 886 /**
 887   This function retrieves the string specified by StringId which is associated
 888   with the specified PackageList in the language Language and copies it into
 889   the buffer specified by String.
 890
 891   @param  This                    A pointer to the EFI_HII_STRING_PROTOCOL
 892                                   instance.
 893   @param  Language                Points to the language for the retrieved string.
 894   @param  PackageList             The package list in the HII database to search
 895                                   for the  specified string.
 896   @param  StringId                The string's id, which is unique within
 897                                   PackageList.
 898   @param  String                  Points to the new null-terminated string.
 899   @param  StringSize              On entry, points to the size of the buffer
 900                                   pointed to by  String, in bytes. On return,
 901                                   points to the length of the string, in bytes.
 902   @param  StringFontInfo          If not NULL, points to the string's font
 903                                   information.  It's caller's responsibility to
 904                                   free this buffer.
 905
 906   @retval EFI_SUCCESS             The string was returned successfully.
 907   @retval EFI_NOT_FOUND           The string specified by StringId is not
 908                                   available.
 909   @retval EFI_NOT_FOUND           The string specified by StringId is available but
 910                                                 not in the specified language.
 911                                                 The specified PackageList is not in the database.
 912   @retval EFI_INVALID_LANGUAGE   - The string specified by StringId is available but
 913   @retval EFI_BUFFER_TOO_SMALL    The buffer specified by StringSize is too small
 914                                   to  hold the string.
 915   @retval EFI_INVALID_PARAMETER   The String or Language or StringSize was NULL.
 916   @retval EFI_OUT_OF_RESOURCES    There were insufficient resources to complete the
 917                                    request.
 918
 919 **/
 920 EFI_STATUS
 921 EFIAPI
 922 HiiGetString (
 923   IN  CONST EFI_HII_STRING_PROTOCOL   *This,
 924   IN  CONST CHAR8                     *Language,
 925   IN  EFI_HII_HANDLE                  PackageList,
 926   IN  EFI_STRING_ID                   StringId,
 927   OUT EFI_STRING                      String,
 928   IN  OUT UINTN                       *StringSize,
 929   OUT EFI_FONT_INFO                   **StringFontInfo OPTIONAL
 930   );
 931
 932
 933 /**
 934   This function updates the string specified by StringId in the specified PackageList to the text
 935   specified by String and, optionally, the font information specified by StringFontInfo.
 936
 937   @param  This                    A pointer to the EFI_HII_STRING_PROTOCOL
 938                                   instance.
 939   @param  PackageList             The package list containing the strings.
 940   @param  StringId                The string's id, which is unique within
 941                                   PackageList.
 942   @param  Language                Points to the language for the updated string.
 943   @param  String                  Points to the new null-terminated string.
 944   @param  StringFontInfo          Points to the string's font information or NULL
 945                                   if the string font information is not changed.
 946
 947   @retval EFI_SUCCESS             The string was updated successfully.
 948   @retval EFI_NOT_FOUND           The string specified by StringId is not in the
 949                                   database.
 950   @retval EFI_INVALID_PARAMETER   The String or Language was NULL.
 951   @retval EFI_OUT_OF_RESOURCES    The system is out of resources to accomplish the
 952                                   task.
 953
 954 **/
 955 EFI_STATUS
 956 EFIAPI
 957 HiiSetString (
 958   IN CONST EFI_HII_STRING_PROTOCOL    *This,
 959   IN EFI_HII_HANDLE                   PackageList,
 960   IN EFI_STRING_ID                    StringId,
 961   IN CONST CHAR8                      *Language,
 962   IN CONST EFI_STRING                 String,
 963   IN CONST EFI_FONT_INFO              *StringFontInfo OPTIONAL
 964   );
 965
 966
 967 /**
 968   This function returns the list of supported languages, in the format specified
 969   in Appendix M of UEFI 2.1 spec.
 970
 971   @param  This                    A pointer to the EFI_HII_STRING_PROTOCOL
 972                                   instance.
 973   @param  PackageList             The package list to examine.
 974   @param  Languages               Points to the buffer to hold the returned string.
 975   @param  LanguagesSize           On entry, points to the size of the buffer
 976                                   pointed to by  Languages, in bytes. On  return,
 977                                   points to the length of Languages, in bytes.
 978
 979   @retval EFI_SUCCESS             The languages were returned successfully.
 980   @retval EFI_INVALID_PARAMETER   The Languages or LanguagesSize was NULL.
 981   @retval EFI_BUFFER_TOO_SMALL    The LanguagesSize is too small to hold the list
 982                                   of  supported languages. LanguageSize is updated
 983                                   to contain the required size.
 984   @retval EFI_NOT_FOUND           Could not find string package in specified
 985                                   packagelist.
 986
 987 **/
 988 EFI_STATUS
 989 EFIAPI
 990 HiiGetLanguages (
 991   IN CONST EFI_HII_STRING_PROTOCOL    *This,
 992   IN EFI_HII_HANDLE                   PackageList,
 993   IN OUT CHAR8                        *Languages,
 994   IN OUT UINTN                        *LanguagesSize
 995   );
 996
 997
 998 /**
 999   Each string package has associated with it a single primary language and zero
1000   or more secondary languages. This routine returns the secondary languages
1001   associated with a package list.
1002
1003   @param  This                    A pointer to the EFI_HII_STRING_PROTOCOL
1004                                   instance.
1005   @param  PackageList             The package list to examine.
1006   @param  FirstLanguage           Points to the primary language.
1007   @param  SecondaryLanguages      Points to the buffer to hold the returned list of
1008                                    secondary languages for the specified
1009                                   FirstLanguage. If there are no secondary
1010                                   languages, the function  returns successfully,
1011                                   but this is set to NULL.
1012   @param  SecondaryLanguagesSize  On entry, points to the size of the buffer
1013                                   pointed to  by SecondLanguages, in bytes. On
1014                                   return, points to the length of SecondLanguages
1015                                   in bytes.
1016
1017   @retval EFI_SUCCESS             Secondary languages were correctly returned.
1018   @retval EFI_INVALID_PARAMETER   FirstLanguage or SecondLanguages or
1019                                   SecondLanguagesSize was NULL.
1020   @retval EFI_BUFFER_TOO_SMALL    The buffer specified by SecondLanguagesSize is
1021                                   too small to hold the returned information.
1022                                   SecondLanguageSize is updated to hold the size of
1023                                   the buffer required.
1024   @retval EFI_INVALID_LANGUAGE           The language specified by FirstLanguage is not
1025                                   present in the specified package list.
1026   @retval EFI_NOT_FOUND          The specified PackageList is not in the Database.
1027
1028 **/
1029 EFI_STATUS
1030 EFIAPI
1031 HiiGetSecondaryLanguages (
1032   IN CONST EFI_HII_STRING_PROTOCOL   *This,
1033   IN EFI_HII_HANDLE                  PackageList,
1034   IN CONST CHAR8                     *FirstLanguage,
1035   IN OUT CHAR8                       *SecondaryLanguages,
1036   IN OUT UINTN                       *SecondaryLanguagesSize
1037   );
1038
1039 //
1040 // EFI_HII_DATABASE_PROTOCOL protocol interfaces
1041 //
1042
1043
1044 /**
1045   This function adds the packages in the package list to the database and returns a handle. If there is a
1046   EFI_DEVICE_PATH_PROTOCOL associated with the DriverHandle, then this function will
1047   create a package of type EFI_PACKAGE_TYPE_DEVICE_PATH and add it to the package list.
1048
1049   @param  This                    A pointer to the EFI_HII_DATABASE_PROTOCOL
1050                                   instance.
1051   @param  PackageList             A pointer to an EFI_HII_PACKAGE_LIST_HEADER
1052                                   structure.
1053   @param  DriverHandle            Associate the package list with this EFI handle.
1054   @param  Handle                  A pointer to the EFI_HII_HANDLE instance.
1055
1056   @retval EFI_SUCCESS             The package list associated with the Handle was
1057                                   added to the HII database.
1058   @retval EFI_OUT_OF_RESOURCES    Unable to allocate necessary resources for the
1059                                   new database contents.
1060   @retval EFI_INVALID_PARAMETER   PackageList is NULL or Handle is NULL.
1061
1062 **/
1063 EFI_STATUS
1064 EFIAPI
1065 HiiNewPackageList (
1066   IN CONST EFI_HII_DATABASE_PROTOCOL    *This,
1067   IN CONST EFI_HII_PACKAGE_LIST_HEADER  *PackageList,
1068   IN CONST EFI_HANDLE                   DriverHandle,
1069   OUT EFI_HII_HANDLE                    *Handle
1070   );
1071
1072
1073 /**
1074   This function removes the package list that is associated with a handle Handle
1075   from the HII database. Before removing the package, any registered functions
1076   with the notification type REMOVE_PACK and the same package type will be called.
1077
1078   @param  This                    A pointer to the EFI_HII_DATABASE_PROTOCOL
1079                                   instance.
1080   @param  Handle                  The handle that was registered to the data that
1081                                   is requested  for removal.
1082
1083   @retval EFI_SUCCESS             The data associated with the Handle was removed
1084                                   from  the HII database.
1085   @retval EFI_NOT_FOUND           The specified Handle is not in database.
1086
1087 **/
1088 EFI_STATUS
1089 EFIAPI
1090 HiiRemovePackageList (
1091   IN CONST EFI_HII_DATABASE_PROTOCOL    *This,
1092   IN EFI_HII_HANDLE                     Handle
1093   );
1094
1095
1096 /**
1097   This function updates the existing package list (which has the specified Handle)
1098   in the HII databases, using the new package list specified by PackageList.
1099
1100   @param  This                    A pointer to the EFI_HII_DATABASE_PROTOCOL
1101                                   instance.
1102   @param  Handle                  The handle that was registered to the data that
1103                                   is  requested to be updated.
1104   @param  PackageList             A pointer to an EFI_HII_PACKAGE_LIST_HEADER
1105                                   package.
1106
1107   @retval EFI_SUCCESS             The HII database was successfully updated.
1108   @retval EFI_OUT_OF_RESOURCES    Unable to allocate enough memory for the updated
1109                                   database.
1110   @retval EFI_INVALID_PARAMETER  PackageList was NULL.
1111   @retval EFI_NOT_FOUND          The specified Handle is not in database.
1112
1113 **/
1114 EFI_STATUS
1115 EFIAPI
1116 HiiUpdatePackageList (
1117   IN CONST EFI_HII_DATABASE_PROTOCOL    *This,
1118   IN EFI_HII_HANDLE                     Handle,
1119   IN CONST EFI_HII_PACKAGE_LIST_HEADER  *PackageList
1120   );
1121
1122
1123 /**
1124   This function returns a list of the package handles of the specified type
1125   that are currently active in the database. The pseudo-type
1126   EFI_HII_PACKAGE_TYPE_ALL will cause all package handles to be listed.
1127
1128   @param  This                    A pointer to the EFI_HII_DATABASE_PROTOCOL
1129                                   instance.
1130   @param  PackageType             Specifies the package type of the packages to
1131                                   list or EFI_HII_PACKAGE_TYPE_ALL for all packages
1132                                   to be listed.
1133   @param  PackageGuid             If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then
1134                                   this  is the pointer to the GUID which must match
1135                                   the Guid field of EFI_HII_GUID_PACKAGE_GUID_HDR.
1136                                   Otherwise,  it must be NULL.
1137   @param  HandleBufferLength      On input, a pointer to the length of the handle
1138                                   buffer.  On output, the length of the handle
1139                                   buffer that is required for the handles found.
1140   @param  Handle                  An array of EFI_HII_HANDLE instances returned.
1141
1142   @retval EFI_SUCCESS             The matching handles are outputed successfully.
1143                                                 HandleBufferLength is updated with the actual length.
1144   @retval EFI_BUFFER_TO_SMALL     The HandleBufferLength parameter indicates that
1145                                   Handle is too small to support the number of
1146                                   handles. HandleBufferLength is updated with a
1147                                   value that will  enable the data to fit.
1148   @retval EFI_NOT_FOUND           No matching handle could not be found in
1149                                   database.
1150   @retval EFI_INVALID_PARAMETER   Handle or HandleBufferLength was NULL.
1151   @retval EFI_INVALID_PARAMETER  PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but
1152                          PackageGuid is not NULL, PackageType is a EFI_HII_
1153                          PACKAGE_TYPE_GUID but PackageGuid is NULL.
1154
1155
1156 **/
1157 EFI_STATUS
1158 EFIAPI
1159 HiiListPackageLists (
1160   IN  CONST EFI_HII_DATABASE_PROTOCOL   *This,
1161   IN  UINT8                             PackageType,
1162   IN  CONST EFI_GUID                    *PackageGuid,
1163   IN  OUT UINTN                         *HandleBufferLength,
1164   OUT EFI_HII_HANDLE                    *Handle
1165   );
1166
1167
1168 /**
1169   This function will export one or all package lists in the database to a buffer.
1170   For each package list exported, this function will call functions registered
1171   with EXPORT_PACK and then copy the package list to the buffer.
1172
1173   @param  This                    A pointer to the EFI_HII_DATABASE_PROTOCOL
1174                                   instance.
1175   @param  Handle                  An EFI_HII_HANDLE that corresponds to the desired
1176                                   package list in the HII database to export or
1177                                   NULL to indicate  all package lists should be
1178                                   exported.
1179   @param  BufferSize              On input, a pointer to the length of the buffer.
1180                                   On output, the length of the buffer that is
1181                                   required for the exported data.
1182   @param  Buffer                  A pointer to a buffer that will contain the
1183                                   results of  the export function.
1184
1185   @retval EFI_SUCCESS             Package exported.
1186   @retval EFI_BUFFER_TO_SMALL     The HandleBufferLength parameter indicates that
1187                                   Handle is too small to support the number of
1188                                   handles.      HandleBufferLength is updated with
1189                                   a value that will enable the data to fit.
1190   @retval EFI_NOT_FOUND           The specifiecd Handle could not be found in the
1191                                   current database.
1192   @retval EFI_INVALID_PARAMETER   Handle or Buffer or BufferSize was NULL.
1193
1194 **/
1195 EFI_STATUS
1196 EFIAPI
1197 HiiExportPackageLists (
1198   IN  CONST EFI_HII_DATABASE_PROTOCOL   *This,
1199   IN  EFI_HII_HANDLE                    Handle,
1200   IN  OUT UINTN                         *BufferSize,
1201   OUT EFI_HII_PACKAGE_LIST_HEADER       *Buffer
1202   );
1203
1204
1205 /**
1206   This function registers a function which will be called when specified actions related to packages of
1207   the specified type occur in the HII database. By registering a function, other HII-related drivers are
1208   notified when specific package types are added, removed or updated in the HII database.
1209   Each driver or application which registers a notification should use
1210   EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before exiting.
1211
1212   @param  This                    A pointer to the EFI_HII_DATABASE_PROTOCOL
1213                                   instance.
1214   @param  PackageType             Specifies the package type of the packages to
1215                                   list or EFI_HII_PACKAGE_TYPE_ALL for all packages
1216                                   to be listed.
1217   @param  PackageGuid             If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then
1218                                   this is the pointer to the GUID which must match
1219                                   the Guid field of
1220                                   EFI_HII_GUID_PACKAGE_GUID_HDR. Otherwise, it must
1221                                   be NULL.
1222   @param  PackageNotifyFn         Points to the function to be called when the
1223                                   event specified by
1224                                   NotificationType occurs.
1225   @param  NotifyType              Describes the types of notification which this
1226                                   function will be receiving.
1227   @param  NotifyHandle            Points to the unique handle assigned to the
1228                                   registered notification. Can be used in
1229                                   EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify()
1230                                   to stop notifications.
1231
1232   @retval EFI_SUCCESS             Notification registered successfully.
1233   @retval EFI_OUT_OF_RESOURCES    Unable to allocate necessary data structures
1234   @retval EFI_INVALID_PARAMETER   NotifyHandle is NULL.
1235   @retval EFI_INVALID_PARAMETER   PackageGuid is not NULL when PackageType is not
1236                                   EFI_HII_PACKAGE_TYPE_GUID.
1237   @retval EFI_INVALID_PARAMETER   PackageGuid is NULL when PackageType is
1238                                   EFI_HII_PACKAGE_TYPE_GUID.
1239
1240 **/
1241 EFI_STATUS
1242 EFIAPI
1243 HiiRegisterPackageNotify (
1244   IN  CONST EFI_HII_DATABASE_PROTOCOL   *This,
1245   IN  UINT8                             PackageType,
1246   IN  CONST EFI_GUID                    *PackageGuid,
1247   IN  CONST EFI_HII_DATABASE_NOTIFY     PackageNotifyFn,
1248   IN  EFI_HII_DATABASE_NOTIFY_TYPE      NotifyType,
1249   OUT EFI_HANDLE                        *NotifyHandle
1250   );
1251
1252
1253 /**
1254   Removes the specified HII database package-related notification.
1255
1256   @param  This                    A pointer to the EFI_HII_DATABASE_PROTOCOL
1257                                   instance.
1258   @param  NotificationHandle      The handle of the notification function being
1259                                   unregistered.
1260
1261   @retval EFI_SUCCESS             Notification is unregistered successfully.
1262   @retval EFI_NOT_FOUND          The incoming notification handle does not exist
1263                            in current hii database.
1264
1265 **/
1266 EFI_STATUS
1267 EFIAPI
1268 HiiUnregisterPackageNotify (
1269   IN CONST EFI_HII_DATABASE_PROTOCOL    *This,
1270   IN EFI_HANDLE                         NotificationHandle
1271   );
1272
1273
1274 /**
1275   This routine retrieves an array of GUID values for each keyboard layout that
1276   was previously registered in the system.
1277
1278   @param  This                    A pointer to the EFI_HII_DATABASE_PROTOCOL
1279                                   instance.
1280   @param  KeyGuidBufferLength     On input, a pointer to the length of the keyboard
1281                                   GUID  buffer. On output, the length of the handle
1282                                   buffer  that is required for the handles found.
1283   @param  KeyGuidBuffer           An array of keyboard layout GUID instances
1284                                   returned.
1285
1286   @retval EFI_SUCCESS             KeyGuidBuffer was updated successfully.
1287   @retval EFI_BUFFER_TOO_SMALL    The KeyGuidBufferLength parameter indicates
1288                                   that KeyGuidBuffer is too small to support the
1289                                   number of GUIDs. KeyGuidBufferLength is
1290                                   updated with a value that will enable the data to
1291                                   fit.
1292   @retval EFI_INVALID_PARAMETER   The KeyGuidBuffer or KeyGuidBufferLength was
1293                                   NULL.
1294   @retval EFI_NOT_FOUND           There was no keyboard layout.
1295
1296 **/
1297 EFI_STATUS
1298 EFIAPI
1299 HiiFindKeyboardLayouts (
1300   IN  CONST EFI_HII_DATABASE_PROTOCOL   *This,
1301   IN  OUT UINT16                        *KeyGuidBufferLength,
1302   OUT EFI_GUID                          *KeyGuidBuffer
1303   );
1304
1305
1306 /**
1307   This routine retrieves the requested keyboard layout. The layout is a physical description of the keys
1308   on a keyboard and the character(s) that are associated with a particular set of key strokes.
1309
1310   @param  This                    A pointer to the EFI_HII_DATABASE_PROTOCOL
1311                                   instance.
1312   @param  KeyGuid                 A pointer to the unique ID associated with a
1313                                   given keyboard layout. If KeyGuid is NULL then
1314                                   the current layout will be retrieved.
1315   @param  KeyboardLayoutLength    On input, a pointer to the length of the
1316                                   KeyboardLayout buffer.  On output, the length of
1317                                   the data placed into KeyboardLayout.
1318   @param  KeyboardLayout          A pointer to a buffer containing the retrieved
1319                                   keyboard layout.
1320
1321   @retval EFI_SUCCESS             The keyboard layout was retrieved successfully.
1322   @retval EFI_NOT_FOUND           The requested keyboard layout was not found.
1323   @retval EFI_INVALID_PARAMETER   The KeyboardLayout or KeyboardLayoutLength was
1324                                   NULL.
1325
1326 **/
1327 EFI_STATUS
1328 EFIAPI
1329 HiiGetKeyboardLayout (
1330   IN  CONST EFI_HII_DATABASE_PROTOCOL   *This,
1331   IN  CONST EFI_GUID                          *KeyGuid,
1332   IN OUT UINT16                         *KeyboardLayoutLength,
1333   OUT EFI_HII_KEYBOARD_LAYOUT           *KeyboardLayout
1334   );
1335
1336
1337 /**
1338   This routine sets the default keyboard layout to the one referenced by KeyGuid. When this routine
1339   is called, an event will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID
1340   group type. This is so that agents which are sensitive to the current keyboard layout being changed
1341   can be notified of this change.
1342
1343   @param  This                    A pointer to the EFI_HII_DATABASE_PROTOCOL
1344                                   instance.
1345   @param  KeyGuid                 A pointer to the unique ID associated with a
1346                                   given keyboard layout.
1347
1348   @retval EFI_SUCCESS             The current keyboard layout was successfully set.
1349   @retval EFI_NOT_FOUND           The referenced keyboard layout was not found, so
1350                                   action was taken.
1351   @retval EFI_INVALID_PARAMETER   The KeyGuid was NULL.
1352
1353 **/
1354 EFI_STATUS
1355 EFIAPI
1356 HiiSetKeyboardLayout (
1357   IN CONST EFI_HII_DATABASE_PROTOCOL          *This,
1358   IN CONST EFI_GUID                           *KeyGuid
1359   );
1360
1361
1362 /**
1363   Return the EFI handle associated with a package list.
1364
1365   @param  This                    A pointer to the EFI_HII_DATABASE_PROTOCOL
1366                                   instance.
1367   @param  PackageListHandle       An EFI_HII_HANDLE that corresponds to the desired
1368                                   package list in the HIIdatabase.
1369   @param  DriverHandle            On return, contains the EFI_HANDLE which was
1370                                   registered with the package list in
1371                                   NewPackageList().
1372
1373   @retval EFI_SUCCESS             The DriverHandle was returned successfully.
1374   @retval EFI_INVALID_PARAMETER   The PackageListHandle was not valid or
1375                                   DriverHandle was NULL.
1376
1377 **/
1378 EFI_STATUS
1379 EFIAPI
1380 HiiGetPackageListHandle (
1381   IN  CONST EFI_HII_DATABASE_PROTOCOL         *This,
1382   IN  EFI_HII_HANDLE                    PackageListHandle,
1383   OUT EFI_HANDLE                        *DriverHandle
1384   );
1385
1386 //
1387 // EFI_HII_CONFIG_ROUTING_PROTOCOL interfaces
1388 //
1389
1390
1391 /**
1392   This function allows a caller to extract the current configuration
1393   for one or more named elements from one or more drivers.
1394
1395   @param  This                    A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL
1396                                   instance.
1397   @param  Request                 A null-terminated Unicode string in
1398                                   <MultiConfigRequest> format.
1399   @param  Progress                On return, points to a character in the Request
1400                                   string. Points to the string's null terminator if
1401                                   request was successful. Points to the most recent
1402                                   & before the first failing name / value pair (or
1403                                   the beginning of the string if the failure is in
1404                                   the first name / value pair) if the request was
1405                                   not successful.
1406   @param  Results                 Null-terminated Unicode string in
1407                                   <MultiConfigAltResp> format which has all values
1408                                   filled in for the names in the Request string.
1409                                   String to be allocated by the called function.
1410
1411   @retval EFI_SUCCESS             The Results string is filled with the values
1412                                   corresponding to all requested names.
1413   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the parts of the
1414                                   results that must be stored awaiting possible
1415                                   future        protocols.
1416   @retval EFI_NOT_FOUND           Routing data doesn't match any known driver.
1417                                      Progress set to the "G" in "GUID" of the
1418                                   routing  header that doesn't match. Note: There
1419                                   is no         requirement that all routing data
1420                                   be validated before any configuration extraction.
1421   @retval EFI_INVALID_PARAMETER   For example, passing in a NULL for the Request
1422                                   parameter would result in this type of error. The
1423                                   Progress parameter is set to NULL.
1424   @retval EFI_INVALID_PARAMETER   Illegal syntax. Progress set to most recent &
1425                                   before the error or the beginning of the string.
1426   @retval EFI_INVALID_PARAMETER   Unknown name. Progress points to the & before the
1427                                   name in question.
1428
1429 **/
1430 EFI_STATUS
1431 EFIAPI
1432 HiiConfigRoutingExtractConfig (
1433   IN  CONST EFI_HII_CONFIG_ROUTING_PROTOCOL  *This,
1434   IN  CONST EFI_STRING                       Request,
1435   OUT EFI_STRING                             *Progress,
1436   OUT EFI_STRING                             *Results
1437   );
1438
1439
1440 /**
1441   This function allows the caller to request the current configuration for the
1442   entirety of the current HII database and returns the data in a null-terminated Unicode string.
1443
1444   @param  This                    A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL
1445                                   instance.
1446   @param  Results                 Null-terminated Unicode string in
1447                                   <MultiConfigAltResp> format which has all values
1448                                   filled in for the names in the Request string.
1449                                   String to be allocated by the  called function.
1450                                   De-allocation is up to the caller.
1451
1452   @retval EFI_SUCCESS             The Results string is filled with the values
1453                                   corresponding to all requested names.
1454   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the parts of the
1455                                   results that must be stored awaiting possible
1456                                   future        protocols.
1457   @retval EFI_INVALID_PARAMETER   For example, passing in a NULL for the Results
1458                                   parameter would result in this type of error.
1459
1460 **/
1461 EFI_STATUS
1462 EFIAPI
1463 HiiConfigRoutingExportConfig (
1464   IN  CONST EFI_HII_CONFIG_ROUTING_PROTOCOL  *This,
1465   OUT EFI_STRING                             *Results
1466   );
1467
1468
1469 /**
1470   This function processes the results of processing forms and routes it to the
1471   appropriate handlers or storage.
1472
1473   @param  This                    A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL
1474                                   instance.
1475   @param  Configuration           A null-terminated Unicode string in
1476                                   <MulltiConfigResp> format.
1477   @param  Progress                A pointer to a string filled in with the offset
1478                                   of the most recent & before the first failing
1479                                   name / value pair (or the beginning of the string
1480                                   if the failure is in the first name / value pair)
1481                                   or the terminating NULL if all was successful.
1482
1483   @retval EFI_SUCCESS             The results have been distributed or are awaiting
1484                                   distribution.
1485   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the parts of the
1486                                   results that must be stored awaiting possible
1487                                   future        protocols.
1488   @retval EFI_INVALID_PARAMETER   Passing in a NULL for the Configuration parameter
1489                                   would result in this type of error.
1490   @retval EFI_NOT_FOUND           Target for the specified routing data was not
1491                                   found.
1492
1493 **/
1494 EFI_STATUS
1495 EFIAPI
1496 HiiConfigRoutingRouteConfig (
1497   IN  CONST EFI_HII_CONFIG_ROUTING_PROTOCOL  *This,
1498   IN  CONST EFI_STRING                       Configuration,
1499   OUT EFI_STRING                             *Progress
1500   );
1501
1502
1503
1504 /**
1505   This helper function is to be called by drivers to map configuration data stored
1506   in byte array ("block") formats such as UEFI Variables into current configuration strings.
1507
1508   @param  This                    A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL
1509                                   instance.
1510   @param  ConfigRequest           A null-terminated Unicode string in
1511                                   <ConfigRequest> format.
1512   @param  Block                   Array of bytes defining the block's
1513                                   configuration.
1514   @param  BlockSize               Length in bytes of Block.
1515   @param  Config                  Filled-in configuration string. String allocated
1516                                   by  the function. Returned only if call is
1517                                   successful.
1518   @param  Progress                A pointer to a string filled in with the offset
1519                                   of  the most recent & before the first failing
1520                                   name/value pair (or the beginning of the string
1521                                   if the failure is in the first name / value pair)
1522                                   or the terminating NULL if all was successful.
1523
1524   @retval EFI_SUCCESS             The request succeeded. Progress points to the
1525                                   null terminator at the end of the ConfigRequest
1526                                         string.
1527   @retval EFI_OUT_OF_RESOURCES    Not enough memory to allocate Config.
1528                                   Progress points to the first character of
1529                                   ConfigRequest.
1530   @retval EFI_INVALID_PARAMETER   Passing in a NULL for the ConfigRequest or
1531                                   Block parameter would result in this type of
1532                                   error. Progress points to the first character of
1533                                   ConfigRequest.
1534   @retval EFI_NOT_FOUND           Target for the specified routing data was not
1535                                   found. Progress points to the "G" in "GUID" of
1536                                   the      errant routing data.
1537   @retval EFI_DEVICE_ERROR        Block not large enough. Progress undefined.
1538   @retval EFI_INVALID_PARAMETER   Encountered non <BlockName> formatted string.
1539                                        Block is left updated and Progress points at
1540                                   the '&' preceding the first non-<BlockName>.
1541
1542 **/
1543 EFI_STATUS
1544 EFIAPI
1545 HiiBlockToConfig (
1546   IN  CONST EFI_HII_CONFIG_ROUTING_PROTOCOL  *This,
1547   IN  CONST EFI_STRING                       ConfigRequest,
1548   IN  CONST UINT8                            *Block,
1549   IN  CONST UINTN                            BlockSize,
1550   OUT EFI_STRING                             *Config,
1551   OUT EFI_STRING                             *Progress
1552   );
1553
1554
1555 /**
1556   This helper function is to be called by drivers to map configuration strings
1557   to configurations stored in byte array ("block") formats such as UEFI Variables.
1558
1559   @param  This                    A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL
1560                                   instance.
1561   @param  ConfigResp              A null-terminated Unicode string in <ConfigResp>
1562                                   format.
1563   @param  Block                   A possibly null array of bytes representing the
1564                                   current  block. Only bytes referenced in the
1565                                   ConfigResp string  in the block are modified. If
1566                                   this parameter is null or if the *BlockSize
1567                                   parameter is (on input) shorter than required by
1568                                   the Configuration string, only the BlockSize
1569                                   parameter is updated and an appropriate status
1570                                   (see below)  is returned.
1571   @param  BlockSize               The length of the Block in units of UINT8.  On
1572                                   input, this is the size of the Block. On output,
1573                                   if successful, contains the index of the  last
1574                                   modified byte in the Block.
1575   @param  Progress                On return, points to an element of the ConfigResp
1576                                    string filled in with the offset of the most
1577                                   recent '&' before the first failing name / value
1578                                   pair (or  the beginning of the string if the
1579                                   failure is in the  first name / value pair) or
1580                                   the terminating NULL if all was successful.
1581
1582   @retval EFI_SUCCESS             The request succeeded. Progress points to the
1583                                   null terminator at the end of the ConfigResp
1584                                   string.
1585   @retval EFI_OUT_OF_RESOURCES    Not enough memory to allocate Config.
1586                                   Progress points to the first character of
1587                                   ConfigResp.
1588   @retval EFI_INVALID_PARAMETER   Passing in a NULL for the ConfigResp or
1589                                   Block parameter would result in this type of
1590                                   error. Progress points to the first character of
1591                                            ConfigResp.
1592   @retval EFI_NOT_FOUND           Target for the specified routing data was not
1593                                   found. Progress points to the "G" in "GUID" of
1594                                   the      errant routing data.
1595   @retval EFI_INVALID_PARAMETER   Encountered non <BlockName> formatted name /
1596                                   value pair. Block is left updated and
1597                                   Progress points at the '&' preceding the first
1598                                   non-<BlockName>.
1599
1600 **/
1601 EFI_STATUS
1602 EFIAPI
1603 HiiConfigToBlock (
1604   IN     CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
1605   IN     CONST EFI_STRING                      ConfigResp,
1606   IN OUT UINT8                                 *Block,
1607   IN OUT UINTN                                 *BlockSize,
1608   OUT    EFI_STRING                            *Progress
1609   );
1610
1611
1612 /**
1613   This helper function is to be called by drivers to extract portions of
1614   a larger configuration string.
1615
1616   @param  This                    A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL
1617                                   instance.
1618   @param  Configuration           A null-terminated Unicode string in
1619                                   <MultiConfigAltResp> format.
1620   @param  Guid                    A pointer to the GUID value to search for in the
1621                                   routing portion of the ConfigResp string when
1622                                   retrieving  the requested data. If Guid is NULL,
1623                                   then all GUID  values will be searched for.
1624   @param  Name                    A pointer to the NAME value to search for in the
1625                                   routing portion of the ConfigResp string when
1626                                   retrieving  the requested data. If Name is NULL,
1627                                   then all Name  values will be searched for.
1628   @param  DevicePath              A pointer to the PATH value to search for in the
1629                                   routing portion of the ConfigResp string when
1630                                   retrieving  the requested data. If DevicePath is
1631                                   NULL, then all  DevicePath values will be
1632                                   searched for.
1633   @param  AltCfgId                A pointer to the ALTCFG value to search for in
1634                                   the  routing portion of the ConfigResp string
1635                                   when retrieving  the requested data.  If this
1636                                   parameter is NULL,  then the current setting will
1637                                   be retrieved.
1638   @param  AltCfgResp              A pointer to a buffer which will be allocated by
1639                                   the  function which contains the retrieved string
1640                                   as requested.   This buffer is only allocated if
1641                                   the call was successful.
1642
1643   @retval EFI_SUCCESS             The request succeeded. The requested data was
1644                                   extracted  and placed in the newly allocated
1645                                   AltCfgResp buffer.
1646   @retval EFI_OUT_OF_RESOURCES    Not enough memory to allocate AltCfgResp.
1647   @retval EFI_INVALID_PARAMETER   Any parameter is invalid.
1648   @retval EFI_NOT_FOUND           Target for the specified routing data was not
1649                                   found.
1650
1651 **/
1652 EFI_STATUS
1653 EFIAPI
1654 HiiGetAltCfg (
1655   IN  CONST EFI_HII_CONFIG_ROUTING_PROTOCOL    *This,
1656   IN  CONST EFI_STRING                         Configuration,
1657   IN  CONST EFI_GUID                           *Guid,
1658   IN  CONST EFI_STRING                         Name,
1659   IN  CONST EFI_DEVICE_PATH_PROTOCOL           *DevicePath,
1660   IN  CONST UINT16                             *AltCfgId,
1661   OUT EFI_STRING                               *AltCfgResp
1662   );
1663
1664
1665 //
1666 // Global variables
1667 //
1668 extern EFI_EVENT gHiiKeyboardLayoutChanged;
1669
1670 #include "R8Lib.h"
1671
1672 #endif