34. HII Protocols

This section provides code definitions for the HII-related protocols, functions, and type definitions, which are the required architectural mechanisms by which UEFI-compliant systems manage user input. The major areas described include the following:

  • Font management.

  • String management.

  • Image management.

  • Database management.

34.1. Font Protocol

34.1.1. EFI_HII_FONT_PROTOCOL

Summary

Interfaces which retrieve font information.

GUID

#define EFI_HII_FONT_PROTOCOL_GUID \
  { 0xe9ca4775, 0x8657, 0x47fc, \
    {0x97, 0xe7, 0x7e, 0xd6, 0x5a, 0x8, 0x43, 0x24 }}

Protocol

typedef struct _EFI_HII_FONT_PROTOCOL {
  EFI_HII_STRING_TO_IMAGE           StringToImage;
  EFI_HII_STRING_ID_TO_IMAGE        StringIdToImage;
  EFI_HII_GET_GLYPH                 GetGlyph;
  EFI_HII_GET_FONT_INFO             GetFontInfo;
}   EFI_HII_FONT_PROTOCOL;

Members

StringToImage, StringIdToImage

Render a string to a bitmap or to the display.

GetGlyph

Return a specific glyph in a specific font.

GetFontInfo

Return font information for a specific font.

34.1.2. EFI_HII_FONT_PROTOCOL.StringToImage()

Summary

Renders a string to a bitmap or to the display.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_STRING_TO_IMAGE) (
  IN CONST EFI_HII_FONT_PROTOCOL       *This,
  IN EFI_HII_OUT_FLAGS                 Flags,
  IN CONST EFI_STRING                  String,
  IN CONST EFI_FONT_DISPLAY_INFO       *StringInfo OPTIONAL,
  IN OUT EFI_IMAGE_OUTPUT              **Blt,
  IN UINTN                             BltX,
  IN UINTN                             BltY,
  OUT EFI_HII_ROW_INFO                 **RowInfoArray OPTIONAL,
  OUT UINTN                            *RowInfoArraySize OPTIONAL,
  OUT UINTN                            *ColumnInfoArray OPTIONAL
):

Parameters

This

A pointer to the EFI_HII_FONT_PROTOCOL instance.

Flags

Describes how the string is to be drawn. EFI_HII_OUT_FLAGS is defined in Related Definitions, below.

String

Points to the null-terminated string to be displayed.

StringInfo

Points to the string output information, including the color and font. If NULL, then the string will be output in the default system font and color.

Blt

If this points to a non-NULL on entry, this points to the image, which is Blt.Width pixels wide and Blt.Height pixels high. The string will be drawn onto this image and EFI_HII_OUT_FLAG_CLIP is implied. If this points to a NULL on entry, then a buffer will be allocated to hold the generated image and the pointer updated on exit. It is the caller’s responsibility to free this buffer.

BltX, BltY

Specifies the offset from the left and top edge of the image of the first character cell in the image.

RowInfoArray

If this is non-NULL on entry, then on exit, this will point to an allocated buffer containing row information and RowInfoArraySize will be updated to contain the number of elements. This array describes the characters which were at least partially drawn and the heights of the rows. It is the caller’s responsibility to free this buffer.

RowInfoArraySize

If this is non-NULL on entry, then on exit it contains the number of elements in RowInfoArray.

ColumnInfoArray

If this is non-NULL, then on return it will be filled with the horizontal offset for each character in the string on the row where it is displayed. Non-printing characters will have the offset ~0. The caller is responsible to allocate a buffer large enough so that there is one entry for each character in the string, not including the null-terminator. It is possible when character display is normalized that some character cells overlap.

Description

This function renders a string to a bitmap or the screen using the specified font, color and options. It either draws the string and glyphs on an existing bitmap, allocates a new bitmap or uses the screen. The strings can be clipped or wrapped. Optionally, the function also returns the information about each row and the character position on that row.

If EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only based on explicit line breaks and all pixels which would lie outside the bounding box specified by Blt.Width and Blt.Height are ignored. The information in the RowInfoArray only describes characters which are at least partially displayed. For the final row, the RowInfoArray.LineHeight and RowInfoArray.BaseLine may describe pixels which are outside the limit specified by Blt. Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those pixels were not drawn. The LineWidth may describe pixels which are outside the limit specified by Blt.Width (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_X is specified) even though those pixels were not drawn.

If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that if a character’s right-most on pixel cannot fit, then it will not be drawn at all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set.

If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that if a row’s bottom-most pixel cannot fit, then it will not be drawn at all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set.

If EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the right-most line-break opportunity prior to a character whose right-most extent would exceed Blt.Width. If no line-break opportunity can be found, then the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X.

If EFI_HII_OUT_FLAG_TRANSPARENT is set, then StringInfo.BackgroundColor is ignored and all “off” pixels in the character’s drawn will use the pixel value from Blt. This flag cannot be used if Blt is NULL upon entry.

If EFI_HII_IGNORE_IF_NO_GLYPH is set, then characters which have no glyphs are not drawn. Otherwise, they are replaced with Unicode character code 0xFFFD (REPLACEMENT CHARACTER).

If EFI_HII_IGNORE_LINE_BREAK is set, then explicit line break characters will be ignored.

If EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written directly to the output device specified by Screen. Otherwise the string will be rendered to the bitmap specified by Bitmap.

Related Definitions

typedef UINT32 EFI_HII_OUT_FLAGS;

#define EFI_HII_OUT_FLAG_CLIP             0x00000001
#define EFI_HII_OUT_FLAG_WRAP             0x00000002
#define EFI_HII_OUT_FLAG_CLIP_CLEAN_Y     0x00000004
#define EFI_HII_OUT_FLAG_CLIP_CLEAN_X     0x00000008
#define EFI_HII_OUT_FLAG_TRANSPARENT      0x00000010
#define EFI_HII_IGNORE_IF_NO_GLYPH        0x00000020
#define EFI_HII_IGNORE_LINE_BREAK         0x00000040
#define EFI_HII_DIRECT_TO_SCREEN          0x00000080

typedef CHAR16 *EFI_STRING;

typedef struct _EFI_HII_ROW_INFO {
  UINTN                                   StartIndex;
  UINTN                                   EndIndex;
  UINTN                                   LineHeight;
  UINTN                                   LineWidth;
  UINTN                                   BaselineOffset;
}   EFI_HII_ROW_INFO;
StartIndex

The index of the first character in the string which is displayed on the line.

EndIndex

The index of the last character in the string which is displayed on the line.

LineHeight

The height of the line, in pixels.

LineWidth

The width of the text on the line, in pixels.

BaselineOffset

The font baseline offset in pixels from the bottom of the row, or 0 if none.

Status Codes Returned

EFI_SUCCESS

The string was successfully updated.

EFI_OUT_OF_RESOURCES

Unable to allocate an output buffer for RowInfoArray or Blt.

EFI_INVALID_PARAMETER

The String or Blt was NULL.

EFI_INVALID_PARAMETER

Flags were invalid combination

34.1.3. EFI_HII_FONT_PROTOCOL.StringIdToImage()

Summary

Render a string to a bitmap or the screen containing the contents of the specified string.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_STRING_ID_TO_IMAGE) (
  IN   CONST EFI_HII_FONT_PROTOCOL          *This,
  IN   EFI_HII_OUT_FLAGS                    Flags,
  IN   EFI_HII_HANDLE                       PackageList,
  IN   EFI_STRING_ID                        StringId,
  IN   CONST CHAR8*                         Language,
  IN   CONST EFI_FONT_DISPLAY_INFO          *StringInfo OPTIONAL,
  IN  OUT EFI_IMAGE_OUTPUT                  **Blt,
  IN   UINTN                                BltX,
  IN   UINTN                                BltY,
  OUT   EFI_HII_ROW_INFO                    **RowInfoArray OPTIONAL,
  OUT   UINTN                               *RowInfoArraySize OPTIONAL,
  OUT   UINTN                               *ColumnInfoArray OPTIONAL
  );

Parameters

This

A pointer to the EFI_HII_FONT_PROTOCOL instance.

Flags

Describes how the string is to be drawn. EFI_HII_OUT_FLAGS is defined in Related Definitions, below.

PackageList

The package list in the HII database to search for the specified string.

StringId

The string’s id, which is unique within PackageList.

Language

Points to the language for the retrieved string. If NULL, then the current system language is used.

StringInfo

Points to the string output information, including the color and font. If NULL, then the string will be output in the default system font and color.

Blt

If this points to a non-NULL on entry, this points to the image, which is Blt.Width pixels wide and Height pixels high. The string will be drawn onto this image and EFI_HII_OUT_FLAG_CLIP is implied. If this points to a NULL on entry, then a buffer will be allocated to hold the generated image and the pointer updated on exit. It is the caller’s responsibility to free this buffer.

BltX, BltY

Specifies the offset from the left and top edge of the output image of the first character cell in the image.

RowInfoArray

If this is non-NULL on entry, then on exit, this will point to an allocated buffer containing row information and RowInfoArraySize will be updated to contain the number of elements. This array describes the characters which were at least partially drawn and the heights of the rows. It is the caller’s responsibility to free this buffer.

RowInfoArraySize

If this is non-NULL on entry, then on exit it contains the number of elements in RowInfoArray.

ColumnInfoArray

If non-NULL, on return it is filled with the horizontal offset for each character in the string on the row where it is displayed. Non-printing characters will have the offset ~0. The caller is responsible to allocate a buffer large enough so that there is one entry for each character in the string, not including the null-terminator. It is possible when character display is normalized that some character cells overlap.

Description

This function renders a string as a bitmap or to the screen and can clip or wrap the string. The bitmap is either supplied by the caller or else is allocated by the function. The strings are drawn with the font, size and style specified and can be drawn transparently or opaquely. The function can also return information about each row and each character’s position on the row.

If EFI_HII_OUT_FLAG_CLIP is set, then text will be formatted only based on explicit line breaks and all pixels which would lie outside the bounding box specified by Width and Height are ignored. The information in the RowInfoArray only describes characters which are at least partially displayed. For the final row, the LineHeight and BaseLine may describe pixels which are outside the limit specified by Height (unless EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is specified) even though those pixels were not drawn.

If EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that if a character’s right-most on pixel cannot fit, then it will not be drawn at all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set. If EFI_HII_OUT_FLAG_CLIP_CLEAN_Y is set, then it modifies the behavior of EFI_HII_OUT_FLAG_CLIP so that if a row’s bottom most pixel cannot fit, then it will not be drawn at all. This flag requires that EFI_HII_OUT_FLAG_CLIP be set.

If EFI_HII_OUT_FLAG_WRAP is set, then text will be wrapped at the right-most line-break opportunity prior to a character whose right-most extent would exceed Width. If no line-break opportunity can be found, then the text will behave as if EFI_HII_OUT_FLAG_CLIP_CLEAN_X is set. This flag cannot be used with EFI_HII_OUT_FLAG_CLIP_CLEAN_X.

If EFI_HII_OUT_FLAG_TRANSPARENT is set, then BackgroundColor is ignored and all “off” pixels in the character’s glyph will use the pixel value from Blt. This flag cannot be used if Blt is NULL upon entry.

If EFI_HII_IGNORE_IF_NO_GLYPH is set, then characters which have no glyphs are not drawn. Otherwise, they are replaced with Unicode character code 0xFFFD (REPLACEMENT CHARACTER).

If EFI_HII_IGNORE_LINE_BREAK is set, then explicit line break characters will be ignored.

If EFI_HII_DIRECT_TO_SCREEN is set, then the string will be written directly to the output device specified by Screen. Otherwise the string will be rendered to the bitmap specified by Bitmap.

Status Codes Returned

EFI_SUCCESS

The string was successfully updated.

EFI_OUT_OF_RESOURCES

Unable to allocate an output buffer for RowInfoArray or Blt.

EFI_INVALID_PARAMETER

The StringId or PackageList was NULL.

EFI_INVALID_PARAMETER

Flags were invalid combination.

EFI_NOT_FOUND

The StringId is not in the specified PackageList. The specified PackageList is not in the Database.

34.1.4. EFI_HII_FONT_PROTOCOL.GetGlyph()

Summary

Return image and information about a single glyph.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_GLYPH) (
  IN CONST EFI_HII_FONT_PROTOCOL       *This,
  IN CHAR16                            Char,
  IN CONST EFI_FONT_DISPLAY_INFO       *StringInfo,
  OUT EFI_IMAGE_OUTPUT                 **Blt;
  OUT UINTN                            *Baseline OPTIONAL;
  );

Parameters

This

A pointer to the EFI_HII_FONT_PROTOCOL instance.

Char

Character to retrieve.

StringInfo

Points to the string font and color information or NULL if the string should use the default system font and color.

Blt

Thus must point to a NULL on entry. A buffer will be allocated to hold the output and the pointer updated on exit. It is the caller’s responsibility to free this buffer.On return, only Blt.Width, Blt.Height, and Blt.Image.Bitmap are valid.

Baseline

Number of pixels from the bottom of the bitmap to the baseline.

Description

Convert the glyph for a single character into a bitmap.

Status Codes Returned

EFI_SUCCESS

Glyph bitmap created.

EFI_OUT_OF_RESOURCES

Unable to allocate the output buffer Blt.

EFI_WARN_UNKNOWN_GLYPH

The glyph was unknown and was replaced with the glyph for Unicode character code 0xFFFD.

EFI_INVALID_PARAMETER

Blt is NULL or * Blt is !Null

34.1.5. EFI_HII_FONT_PROTOCOL.GetFontInfo()

Summary

Return information about a particular font.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_FONT_INFO) (
  IN    CONST EFI_HII_FONT_PROTOCOL          *This,
  IN  OUT EFI_FONT_HANDLE                    *FontHandle,
  IN    CONST EFI_FONT_DISPLAY_INFO          *StringInfoIn,OPTIONAL
  OUT   EFI_FONT_DISPLAY_INFO                **StringInfoOut,
  IN    CONST EFI_STRING                     String OPTIONAL
  );

typedef VOID                                 *EFI_FONT_HANDLE;

Parameters

This

A pointer to the EFI_HII_FONT_PROTOCOL instance.

FontHandle

On entry, points to the font handle returned by a previous call to GetFontInfo() or points to NULL to start with the first font. On return, points to the returned font handle or points to NULL if there are no more matching fonts.

StringInfoIn

Upon entry, points to the font to return information about. If NULL, then the information about the system default font will be returned.

StringInfoOut

Upon return, contains the matching font’s information. If NULL, then no information is returned. This buffer is allocated with a call to the Boot Service AllocatePool(). It is the caller’s responsibility to call the Boot Service FreePool() when the caller no longer requires the contents of StringInfoOut.

String

Points to the string which will be tested to determine if all characters are available. If NULL, then any font is acceptable.

Description

This function iterates through fonts which match the specified font, using the specified criteria. If String is non-NULL, then all of the characters in the string must exist in order for a candidate font to be returned.

Status Codes Returned

EFI_SUCCESS

Matching font returned successfully.

EFI_NOT_FOUND

No matching font was found.

EFI_OUT_OF_RESOURCES

There were insufficient resources to complete the request.

34.2. EFI HII Font Ex Protocol

The EFI HII Font Ex protocol defines an extension to the EFI HII Font protocol which enables various new capabilities described in this section.

34.2.1. EFI_HII_FONT_EX_PROTOCOL

Summary

Interfaces which retrieve the font information.

GUID

#define EFI_HII_FONT_EX_PROTOCOL_GUID \
  { 0x849e6875, 0xdb35, 0x4df8, 0xb4, \
    {0x1e, 0xc8, 0xf3, 0x37, 0x18, 0x7, 0x3f }}

Protocol

typedef struct _EFI_HII_FONT_EX_PROTOCOL {
  EFI_HII_STRING_TO_IMAGE_EX           StringToImageEx;
  EFI_HII_STRING_ID_TO_IMAGE_EX        StringIdToImageEx;
  EFI_HII_GET_GLYPH_EX                 GetGlyphEx;
  EFI_HII_GET_FONT_INFO_EX             GetFontInfoEx;
  EFI_HII_GET_GLYPH_INFO               GetGlyphInfo;
}   EFI_HII_FONT_EX_PROTOCOL;

Members

StringToImageEx, StringIdToImageEx

Render a string to a bitmap or to the display. This function will try to use the external font glyph generator for generating the glyph if it can’t find the glyph in the font database.

GetGlphyEx

Return a specific glyph in a specific font. This function will try to use the external font glyph generator for generating the glyph if it can’t find the glyph in the font database.

GetFontInfoEx

Return the font information for a specific font, this protocol invokes original EFI_HII_FONT_PROTOCOL.GetFontInfo() implicitly.

GetGlphyInfoEx

Return the glyph information for the single glyph.

34.2.2. EFI_HII_FONT_EX_PROTOCOL.StringToImageEx()

Summary

Render a string to a bitmap or to the display. The prototype of this extension function is the same with EFI_HII_FONT_PROTOCOL.StringToImage().

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_STRING_TO_IMAGE_EX)(
  IN CONST EFI_HII_FONT_EX_PROTOCOL       *This,
  IN EFI_HII_OUT_FLAGS                    Flags,
  IN CONST EFI_STRING                     String,
  IN CONST EFI_FONT_DISPLAY_INFO          *StringInfo OPTIONAL,
  IN OUT EFI_IMAGE_OUTPUT                 **Blt,
  IN UINTN                                BltX,
  IN UINTN                                BltY,
  OUT EFI_HII_ROW_INFO                    **RowInfoArray OPTIONAL,
  OUT UINTN                               *RowInfoArraySize OPTIONAL,
  OUT UINTN                               *ColumnInfoArray OPTIONAL
  );

Parameters

Same with EFI_HII_FONT_PROTOCOL.STRINGTOIMAGE() .

Description

This function is similar to EFI_HII_FONT_PROTOCOL.StringToImage(). The difference is that this function will locate all EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL instances that are installed in the system when the glyph in the string with the given font information is not found in the current HII glyph database. The function will attempt to generate the glyph information and the bitmap using the first EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL instance that supports the requested font information in the EFI_FONT_DISPLAY_INFO.

Status Codes Returned — Same with EFI_HII_FONT_PROTOCOL.STRINGTOIMAGE() .

34.2.3. EFI_HII_FONT_EX_PROTOCOL.StringIdToImageEx()

Summary

Render a string to a bitmap or the screen containing the contents of the specified string. The prototype of this extension function is the same with EFI_HII_FONT_PROTOCOL.STRINGTOIMAGE() .

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_STRING_ID_TO_IMAGE_EX)(
  IN CONST EFI_HII_FONT_EX_PROTOCOL          *This,
  IN EFI_HII_OUT_FLAGS                       Flags,
  IN EFI_HII_HANDLE                          PackageList,
  IN EFI_STRING_ID                           StringId,
  IN CONST CHAR8                             *Language,
  IN CONST EFI_FONT_DISPLAY_INFO             *StringInfo OPTIONAL,
  IN OUT EFI_IMAGE_OUTPUT                    **Blt,
  IN UINTN                                   BltX,
  IN UINTN                                   BltY,
  OUT EFI_HII_ROW_INFO                       **RowInfoArray OPTIONAL,
  OUT UINTN                                  *RowInfoArraySize OPTIONAL,
  OUT UINTN                                  *ColumnInfoArray OPTIONAL
  );

Parameters

Same with EFI_HII_FONT_PROTOCOL.STRINGTOIMAGE() .

Description

This function is similar to EFI_HII_FONT_PROTOCOL.StringIdToImage().*The difference is that this function will locate all *EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL instances that are installed in the system when the glyph in the string with the given font information is not found in the current HII glyph database. The function will attempt to generate the glyph information and the bitmap using the first EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL instance that supports the requested font information in the EFI_FONT_DISPLAY_INFO .

Status Codes Returned — Same with EFI_HII_FONT_PROTOCOL.STRINGTOIMAGE() .

34.2.4. EFI_HII_FONT_EX_PROTOCOL.GetGlyphEx()

Summary

Return image and baseline about a single glyph. The prototype of this extension function is the same with EFI_HII_FONT_PROTOCOL.GETGLYPH() .

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_GLYPH_EX)(
  IN CONST EFI_HII_FONT_EX_PROTOCOL     *This,
  IN CHAR16                             Char,
  IN CONST EFI_FONT_DISPLAY_INFO        *StringInfo,
  IN OUT EFI_IMAGE_OUTPUT               **Blt,
  IN UINTN                              Baseline OPTIONAL
  );

Parameters — Same with EFI_HII_FONT_PROTOCOL.GETGLYPH() .

Description

The difference is that this function will locate all EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL instances that are installed in the system when the glyph in the string with the given font information is not found in the current HII glyph database. The function will attempt to generate the glyph information and the bitmap using the first EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL instance that supports the requested font information in the EFI_FONT_DISPLAY_INFO.

Status Codes Returned — Same as EFI_HII_FONT_PROTOCOL.GETGLYPH() .

34.2.5. EFI_HII_FONT_EX_PROTOCOL.GetFontInfoEx()

Summary

Return information about a particular font. The prototype of this extension function is the same with

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_FONT_INFO_EX)(
  IN CONST EFI_HII_FONT_EX_PROTOCOL             *This,
  IN OUT EFI_FONT_HANDLE                        *FontHandle,
  IN CONST EFI_FONT_DISPLAY_INFO                *StringInfoIn, OPTIONAL
  OUT EFI_FONT_DISPLAY_INFO                     **StringInfoOut,
  IN CONST EFI_STRING                           String OPTIONAL
  );

Parameters — Same with EFI_HII_FONT_PROTOCOL.GETFONTINFO() .

Description

Same with EFI_HII_FONT_PROTOCOL.GETFONTINFO() . This protocol invokes EFI_HII_FONT_PROTOCOL.GETFONTINFO() . implicitly.

Status Codes Returned — Same as EFI_HII_FONT_PROTOCOL.GETFONTINFO() .

34.2.6. EFI_HII_FONT_EX_PROTOCOL.GetGlyphInfo()

Summary

The function returns the information of the single glyph.

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_GLYPH_INFO)(
  IN CONST EFI_HII_FONT_EX_PROTOCOL          *This,
  IN CHAR16                                  Char,
  IN CONST EFI_FONT_DISPLAY_INFO             *FontDisplayInfo,
  OUT EFI_HII_GLYPH_INFO *                   GlyphInfo
  );

Parameters

This

EFI_HII_FONT_EX_PROTOCOL instance.

Char

Information of Character to retrieve.

FontDisplayInfo

Font display information of this character.

GlyphInfo

Pointer to retrieve the glyph information.

Description

This function returns the glyph information of character in the specific font family. This function will locate all EFI_HII_FONT_GLYPH_GENERATOR protocol instances that are installed in the system, and attempt to use them if it can’t find the glyph information in the font database. It returns EFI_UNSUPPORTED if neither the font database nor any instances of the EFI_HII_FONT_GLYPH_GENRATOR protocols support the font glyph in the specific font family. Otherwise, the EFI_HII_GLYPH_INFO is returned in GlyphInfo. This function only returns the glyph geometry information instead of allocating the buffer for EFI_IMAGE_OUTPUT and drawing the glyph in the buffer.

_images/HII_Protocols-2.png

Fig. 34.1 Glyph Example

Status Codes Returned

EFI_SUCCESS

The glyph information was returned to GlyphInfo.

EFI_OUT_OF_RESOURCES

Memory allocation failed in this function.

EFI_NOT_FOUND

The input character was not found in the database.

EFI_UNSUPPORTED

The font is not supported.

EFI_INVALID_PARAMETER

The GlyphInfo or FontDisplayInfo was NULL.

34.2.7. Code Definitions

34.2.7.1. EFI_FONT_DISPLAY_INFO

Summary

Describes font output-related information.

Prototype

typedef struct _EFI_FONT_DISPLAY_INFO {
  EFI_GRAPHICS_OUTPUT_BLT_PIXEL                 ForegroundColor;
  EFI_GRAPHICS_OUTPUT_BLT_PIXEL                 BackgroundColor;
  EFI_FONT_INFO_MASK                            FontInfoMask;
  EFI_FONT_INFO                                 FontInfo
}  EFI_FONT_DISPLAY_INFO;

Members

FontInfo

The font information. Type EFI_FONT_INFO is defined in EFI_HII_STRING_PROTOCOL.NewString().

ForegroundColor

The color of the “on” pixels in the glyph in the bitmap.

BackgroundColor

The color of the “off” pixels in the glyph in the bitmap.

FontInfoMask

The font information mask determines which portion of the font information will be used and what to do if the specific font is not available.

Description

This structure is used for describing the way in which a string should be rendered in a particular font. FontInfo specifies the basic font information and ForegroundColor and BackgroundColor specify the color in which they should be displayed. The flags in FontInfoMask describe where the system default should be supplied instead of the specified information. The flags also describe what options can be used to make a match between the font requested and the font available.

If EFI_FONT_INFO_SYS_FONT is specified, then the font name in FontInfo is ignored and the system font name is used. This flag cannot be used with EFI_FONT_INFO_ANY_FONT.

If EFI_FONT_INFO_SYS_SIZE is specified, then the font height specified in FontInfo is ignored and the system font height is used instead. This flag cannot be used with EFI_FONT_INFO_ANY_SIZE.

If EFI_FONT_INFO_SYS_STYLE is specified, then the font style in FontInfo is ignored and the system font style is used. This flag cannot be used with EFI_FONT_INFO_ANY_STYLE.

If EFI_FONT_INFO_SYS_FORE_COLOR is specified, then ForegroundColor is ignored and the system foreground color is used.

If EFI_FONT_INFO_SYS_BACK_COLOR is specified, then BackgroundColor is ignored and the system background color is used.

If EFI_FONT_INFO_RESIZE is specified, then the system may attempt to stretch or shrink a font to meet the size requested. This flag cannot be used with EFI_FONT_INFO_ANY_SIZE.

If EFI_FONT_INFO_RESTYLE is specified, then the system may attempt to remove some of the specified styles in order to meet the style requested. This flag cannot be used with EFI_FONT_INFO_ANY_STYLE.

If EFI_FONT_INFO_ANY_FONT is specified, then the system may attempt to match with any font. This flag cannot be used with EFI_FONT_INFO_SYS_FONT.

If EFI_FONT_INFO_ANY_SIZE is specified, then the system may attempt to match with any font size. This flag cannot be used with EFI_FONT_INFO_SYS_SIZE or EFI_FONT_INFO_RESIZE .

If EFI_FONT_INFO_ANY_STYLE is specified, then the system may attempt to match with any font style. This flag cannot be used with EFI_FONT_INFO_SYS_STYLE or EFI_FONT_INFO_RESTYLE.

Related Definitions

typedef UINT32 EFI_FONT_INFO_MASK;

#define EFI_FONT_INFO_SYS_FONT         0x00000001
#define EFI_FONT_INFO_SYS_SIZE         0x00000002
#define EFI_FONT_INFO_SYS_STYLE        0x00000004
#define EFI_FONT_INFO_SYS_FORE_COLOR   0x00000010
#define EFI_FONT_INFO_SYS_BACK_COLOR   0x00000020
#define EFI_FONT_INFO_RESIZE           0x00001000
#define EFI_FONT_INFO_RESTYLE          0x00002000
#define EFI_FONT_INFO_ANY_FONT         0x00010000
#define EFI_FONT_INFO_ANY_SIZE         0x00020000
#define EFI_FONT_INFO_ANY_STYLE        0x00040000

34.2.7.2. EFI_IMAGE_OUTPUT

Summary

Describes information about either a bitmap or a graphical output device.

Prototype

typedef struct _EFI_IMAGE_OUTPUT {
  UINT16                               Width;
  UINT16                               Height;
  union {
    EFI_GRAPHICS_OUTPUT_BLT_PIXEL      *Bitmap;
    EFI_GRAPHICS_OUTPUT_PROTOCOL       *Screen;
  } Image;
}  EFI_IMAGE_OUTPUT;

Members

Width

Width of the output image.

Height

Height of the output image.

Bitmap

Points to the output bitmap.

Screen

Points to the EFI_GRAPHICS_OUTPUT_PROTOCOL which describes the screen on which to draw the specified string.

34.3. String Protocol

34.3.1. EFI_HII_STRING_PROTOCOL

Summary

Interfaces which manipulate string data.

GUID

#define EFI_HII_STRING_PROTOCOL_GUID \
  { 0xfd96974, 0x23aa, 0x4cdc,\
    { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a }}

Protocol

typedef struct _EFI_HII_STRING_PROTOCOL {
  EFI_HII_NEW_STRING                      NewString;
  EFI_HII_GET_STRING                      GetString;
  EFI_HII_SET_STRING                      SetString;
  EFI_HII_GET_LANGUAGES                   GetLanguages;
  EFI_HII_GET_2ND_LANGUAGES               GetSecondaryLanguages;
}   EFI_HII_STRING_PROTOCOL;

Members

NewString

Add a new string.

GetString

Retrieve a string and related string information.

SetString

Change a string.

GetLanguages

List the languages for a particular package list.

GetSecondaryLanguages

List supported secondary languages for a particular primary language.

34.3.2. EFI_HII_STRING_PROTOCOL.NewString()

Summary

Creates a new string in a specific language and add it to strings from a specific package list.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_NEW_STRING) (
  IN CONST EFI_HII_STRING_PROTOCOL           *This,
  IN EFI_HII_HANDLE                          PackageList,
  OUT EFI_STRING_ID                          *StringId
  IN CONST CHAR8                             *Language,
  IN CONST CHAR16                            *LanguageName OPTIONAL,
  IN CONST EFI_STRING                        String,
  IN CONST EFI_FONT_INFO                     *StringFontInfo
  );

Parameters

This

A pointer to the EFI_HII_STRING_PROTOCOL instance.

PackageList

Handle of the package list where this string will be added.

Language

Points to the language for the new string. The language information is in the format described by Appendix M — Formats — Language Codes and Language Code Arrays of the UEFI Specification.

LanguageName

Points to the printable language name to associate with the passed in Language field. This is analogous to passing in “zh-Hans” in the Language field and LanguageName might contain “Simplified Chinese” as the printable language.

String

Points to the new null-terminated string.

StringFontInfo

Points to the new string’s font information or NULL if the string should have the default system font, size and style.

StringId

On return, contains the new strings id, which is unique within PackageList. Type EFI_STRING_ID is defined in EFI_IFR_OP_HEADER .

Description

This function adds the string String to the group of strings owned by PackageList, with the specified font information StringFontInfo and returns a new string id. The new string identifier is guaranteed to be unique within the package list. That new string identifier is reserved for all languages in the package list.

Related Definitions

typedef struct {
  EFI_HII_FONT_STYLE       FontStyle;
  UINT16                   FontSize;
  CHAR16                   FontName[...];
}   EFI_FONT_INFO;
FontStyle

The design style of the font. Type EFI_HII_FONT_STYLE is defined in Fixed Header.

FontSize

The character cell height, in pixels.

FontName

The null-terminated font family name.

Status Codes Returns

EFI_SUCCESS

The new string was added successfully

EFI_OUT_OF_RESOURCES

Could not add the string.

EFI_INVALID_PARAMETER

String is NULL or StringId is NULL or Language is NULL.

EFI_NOT_FOUND

The input package list could not be found in the current database.

34.3.3. EFI_HII_STRING_PROTOCOL.GetString()

Summary

Returns information about a string in a specific language, associated with a package list.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_STRING) (
  IN   CONST EFI_HII_STRING_PROTOCOL      *This,
  IN   CONST CHAR8                        *Language,
  IN   EFI_HII_HANDLE                     PackageList,
  IN   EFI_STRING_ID                      StringId,
  OUT  EFI_STRING                         String,
  IN  OUT UINTN                           *StringSize,
  OUT  EFI_FONT_INFO                      **StringFontInfo OPTIONAL
  );

Parameters

This

A pointer to the EFI_HII_STRING_PROTOCOL instance.

PackageList

The package list in the HII database to search for the specified string.

Language

Points to the language for the retrieved string. Callers of interfaces that require RFC 4646 language codes to retrieve a Unicode string must use the RFC 4647 algorithm to lookup the Unicode string with the closest matching RFC 4646 language code.

StringId

The string’s id, which is unique within PackageList.

String

Points to the new null-terminated string.

StringSize

On entry, points to the size of the buffer pointed to by String, in bytes. On return, points to the length of the string, in bytes.

StringFontInfo

Points to a buffer that will be callee allocated and will have the string’s font information into this buffer. The caller is responsible for freeing this buffer. If the parameter is NULL a buffer will not be allocated and the string font information will not be returned.

Description

This function retrieves the string specified by StringId which is associated with the specified PackageList in the language Language and copies it into the buffer specified by String.

If the string specified by StringId is not present in the specified PackageList, then EFI_NOT_FOUND is returned. If the string specified by StringId is present, but not in the specified language then EFI_INVALID_LANGUAGE is returned.

If the buffer specified by StringSize is too small to hold the string, then EFI_BUFFER_TOO_SMALL will be returned. StringSize will be updated to the size of buffer actually required to hold the string.

Status Codes Returned

EFI_SUCCESS

The string was returned successfully.

EFI_NOT_FOUND

The string specified by StringId is not available. The specified PackageList is not in the Database.

EFI_INVALID_LANGUAGE

The string specified by StringId is available but not in the specified language.

EFI_BUFFER_TOO_SMALL

The buffer specified by StringLength is too small to hold the string.

EFI_INVALID_PARAMETER

The Language or StringSize was NULL.

EFI_INVALID_PARAMETER

The value referenced by StringLength was not zero and String was NULL.

EFI_OUT_OF_RESOURCES

There were insufficient resources to complete the request.

34.3.4. EFI_HII_STRING_PROTOCOL.SetString()

Summary

Change information about the string.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_SET_STRING) (
  IN CONST EFI_HII_STRING_PROTOCOL        *This,
  IN EFI_HII_HANDLE                       PackageList,
  IN EFI_STRING_ID                        StringId,
  IN CONST CHAR8                          *Language,
  IN CONST EFI_STRING                     String,
  IN CONST EFI_FONT_INFO                  *StringFontInfo OPTIONAL

  );

Parameters

This

A pointer to the EFI_HII_STRING_PROTOCOL instance.

PackageList

The package list containing the strings.

Language

Points to the language for the updated string.

StringId

The string id, which is unique within PackageList.

String

Points to the new null-terminated string.

StringFontInfo

Points to the string’s font information or NULL if the string font information is not changed.

Description

This function updates the string specified by StringId in the specified PackageList to the text specified by String and, optionally, the font information specified by StringFontInfo . There is no way to change the font information without changing the string text.

Status Codes Returned

EFI_SUCCESS

The string was successfully updated.

EFI_NOT_FOUND

The string specified by StringId is not in the database. The specified PackageList is not in the Database.

EFI_INVALID_PARAMETER

The String or Language was NULL.

EFI_OUT_OF_RESOURCES

The system is out of resources to accomplish the task.

34.3.5. EFI_HII_STRING_PROTOCOL.GetLanguages()

Summary

Returns a list of the languages present in strings in a package list.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_LANGUAGES) (
  IN   CONST EFI_HII_STRING_PROTOCOL      *This,
  IN   EFI_HII_HANDLE                     PackageList,
  IN OUT CHAR8                            *Languages,
  IN OUT UINTN                            *LanguagesSize
  );

Parameters

This

A pointer to the EFI_HII_STRING_PROTOCOL instance.

PackageList

The package list to examine.

Languages

Points to the buffer to hold the returned null-terminated ASCII string.

LanguageSize

On entry, points to the size of the buffer pointed to by Languages, in bytes. On return, points to the length of Languages, in bytes.

Description

This function returns the list of supported languages, in the format specified in Appendix M — Formats — Language Codes and Language Code Arrays .

Status Codes Returned

EFI_SUCCESS

The languages were returned successfully.

EFI_BUFFER_TOO_SMALL

The LanguagesSize is too small to hold the list of supported languages. LanguageSize is updated to contain the required size.

EFI_NOT_FOUND

The specified PackageList is not in the Database.

EFI_INVALID_PARAMETER

LanguagesSize is NULL.

EFI_INVALID_PARAMETER

The value referenced by LanguagesSize is not zero and Languages is NULL.

34.3.6. EFI_HII_STRING_PROTOCOL.GetSecondaryLanguages()

Summary

Given a primary language, returns the secondary languages supported in a package list.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_2ND_LANGUAGES) (
  IN   CONST EFI_HII_STRING_PROTOCOL         *This,
  IN   EFI_HII_HANDLE                        PackageList,
  IN   CONST CHAR8*                          PrimaryLanguage;
  IN OUT CHAR8                               *SecondaryLanguages,
  IN OUT UINTN                               *SecondaryLanguagesSize
  );

Parameters

This

A pointer to the EFI_HII_STRING_PROTOCOL instance.

PackageList

The package list to examine.

Primary Language

Points to the null-terminated ASCII string that specifies the primary language. Languages are specified in the format specified in Appendix M — Formats — Language Codes and Language Code Arrays of the UEFI Specification.

SecondaryLanguages

Points to the buffer to hold the returned null-terminated ASCII string that describes the list of secondary languages for the specified PrimaryLanguage. If there are no secondary languages, the function returns successfully, but this is set to NULL.

SecondaryLanguagesSize

On entry, points to the size of the buffer pointed to by SecondaryLanguages, in bytes. On return, points to the length of SecondaryLanguages in bytes.

Description

Each string package has associated with it a single primary language and zero or more secondary languages. This routine returns the secondary languages associated with a package list.

Status Codes Returned

EFI_SUCCESS

Secondary languages correctly returned

EFI_BUFFER_TOO_SMALL

The buffer specified by SecondaryLanguagesSize is too small to hold the returned information. SecondaryLanguageSize is updated to hold the size of the buffer required.

EFI_INVALID_LANGUAGE

The language specified by FirstLanguage is not present in the specified package list.

EFI_NOT_FOUND

The specified PackageList is not in the Database.

EFI_INVALID_PARAMETER

PrimaryLanguage or SecondaryLanguagesSize is NULL.

EFI_INVALID_PARAMETER

The value referenced by SecondaryLanguagesSize is not zero and SecondaryLanguages is NULL.

34.4. Image Protocol

34.4.1. EFI_HII_IMAGE_PROTOCOL

Summary

Protocol which allow access to images in the images database.

GUID

#define EFI_HII_IMAGE_PROTOCOL_GUID \
  { 0x31a6406a, 0x6bdf, 0x4e46,\
    { 0xb2, 0xa2, 0xeb, 0xaa, 0x89, 0xc4, 0x9, 0x20 }}

Protocol

typedef struct _EFI_HII_IMAGE_PROTOCOL {
  EFI_HII_NEW_IMAGE            NewImage;
  EFI_HII_GET_IMAGE            GetImage;
  EFI_HII_SET_IMAGE            SetImage;
  EFI_HII_DRAW_IMAGE           DrawImage;
  EFI_HII_DRAW_IMAGE_ID        DrawImageId;
} EFI_HII_IMAGE_PROTOCOL;

Members

NewImage

Add a new image.

GetImage

Retrieve an image and related font information.

SetImage

Change an image.

34.4.2. EFI_HII_IMAGE_PROTOCOL.NewImage()

Summary

Creates a new image and add it to images from a specific package list.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_NEW_IMAGE) (
  IN CONST EFI_HII_IMAGE_PROTOCO     *This,
  IN EFI_HII_HANDLE                  PackageList,
  OUT EFI_IMAGE_ID                   *ImageId
  IN CONST EFI_IMAGE_INPUT           *Image
  );

Parameters

This

A pointer to the EFI_HII_IMAGE_PROTOCOL instance.

PackageList

Handle of the package list where this image will be added.

ImageId

On return, contains the new image id, which is unique within PackageList.

Image

Points to the image.

Description

This function adds the image Image to the group of images owned by PackageList, and returns a new image identifier ( ImageId ).

Related Definitions

typedef UINT16 EFI_IMAGE_ID;

typedef struct {
  UINT32                         Flags;
  UINT16                         Width;
  UINT16                         Height;
  EFI_GRAPHICS_OUTPUT_BLT_PIXEL  *Bitmap;
}   EFI_IMAGE_INPUT;
Flags

Describe image characteristics. If EFI_IMAGE_TRANSPARENT is set, then the image was designed for transparent display. #define EFI_IMAGE_TRANSPARENT 0x00000001

Width

Image width, in pixels.

Height

Image height, in pixels.

Bitmap

A pointer to the actual bitmap, organized left-to-right, top-to-bottom. The size of the bitmap is Width * Height * size of (EFI_GRAPHICS_OUTPUT_BLT_PIXEL).

Status Codes Returned

EFI_SUCCESS

The new image was added successfully

EFI_OUT_OF_RESOURCES

Could not add the image.

EFI_INVALID_PARAMETER

Image is NULL or ImageId is NULL.

EFI_NOT_FOUND

The PackageList could not be found.

34.4.3. EFI_HII_IMAGE_PROTOCOL.GetImage()

Summary

Returns information about an image, associated with a package list.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_IMAGE) (
  IN CONST EFI_HII_IMAGE_PROTOCOL    *This,
  IN EFI_HII_HANDLE                  PackageList,
  IN EFI_IMAGE_ID                    ImageId,
  OUT EFI_IMAGE_INPUT                *Image
  );

Parameters

This

A pointer to the EFI_HII_IMAGE_PROTOCOL instance.

PackageList

The package list in the HII database to search for the specified image.

ImageId

The image’s id, which is unique within PackageList.

Image

Points to the new image.

Description

This function retrieves the image specified by ImageId which is associated with the specified PackageList and copies it into the buffer specified by Image.

If the image specified by ImageId is not present in the specified PackageList, then EFI_NOT_FOUND is returned.

The actual bitmap (I mage->Bitmap ) should not be freed by the caller and should not be modified directly.

Status Codes Returned

EFI_SUCCESS

The image was returned successfully.

EFI_NOT_FOUND

The image specified by ImageId is not available. The specified PackageList is not in the Database.

EFI_INVALID_PARAMETER

Image was NULL.

EFI_OUT_OF_RESOURCES

The bitmap could not be retrieved because there was not enough memory.

34.4.4. EFI_HII_IMAGE_PROTOCOL.SetImage()

Summary

Change information about the image.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_SET_IMAGE) (
  IN CONST EFI_HII_IMAGE_PROTOCOL    *This,
  IN EFI_HII_HANDLE                  PackageList,
  IN EFI_IMAGE_ID                    ImageId,
  IN CONST EFI_IMAGE_INPUT           *Image,
  );

Parameters

This

A pointer to the EFI_HII_IMAGE_PROTOCOL instance.

PackageList

The package list containing the images.

ImageId

The image id, which is unique within PackageList.

Image

Points to the image.

Description

This function updates the image specified by ImageId in the specified PackageListHandle to the image specified by Image .

Status Codes Returned

EFI_SUCCESS

The image was successfully updated.

EFI_NOT_FOUND

The image specified by ImageId is not in the database. The specified PackageList is not in the Database.

EFI_INVALID_PARAMETER

The Image was NULL.

34.4.5. EFI_HII_IMAGE_PROTOCOL.DrawImage()

Summary

Renders an image to a bitmap or to the display.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DRAW_IMAGE) (
  IN CONST EFI_HII_IMAGE_PROTOCOL    *This,
  IN EFI_HII_DRAW_FLAGS              Flags,
  IN CONST EFI_IMAGE_INPUT           *Image,
  IN OUT EFI_IMAGE_OUTPUT            **Blt,
  IN UINTN                           BltX,
  IN UINTN                           BltY,
  );

Parameters

This

A pointer to the EFI_HII_IMAGE_PROTOCOL instance.

Flags

Describes how the image is to be drawn. EFI_HII_DRAW_FLAGS is defined in Related Definitions, below.

Image

Points to the image to be displayed.

Blt

If this points to a non-NULL on entry, this points to the image, which is Width pixels wide and Height pixels high. The image will be drawn onto this image and EFI_HII_DRAW_FLAG_CLIP is implied. If this points to a NULL on entry, then a buffer will be allocated to hold the generated image and the pointer updated on exit. It is the caller’s responsibility to free this buffer.

BltX, BltY

Specifies the offset from the left and top edge of the image of the first pixel in the image.

Description

This function renders an image to a bitmap or the screen using the specified color and options. It draws the image on an existing bitmap, allocates a new bitmap or uses the screen. The images can be clipped.

If EFI_HII_DRAW_FLAG_CLIP is set, then all pixels drawn outside the bounding box specified by Width and Height are ignored.

The EFI_HII_DRAW_FLAG_TRANSPARENT flag determines whether the image will be drawn transparent or opaque. If EFI_HII_DRAW_FLAG_FORCE_TRANS is set then the image’s pixels will be drawn so that all “off” pixels in the image will be drawn using the pixel value from BLT and all other pixels will be copied. If EFI_HII_DRAW_FLAG_FORCE_OPAQUE is set, then the image’s pixels will be copied directly to the destination. If EFI_HII_DRAW_FLAG_DEFAULT is set, then the image will be drawn transparently or opaque, depending on the image’s transparency setting (see EFI_IMAGE_TRANSPARENT). Images cannot be drawn transparently if Blt is NULL.

If EFI_HII_DIRECT_TO_SCREEN is set, then the image will be written directly to the output device specified by Screen. Otherwise the image will be rendered to the bitmap specified by Bitmap.

Status Codes Returned

EFI_SUCCESS

The image was successfully updated.

EFI_OUT_OF_RESOURCES

Unable to allocate an output buffer for Blt.

EFI_INVALID_PARAMETER

The Image or Blt was NULL.

34.4.6. EFI_HII_IMAGE_PROTOCOL.DrawImageId()

Summary

Render an image to a bitmap or the screen containing the contents of the specified image.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DRAW_IMAGE_ID) (
  IN CONST EFI_HII_IMAGE_PROTOCOL      *This,
  IN EFI_HII_DRAW_FLAGS                Flags,
  IN EFI_HII_HANDLE                    PackageList,
  IN EFI_IMAGE_ID                      ImageId,
  IN OUT EFI_IMAGE_OUTPUT              **Blt,
  IN UINTN                             BltX,
  IN UINTN                             BltY,
  );

Parameters

This

A pointer to the EFI_HII_IMAGE_PROTOCOL instance.

Flags

Describes how the image is to be drawn. EFI_HII_DRAW_FLAGS is defined in Related Definitions, below.

PackageList

The package list in the HII database to search for the specified image.

ImageId

The image’s id, which is unique within PackageList.

Blt

If this points to a non-NULL on entry, this points to the image, which is Width pixels wide and Height pixels high. The image will be drawn onto this image and EFI_HII_DRAW_FLAG_CLIP is implied. If this points to a NULL on entry, then a buffer will be allocated to hold the generated image and the pointer updated on exit. It is the caller’s responsibility to free this buffer.

BltX, BltY

Specifies the offset from the left and top edge of the output image of the first pixel in the image.

Description

This function renders an image to a bitmap or the screen using the specified color and options. It draws the image on an existing bitmap, allocates a new bitmap or uses the screen. The images can be clipped.

If EFI_HII_DRAW_FLAG_CLIP is set, then all pixels drawn outside the bounding box specified by Width and Height are ignored.

The EFI_HII_DRAW_FLAG_TRANSPARENT flag determines whether the image will be drawn transparent or opaque. If EFI_HII_DRAW_FLAG_FORCE_TRANS is set, then the image will be drawn so that all “off” pixels in the image will be drawn using the pixel value from Blt and all other pixels will be copied. If EFI_HII_DRAW_FLAG_FORCE_OPAQUE is set, then the image’s pixels will be copied directly to the destination. If EFI_HII_DRAW_FLAG_DEFAULT is set, then the image will be drawn transparently or opaque, depending on the image’s transparency setting ( EFI_IMAGE_TRANSPARENT ). Images cannot be drawn transparently if Blt is NULL.

If EFI_HII_DIRECT_TO_SCREEN is set, then the image will be written directly to the output device specified by Screen. Otherwise the image will be rendered to the bitmap specified by Bitmap.

Related Definitions

typedef UINT32 EFI_HII_DRAW_FLAGS;
#define EFI_HII_DRAW_FLAG_CLIP          0x00000001
#define EFI_HII_DRAW_FLAG_TRANSPARENT   0x00000030
#define EFI_HII_DRAW_FLAG_DEFAULT       0x00000000
#define EFI_HII_DRAW_FLAG_FORCE_TRANS   0x00000010
#define EFI_HII_DRAW_FLAG_FORCE_OPAQUE  0x00000020
#define EFI_HII_DIRECT_TO_SCREEN        0x00000080

Status Codes Returned

EFI_SUCCESS

The image was successfully updated.

EFI_OUT_OF_RESOURCES

Unable to allocate an output buffer for RowInfoArray or Blt.

EFI_NOT_FOUND

The image specified by ImageId is not in the database. The specified PackageList is not in the Database

EFI_INVALID_PARAMETER

The Image or Blt was NULL.

34.5. EFI HII Image Ex Protocol

The EFI HII Image Ex protocol defines an extension to the EFI HII Image protocol which enables various new capabilities described in this section.

34.5.1. EFI_HII_IMAGE_EX_PROTOCOL

Summary

Protocol which allows access to the images in the images database

GUID

#define EFI_HII_IMAGE_EX_PROTOCOL_GUID \
  {0x1a1241e6, 0x8f19, 0x41a9, 0xbc, \
    {0xe, 0xe8, 0xef,0x39, 0xe0, 0x65, 0x46}}

Protocol

typedef struct _EFI_HII_IMAGE_EX_PROTOCOL {
  EFI_HII_NEW_IMAGE_EX               NewImageEx;
  EFI_HII_GET_IMAGE_EX               GetImageEx;
  EFI_HII_SET_IMAGE_EX               SetImageEx;
  EFI_HII_DRAW_IMAGE_EX              DrawImageEx;
  EFI_HII_DRAW_IMAGE_ID_EX           DrawImageIdEx;
  EFI_HII_GET_IMAGE_INFO             GetImageInfo;
}   EFI_HII_IMAGE_EX_PROTOCOL;

Members

NewImageEx

Add a new image. This protocol invokes the original EFI_HII_IMAGE_PROTOCOL.NewImage() implicitly.

GetImageEx

Retrieve an image and the related image information. This function will try to locate the EFI_HII_IMAGE_DECODER_PROTOCOL if the image decoder for the image is not supported by the EFI HII image EX protocol.

SetImageEx

Change information about the image, this protocol invokes original EFI_HII_IMAGE_PROTOCOL.SetImage() implicitly.

DrawImageEx

Renders an image to a bitmap or the display, this protocol invokes original EFI_HII_IMAGE_PROTOCOL.DrawImage() implicitly.

DrawImageIdEx

Renders an image to a bitmap or the screen containing the contents of the specified image, this protocol invokes original EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly.

GetImageInfo

This function retrieves the image information specified by the image ID which is associated with the specified HII package list. This function only returns the geometry of the image instead of allocating the memory buffer and decoding the image to the buffer.

34.5.2. EFI_HII_IMAGE_EX_PROTOCOL.NewImageEx()

Summary

The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.NEWIMAGE() .

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_NEW_IMAGE_EX)(
  IN CONST EFI_HII_IMAGE_EX_PROTOCOL     *This,
  IN EFI_HII_HANDLE                      PackageList,
  OUT EFI_IMAGE_ID                       *ImageId
  IN OUT EFI_IMAGE_INPUT                 *Image
);

Parameters

Same with EFI_HII_IMAGE_PROTOCOL.NEWIMAGE() .

Description

Same with EFI_HII_IMAGE_PROTOCOL.NEWIMAGE() . This protocol invokes EFI_HII_IMAGE_PROTOCOL.NEWIMAGE() implicitly.

Status Codes Returned — Same as EFI_HII_IMAGE_PROTOCOL.NEWIMAGE()

34.5.3. EFI_HII_IMAGE_EX_PROTOCOL.GetImageEx()

Summary

Return the information about the image, associated with the package list. The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.GETIMAGE()

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_IMAGE_EX)(
  IN CONST EFI_HII_IMAGE_EX_PROTOCOL   *This,
  IN EFI_HII_HANDLE                    PackageList,
  IN EFI_IMAGE_ID                      ImageId,
  OUT EFI_IMAGE_INPUT                  *Image
);

Parameters — Same with EFI_HII_IMAGE_PROTOCOL.GETIMAGE() .

Description

This function is similar to EFI_HII_IMAGE_PROTOCOL.GETIMAGE() . The difference is that this function will locate all EFI_HII_IMAGE_DECODER_PROTOCOL instances installed in the system if the decoder of the certain image type is not supported by the EFI_HII_IMAGE_EX_PROTOCOL. The function will attempt to decode the image to the EFI_IMAGE_INPUT using the first EFI_HII_IMAGE_DECODER_PROTOCOL instance that supports the requested image type.

Status Codes Returned — Same as EFI_HII_IMAGE_PROTOCOL.GETIMAGE() .

34.5.4. EFI_HII_IMAGE_EX_PROTOCOL.SetImageEx()

Summary

Change the information about the image. The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.SetImage() .

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_SET_IMAGE_EX)(
  IN CONST EFI_HII_IMAGE_EX_PROTOCOL      *This,
  IN EFI_HII_HANDLE                       PackageList,
  IN EFI_IMAGE_ID                         ImageId,
  IN CONST EFI_IMAGE_INPUT                *Image
);

Parameters — Same with`EFI_HII_IMAGE_PROTOCOL.SetImage()`_ .

Description

Same with EFI_HII_IMAGE_PROTOCOL.SetImage() , this protocol invokes EFI_HII_IMAGE_PROTOCOL.SetImage() implicitly.

Status Codes Returned — Same as EFI_HII_IMAGE_PROTOCOL.SetImage() .

34.5.5. EFI_HII_IMAGE_EX_PROTOCOL.DrawImageEx()

Summary

Renders an image to a bitmap or to the display. The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.DrawImageId() .

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DRAW_IMAGE_EX)(
  IN CONST EFI_HII_IMAGE_EX_PROTOCOL       *This,
  IN EFI_HII_DRAW_FLAGS                    Flags,
  IN CONST EFI_IMAGE_INPUT                 *Image,
  IN OUT EFI_IMAGE_OUTPUT                  **Blt,
  IN UINTN                                 BltX,
  IN UINTN                                 BltY
);

Parameters

Same with EFI_HII_IMAGE_PROTOCOL.DrawImageId() .

Description

Same with EFI_HII_IMAGE_PROTOCOL.DrawImage() ` this protocol invokes EFI_HII_IMAGE_PROTOCOL.DrawImage() implicitly.

Status Codes Returned — Same as EFI_HII_IMAGE_PROTOCOL.DrawImage()

34.5.6. EFI_HII_IMAGE_EX_PROTOCOL.DrawImageIdEx()

Summary

Renders an image to a bitmap or the screen containing the contents of the specified image. The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.DrawImageID()

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DRAW_IMAGE_ID_EX)(
  IN CONST EFI_HII_IMAGE_EX_PROTOCOL     *This,
  IN EFI_HII_DRAW_FLAGS                  Flags,
  IN EFI_HII_HANDLE                      PackageList,
  IN EFI_IMAGE_ID                        ImageId,
  IN OUT EFI_IMAGE_OUTPUT                **Blt,
  IN UINTN                               BltX,
  IN UINTN                               BltY
);

Parameters — Same with EFI_HII_IMAGE_PROTOCOL.DrawImageID() .

Description

This function is similar to EFI_HII_IMAGE_PROTOCOL.DrawImageID() . The difference is that this function will locate all EFI_HII_IMAGE_DECODER_PROTOCOL instances installed in the system if the decoder of the certain image type is not supported by the EFI_HII_IMAGE_EX_PROTOCOL. The function will attempt to decode the image to the EFI_IMAGE_INPUT using the first EFI_HII_IMAGE_DECODER_PROTOCOL instance that supports the requested image type.

Status Codes Returned — Same as EFI_HII_IMAGE_PROTOCOL.DrawImageID() .

34.5.7. EFI_HII_IMAGE_EX_PROTOCOL.GetImageInfo()

Summary

The function returns the information of the image. This function is differ from the EFI_HII_IMAGE_EX_PROTOCOL.GetImageEx() . This function only returns the geometry of the image instead of decoding the image to the buffer.

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_IMAGE_INFO)(
  IN CONST EFI_HII_IMAGE_EX_PROTOCOL       *This,
  IN EFI_HII_HANDLE                        PackageList,
  IN EFI_IMAGE_ID                          ImageId,
  OUT EFI_IMAGE_OUTPUT                     *Image
);

Parameters

This

EFI_HII_IMAGE_EX_PROTOCOL instance.

PackageList

The HII package list.

ImageId

The HII image ID.

Image

EFI_IMAGE_OUTPUT to retrieve the image information. Only Image.Width and Image.Height will be updated by this function. Image.Bitmap is always set to NULL.

Description

This function returns the image information to EFI_IMAGE_OUTPUT. Only the width and height are returned to the EFI_IMAGE_OUTPUT instead of decoding the image to the buffer. This function is used to get the geometry of the image. This function will try to locate all of the EFI_HII_IMAGE_DECODER_PROTOCOL installed on the system if the decoder of image type is not supported by the EFI_HII_IMAGE_EX_PROTOCOL .

Status Codes Returned

EFI_SUCCESS

The image information was returned to Image.

EFI_OUT_OF_RESOURCES

Memory allocation failed in this function.

EFI_UNSUPPORTED

The format of image is not supported.

EFI_NOT_FOUND

The image was not found in the database.

EFI_INVALID_PARAMETER

The Image was NULL or ImageId was 0.

34.6. EFI HII Image Decoder Protocol

For those HII image block types which don’t have the corresponding image decoder supported in EFI HII image EX protocol, EFI_HII_IMAGE_DECODER_PROTOCOL can be used to provide the proper image decoder. There may be more than one EFI_HII_IMAGE_DECODER_PROTOCOL instance installed in the system. Each image decoder can decode more than on HII image block types. Whether or not the HII image block type of image is supported by the certain image decoder is reported through the EFI_HII_IMAGE_DECODER_PROTOCOL. GetImageDecoderName() . Caller can invoke this function to verify the image is supported by the image decoder before sending the image raw data to the image decoder. There are two image decoder names defined in this specification: EFI_HII_IMAGE_DECODER_NAME_JPEG and EFI_HII_IMAGE_DECODER_NAME_PNG.

The image decoder protocol can publish the support for additional image decoder names other than the ones defined in this specification. This allows the image decoder to support additional image formats that are not defined by the HII image block types. In that case, callers can send the image raw data to the image decoder protocol instance to retrieve the image information or decode the image. Since the HII image block type of such images is not defined, the image may or may not be decoded by that decoder. The decoder can use the signature or data structures in the image raw data is check the format before it processes the image.

The EFI_HII_IMAGE_EX_PROTOCOL uses EFI_HII_IMAGE_DECODER_PROTOCOL as follows:

_images/HII_Protocols-3.png

Fig. 34.2 How EFI_HII_IMAGE_EX_PROTOCOL uses EFI_HII_IMAGE_DECODER_PROTOCOL

34.6.1. EFI_HII_IMAGE_DECODER_PROTOCOL.DecodeImage()

Summary

Provides the image decr for specific image file formats.

GUID

#define EFI_HII_IMAGE_DECODER_PROTOCOL_GUID \
  {0x9E66F251, 0x727C, 0x418C, \
  {0xBF, 0xD6, 0xC2, 0xB4, 0x25, 0x28, 0x18, 0xEA}}

Protocol

typedef struct _EFI_HII_IMAGE_DECODER_PROTOCOL {
  EFI_HII_IMAGE_DECODER_GET_NAME             GetImageDecoderName;
  EFI_HII_IMAGE_DECODER_GET_IMAGE_INFO       GetImageInfo;
  EFI_HII_IMAGE_DECODER_DECODE               DecodeImage;
}  EFI_HII_IMAGE_DECODER_PROTOCOL;

Members

GetImageDecodeName

The function returns the decoder name.

GetImageInfo

The function returns the image information

DecodeImage

The function decodes the image to the EFI_IMAGE_INPUT

Status Codes Returned

EFI_SUCCESS

The image information was returned to Bitmap.

EFI_UNSUPPORTED

The image decoder can’t decode this image.

EFI_OUT_OF_RESOURCE

Not enough memory to decode this image.

EFI_INVALID_PARAMETER

The Image was NULL or ImageRawDataSize was 0.

34.6.2. EFI_HII_IMAGE_DECODER_PROTOCOL.GetImageDecoderName()

Summary

This function returns the decoder name.

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_IMAGE_DECODER_GET_NAME)(
  IN CONST EFI_HII_IMAGE_DECODER_PROTOCOL      *This,
  IN OUT EFI_GUID                              **DecoderName,
  OUT UINT16                                   *NumberOfDecoderName
);

Parameters

This

EFI_HII_IMAGE_DECODER_PROTOCOL instance.

DecoderName

Pointer to a dimension to retrieve the decoder names in EFI_GUID format. The number of the decoder names is returned in NumberOfDecoderName.

NumberOfDecoderName

Pointer to retrieve the number of decoders which supported by this decoder driver.

Description

There could be more than one EFI_HII_IMAGE_DECODER_PROTOCOL instances installed in the system for different image formats. This function returns the decoder name which callers can use to find the proper image decoder for the image. It is possible to support multiple image formats in one EFI_HII_IMAGE_DECODER_PROTOCOL. The capability of the supported image formats is returned in DecoderName and NumberOfDecoderName.

Related Definitions

//******************************************
// EFI_HII_IMAGE_DECODER_NAME
//******************************************
#define EFI_HII_IMAGE_DECODER_NAME_JPEG_GUID \
{0xefefd093, 0xd9b, 0x46eb, 0xa8, \
{0x56, 0x48, 0x35,0x7, 0x0, 0xc9, 0x8}}

#define EFI_HII_IMAGE_DECODER_NAME_PNG_GUID \\

{0xaf060190, 0x5e3a, 0x4025, 0xaf, \\

{0xbd, 0xe1, 0xf9,0x5, 0xbf, 0xaa, 0x4c}}

Status Codes Returned

EFI_SUCCESS

The image decoder names were returned in DecoderName.

EFI_UNSUPPORTED

No image decoders found in this EFI_HII_IMAGE_DECODER instance.

34.6.3. EFI_HII_IMAGE_DECODER_PROTOCOL.GetImageInfo()

Summary

The function returns the EFI_HII_IMAGE_DECODER_IMAGE_INFO to the caller.

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_IMAGE_DECODER_GET_IMAGE_INFO)(
  IN CONST EFI_HII_IMAGE_DECODER_PROTOCOL    *This,
  IN VOID                                    *Image,
  IN UINTN                                   SizeOfImage,
  IN OUT EFI_HII_IMAGE_DECODER_IMAGE_INFO    **ImageInfo
);

Parameters

This

EFI_HII_IMAGE_DECODER_PROTOCOL instance.

Image

Pointer to the image raw data

SizeOfImage

Size of the entire image raw data

ImageInfo

Pointer to receive the EFI_HII_IMAGE_DECODER_IMAGE_INFO

Description

This function returns the image information of the given image raw data. This function first checks whether the image raw data is supported by this decoder or not. This function may go through the first few bytes in the image raw data for the specific data structure or the image signature. If the image is not supported by this image decoder, this function returns EFI_UNSUPPORTED to the caller. Otherwise, this function returns the proper image information to the caller. It is the caller’s responsibility to free then*ImageInfo*.

Status Codes Returned

EFI_SUCCESS

The image information was returned to ImageInfo.

EFI_UNSUPPORTED

No image decoder for the given Image or the image decoder can’t decode this image.

EFI_OUT_OF_RESOURCE

Not enough memory to decode this image for getting the image information.

EFI_INVALID_PARAMETER

The Image was NULL, SizeOfImage was 0 or the image is corrupted.

Related Definitions

//**************************************************
      // EFI_HII_IMAGE_DECODER_COLOR_TYPE
      //**************************************************
typedef enum {
  EFI_HII_IMAGE_DECODER_COLOR_TYPE_RGB = 0,
  EFI_HII_IMAGE_DECODER_COLOR_TYPE_RGBA = 1,
  EFI_HII_IMAGE_DECODER_COLOR_TYPE_CMYK = 2,
  EFI_HII_IMAGE_DECODER_COLOR_TYPE_UNKNOWN = 0xff,
}   EFI_HII_IMAGE_DECODER_COLOR_TYPE

//***************************************************
// EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER
//***************************************************
typedef struct _EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER {
  EFI_GUID                             DecoderName;
  UINT16                               ImageInfoSize;
  UINT16                               ImageWidth;
  UINT16                               ImageHeight;
  EFI_HII_IMAGE_DECODER_COLOR_TYPE     ColorType;
  UINT8                                ColorDepthInBits;
}   EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER;
DecoderName

Decoder Name

ImageInfoSize

The size of entire image information structure in bytes.

ImageWidth

The image width.

ImageHeight

The image height.

ColorType
The color type, refer to
EFI_HII_IMAGE_DECODER_COLOR_TYPE.
ColorDepthInBits

The color depth in bits.

//**************************************************
// EFI_HII_IMAGE_DECODER_JPEG_INFO
//**************************************************
typedef struct _EFI_HII_IMAGE_DECODER_JPEG_INFO {
  EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER       Header;
  UINT16                                        ScanType;
  UINT64                                        Reserved;
}   EFI_HII_IMAGE_DECODER_JPEG_INFO;
Header

EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER

ScanType
The scan type of the JPEG image
#define EFI_IMAGE_JPEG_SCANTYPE_PROGREESSIVE 0x01
#define EFI_IMAGE_JPEG_SCANTYPE_INTERLACED 0x02
Reserved

Reserved

//****************************************************
// EFI_HII_IMAGE_DECODER_PNG_INFO
//****************************************************
typedef struct _EFI_HII_IMAGE_DECODER_PNG_INFO {
  EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER    Header;
  UINT16                                     Channels;
  UINT64                                     Reserved;
}  EFI_HII_IMAGE_DECODER_PNG_INFO;
Header

EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER

Channels

Number of channels in the PNG image.

Reserved

Reserved

//****************************************************
// EFI_HII_IMAGE_DECODER_OTHER_INFO
//****************************************************
typedef struct _EFI_HII_IMAGE_DECODER_OTHER_INFO {
  EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER          Header;
  CHAR16                                           ImageExtenion[1];
  //
  // Variable length of image file extension name.
  //
}   EFI_HII_IMAGE_DECODER_OTHER_INFO;
Header

EFI_HII_IMAGE_DECODER_IMAGE_INFO_HEADER

ImageExtenion

The string of the image file extension. For example, “GIF”, “TIFF” or others.

34.6.4. EFI_HII_IMAGE_DECODER_PROTOCOL.Decode()

Summary

The function decodes the image

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_IMAGE_DECODER_DECODE)(
  IN CONST EFI_HII_IMAGE_DECODER_PROTOCOL    *This,
  IN VOID                                    *Image,
  IN UINTN                                   ImageRawDataSize,
  IN OUT EFI_IMAGE_OUTPUT                    **Bitmap,
  IN BOOLEAN                                 Transparent
);

Parameters

This

EFI_HII_IMAGE_DECODER_PROTOCOL instance.

Image

Pointer to the image raw data

ImageRawDataSize

Size of the entire image raw data

Bitmap

EFI_IMAGE_OUTPUT to receive the image or overlap the image on the original buffer.

Transparent

BOOLEAN value indicates whether the image decoder has to handle the transparent image or not.

Description

This function decodes the image which the image type of this image is supported by this EFI_HII_IMAGE_DECODER_PROTOCOL. If Bitmap is not NULL, the caller intends to put the image in the given image buffer. That allows the caller to put an image overlap on the original image. The transparency is handled by the image decoder because the transparency capability depends on the image format. Callers can set Transparent to FALSE to force disabling the transparency process on the image. Forcing Transparent to FALSE may also improve the performance of the image decoding because the image decoder can skip the transparency processing.

If Bitmap is NULL, the image decoder allocates the memory buffer for the EFI_IMAGE_OUTPUT and decodes the image to the image buffer. It is the caller’s responsibility to free the memory for EFI_IMAGE_OUTPUT. Image decoder doesn’t have to handle the transparency in this case because there is no background image given by the caller. The background color in this case is all black (#00000000).

34.7. Font Glyph Generator Protocol

The EFI HII Font glyph generator protocol generates font glyphs of the requested characters according to the given font information. This protocol is utilized by the EFI_HII_FONT_EX_PROTOCOL when the character can’t be found in the existing glyph database. That is when glyph is not found in any HII font package, EFI_HII_FONT_EX_PROTOCOL locates EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL to generate glyph block and insert glyph block into HII font package. The HII font package can be an existing HII font package or a new HII font package. This protocol can be provided by any driver that knows how to generate the glyph for a specific font family. For example, EFI application or driver may provide “Times new roman” font glyph generator driver. With this driver, platform can have “Times new roman” font supported on system.*

34.7.1. EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL

Summary

EFI HII Font glyph generator protocol generates the glyph of the character according to the given font information.

GUID

#define EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL_GUID \
  { 0xf7102853, 0x7787, 0x4dc2, 0xa8, \
    {0xa8, 0x21, 0xb5, 0xdd, 0x5, 0xc8, 0x9b }}

Protocol

typedef struct _EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL {
  EFI_GENERATE_GLYPH                GenerateGlyph;
  EFI_GENERATE_IMAGE                GenerateGlyphImage;
}  EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL;

Members

GenerateGlyph

The function generates the glyph information according to the given font information.

GenerateGlyphImage

The function generates the glyph image according to the given font information.

34.7.2. EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL.GenerateGlyph()

Summary

The function generates the glyph information according to the given font information. This function returns the glyph block in EFI_HII_GIBT_GLYPH_VARIABILITY type.

Protocol

typedef
  EFI_STATUS
  (EFIAPI *EFI_HII_GENERATE_GLYPH)(
  IN CONST EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL   *This,
  IN CHAR16                                        Char,
  IN CONST EFI_FONT_DISPLAY_INFO                   *FontInfo,
  OUT EFI_HII_GIBT_VARIABILITY_BLOCK               *GlyphBlock
);

Parameters

This

EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL instance.

Char

Character to retrieve.

FontInfo

Font display information of this character.

GlyphBlock

Pointer to retrieve the EFI_HII_GIBT_VARIABILITY_BLOCK

Description

This function generates the glyph information of the character in the specific font family. EFI_HII_GIBT_VARIABILITY_BLOCK is returned to GlyphBlock if GlyphBlock is not NULL. GlyphBlock can be called by EFI_HII_FONT_EX_PROTOCOL to retrieve the glyph information which are provided by the font family specific driver, or can be used to build up the HII font package if the HII font package with the specific font family does not exist in the HII database.

Status Codes Returned

EFI_SUCCESS

The glyph information was returned to GlyphBlock.

EFI_INVALID_PARAMETER

The FontInfo or GlyphBloc was NULL,

EFI_OUT_OF_RESOURCE

Not enough memory to generate the glyph information.

EFI_UNSUPPORTED

The font glyph generator can’t generate the glyph for the given Char. This may caused by the unsupported character, font name font style or font size.

34.7.3. EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL.GenerateGlyphImage()

Summary

The function generates the glyph image according to the given font information. This function returns EFI_GRAPHICS_OUTPUT_BLT_PIXEL points to the EFI_IMAGE_OUTPUT buffer. This function is used for glyphs which are reported in the font database as EFI_HII_GIBT_GLYPH_VARIABILITY glyph blocks.

Protocol

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GENERATE_GLYPH_IMAGE)(
  IN CONST EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL   *This,
  IN CONST EFI_HII_GLYPH_INFO                      *Cell,
  IN UINT8                                         *GlyphBuffer,
  IN CONST EFI_FONT_DISPLAY_INFO                   *FontInfo,
  IN OUT EFI_IMAGE_OUTPUT                          *Image,
  IN INT32                                         *BltX,
  IN INT32                                         *BltY,
  IN BOOLEAN                                       Transparent
);

Parameters

This

EFI_HII_FONT_GLYPH_GENERATOR_PROTOCOL instance.

Cell

Pointer to EFI_HII_GLYPH_INFO

GlyphBuffer

The buffer points to the bitmap of glyph. This pointer points to GlyphBlock.BitmapData which returned from GenerateGlyph()function

FontInfo

Font display information of this glyph.

Image

Image output buffer to retrieve the glyph image.

BltX

Together with BltY, specifies the offset from the left and top edge of the image of the first character cell in the * Image.

BltY

Together with BltX, specifies the offset from the left and top edge of the image of the first character cell in the * Image.

Transparent

If TRUE, the Background color is ignored and all”off” pixels in the character’s drawn will use the pixel value from * Image.

Description

This function generates the glyph image of the character in the specific font family on the given EFI_IMAGE_OUTPUT

Status Codes Returned

EFI_SUCCESS

The glyph image was generated in Image.

EFI_OUT_OF_RESOURCE

Not enough memory to generate image of the given glyph.

EFI_UNSUPPORTED

The font glyph generator can’t generate the glyph for the given FontInfo. This may caused by the unsupported font name, font style or font size.

EFI_INVALID_PARAMETER

One or more parameters of Cell, GlyphBuffe, FontInfo, Image, BltX or BltY was NULL.

34.8. Database Protocol

34.8.1. EFI_HII_DATABASE_PROTOCOL

Summary

Database manager for HII-related data structures.

GUID

#define EFI_HII_DATABASE_PROTOCOL_GUID \
  { 0xef9fc172, 0xa1b2, 0x4693,\
    { 0xb3, 0x27, 0x6d, 0x32, 0xfc, 0x41, 0x60, 0x42 }}

Protocol

typedef struct _EFI_HII_DATABASE_PROTOCOL {
  EFI_HII_DATABASE_NEW_PACK            NewPackageList;
  EFI_HII_DATABASE_REMOVE_PACK         RemovePackageList;
  EFI_HII_DATABASE_UPDATE_PACK         UpdatePackageList;
  EFI_HII_DATABASE_LIST_PACKS          ListPackageLists;
  EFI_HII_DATABASE_EXPORT_PACKS        ExportPackageLists;
  EFI_HII_DATABASE_REGISTER_NOTIFY     RegisterPackageNotify;
  EFI_HII_DATABASE_UNREGISTER_NOTIFY   UnregisterPackageNotify;
  EFI_HII_FIND_KEYBOARD_LAYOUTS        FindKeyboardLayouts;
  EFI_HII_GET_KEYBOARD_LAYOUT          GetKeyboardLayout;
  EFI_HII_SET_KEYBOARD_LAYOUT          SetKeyboardLayout;
  EFI_HII_DATABASE_GET_PACK_HANDLE     GetPackageListHandle;
}   EFI_HII_DATABASE_PROTOCOL;

Members

NewPackageList

Add a new package list to the HII database.

RemovePackageList

Remove a package list from the HII database.

UpdatePackageList

Update a package list in the HII database.

ListPackageLists

List the handles of the package lists within the HII database.

ExportPackageLists

Export package lists from the HII database.

RegisterPackageNotify

Register notification when packages of a certain type are installed.

UnregisterPackageNotify

Unregister notification of packages.

FindKeyboardLayouts

Retrieves a list of the keyboard layouts in the system.

GetKeyboardLayout

Allows a program to extract the current keyboard layout. See the GetKeyboardLayout() function description.

SetKeyboardLayout

Changes the current keyboard layout. See the SetKeyboardLayout() function description.

GetPackageListHandle

Return the EFI handle associated with a given package list.

34.8.2. EFI_HII_DATABASE_PROTOCOL.NewPackageList()

Summary

Adds the packages in the package list to the HII database.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DATABASE_NEW_PACK) (
  IN CONST EFI_HII_DATABASE_PROTOCOL         *This,
  IN CONST EFI_HII_PACKAGE_LIST_HEADER       *PackageList,
  IN CONST EFI_HANDLE                        DriverHandle, OPTIONAL
  OUT EFI_HII_HANDLE                         *Handle
  );

Parameters

This

A pointer to the EFI_HII_DATABASE_PROTOCOL instance.

PackageList

A pointer to an EFI_HII_PACKAGE_LIST_HEADER structure.

DriverHandle

Associate the package list with this EFI handle

Handle

A pointer to the EFI_HII_HANDLE instance. Type EFI_HII_HANDLE is defined in “Related Definitions” below.

Description

This function adds the packages in the package list to the database and returns a handle. If there is a EFI_DEVICE_PATH_PROTOCOL associated with the DriverHandle, then this function will create a package of type EFI_PACKAGE_TYPE_DEVICE_PATH and add it to the package list.

For each package in the package list, registered functions with the notification type NEW_PACK and having the same package type will be called.

For each call to NewPackageList(), there should be a corresponding call to EFI_HII_DATABASE_PROTOCOL.RemovePackageList() .

Related Definitions

typedef void *EFI_HII_HANDLE:

Status Codes Returns

EFI_SUCCESS

The package list associated with the Handle was added to the HII database.

EFI_OUT_OF_RESOURCES

Unable to allocate necessary resources for the new database contents.

EFI_INVALID_PARAMETER

PackageList is NULL or Handle is NULL.

34.8.3. EFI_HII_DATABASE_PROTOCOL.RemovePackageList()

Summary

Removes a package list from the HII database.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DATABASE_REMOVE_PACK) (
  IN CONST EFI_HII_DATABASE_PROTOCOL         *This,
  IN EFI_HII_HANDLE                          Handle
  );

Parameters

This

A pointer to the EFI_HII_DATABASE_PROTOCOL instance.

Handle

The handle that was registered to the data that is requested for removal. Type EFI_HII_HANDLE is defined in EFI_HII_DATABASE_PROTOCOL.NewPackageList() in the Packages section.

Description

This function removes the package list that is associated with a handle Handle from the HII database. Before removing the package, any registered functions with the notification type REMOVE_PACK and the same package type will be called.

For each call to EFI_HII_DATABASE_PROTOCOL.NewPackageList() , there should be a corresponding call to RemovePackageList.

Status Codes Returned

EFI_SUCCESS

The data associated with the Handle was removed from the HII database.

EFI_NOT_FOUND

The specified Handle is not in the Database.

34.8.4. EFI_HII_DATABASE_PROTOCOL.UpdatePackageList()

Summary

Update a package list in the HII database.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DATABASE_UPDATE_PACK) (
  IN CONST EFI_HII_DATABASE_PROTOCOL            *This,
  IN EFI_HII_HANDLE                             Handle,
  IN CONST EFI_HII_PACKAGE_LIST_HEADER          *PackageList,
  );

Parameters

This

A pointer to the EFI_HII_DATABASE_PROTOCOL instance.

Handle

The handle that was registered to the data that is requested to be updated. Type EFI_HII_HANDLE is defined in EFI_HII_DATABASE_PROTOCOL.NewPackageList() in the Packages section.

PackageList

A pointer to an instance of EFI_HII_PACKAGE_LIST_HEADER.

Description

This function updates the existing package list (which has the specified Handle ) in the HII databases, using the new package list specified by PackageList. The update process has the following steps:

Collect all the package types in the package list specified by PackageList. A package type consists of the Type field of EFI_HII_PACKAGE_HEADER and, if the Type is EFI_HII_PACKAGE_TYPE_GUID, the Guid field, as defined in EFI_HII_GUID_PACKAGE_HDR.

Iterate through the packages within the existing package list in the HII database specified by Handle. If a package’s type matches one of the types collected in step 1, then perform the following steps:

  • Call any functions registered with the notification type REMOVE_PACK.

  • Remove the package from the package list and the HII database.

Add all of the packages within the new package list specified by PackageList, using the following steps:

  • Add the package to the package list and the HII database.

  • Call any functions registered with the notification type ADD_PACK.

Status Codes Returned

EFI_SUCCESS

The HII database was successfully updated.

EFI_OUT_OF_RESOURCES

Unable to allocate enough memory for the updated database.

EFI_INVALID_PARAMETER

PackageList was NULL.

EFI_NOT_FOUND

The specified Handle is not in the Database.

34.8.5. EFI_HII_DATABASE_PROTOCOL.ListPackageLists()

Summary

Determines the handles that are currently active in the database.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DATABASE_LIST_PACKS) (
  IN CONST EFI_HII_DATABASE_PROTOCOL      *This,
  IN UINT8                                PackageType,
  IN CONST EFI_GUID                       *PackageGuid,
  IN OUT UINTN                            *HandleBufferLength,
  OUT EFI_HII_HANDLE                      *Handle
  );

Parameters

This

A pointer to the EFI_HII_DATABASE_PROTOCOL instance.

PackageType

Specifies the package type of the packages to list or EFI_HII_PACKAGE_TYPE_ALL for all packages to be listed.

PackageGuid

If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then this is the pointer to the GUID which must match the Guid field of EFI_HII_GUID_PACKAGE_HDR. Otherwise, it must be NULL.

HandleBufferLength

On input, a pointer to the length of the handle buffer. On output, the length of the handle buffer that is required for the handles found.

Handle

An array of EFI_HII_HANDLE instances returned. Type EFI_HII_HANDLE is defined in EFI_HII_DATABASE_PROTOCOL.NewPackageList() in the Packages section.

Description

This function returns a list of the package handles of the specified type that are currently active in the database. The pseudo-type EFI_HII_PACKAGE_TYPE_ALL will cause all package handles to be listed.

Status Codes Returned

EFI_SUCCESS

A list of Packages was placed in Handle successfully. HandleBufferLength is updated with the actual length.

EFI_BUFFER_TOO_SMALL

The HandleBufferLength parameter indicates that Handle is too small to support the number of handles. HandleBufferLength is updated with a value that will enable the data to fit.

EFI_INVALID_PARAMETER

HandleBufferLength was NULL.

EFI_INVALID_PARAMETER

The value referenced by HandleBufferLength was not zero and Handle was NULL.

EFI_INVALID_PARAMETER

PackageType is a EFI_HII_PACKAGE_TYPE_GUID but PackageGuid is not NULL.

EFI_INVALID_PARAMETER

PackageType is a EFI_HII_PACKAGE_TYPE_GUID but PackageGuid is NULL.

EFI_NOT_FOUND

No matching handles were found

34.8.6. EFI_HII_DATABASE_PROTOCOL.ExportPackageLists()

Summary

Exports the contents of one or all package lists in the HII database into a buffer.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DATABASE_EXPORT_PACKS) (
  IN CONST EFI_HII_DATABASE_PROTOCOL      *This,
  IN EFI_HII_HANDLE                       Handle,
  IN OUT UINTN                            *BufferSize,
  OUT EFI_HII_PACKAGE_LIST_HEADER         *Buffer
  );

Parameters

This

A pointer to the EFI_HII_DATABASE_PROTOCOL instance.

Handle

An EFI_HII_HANDLE that corresponds to the desired package list in the HII database to export or NULL to indicate all package lists should be exported.

BufferSize

On input, a pointer to the length of the buffer. On output, the length of the buffer that is required for the exported data.

Buffer

A pointer to a buffer that will contain the results of the export function.

Description

This function will export one or all package lists in the database to a buffer. For each package list exported, this function will call functions registered with EXPORT_PACK and then copy the package list to the buffer. The registered functions may call EFI_HII_DATABASE_PROTOCOL.UpdatePackageList() to modify the package list before it is copied to the buffer.

If the specified BufferSize is too small, then the status EFI_BUFFER_TOO_SMALL will be returned and the actual package size will be returned in BufferSize.

Status Codes Returned

EFI_SUCCESS

Package exported.

EFI_BUFFER_TOO_SMALL

BufferSize is too small to hold the package.

EFI_INVALID_PARAMETER

BufferSize was NULL

EFI_INVALID_PARAMETER

The value referenced by BufferSize was not zero and Buffer was NULL.

EFI_NOT_FOUND

The specified Handle could not be found in the current database.

34.8.7. EFI_HII_DATABASE_PROTOCOL.RegisterPackageNotify()

Summary

Registers a notification function for HII database-related events.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DATABASE_REGISTER_NOTIFY) (
  IN CONST EFI_HII_DATABASE_PROTOCOL         *This,
  IN UINT8                                   PackageType,
  IN CONST EFI_GUID                          *PackageGuid,
  IN CONST EFI_HII_DATABASE_NOTIFY           PackageNotifyFn,
  IN EFI_HII_DATABASE_NOTIFY_TYPE            NotifyType,
  OUT EFI_HANDLE                             *NotifyHandle
  );

Parameters

This

A pointer to the EFI_HII_DATABASE_PROTOCOL instance.

PackageType

The package type. See EFI_HII_PACKAGE_TYPE_x in EFI_HII_PACKAGE_HEADER.

PackageGuid

If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then this is the pointer to the GUID which must match the Guid field of EFI_HII_GUID_PACKAGE_HDR. Otherwise, it must be NULL.

PackageNotifyFn

Points to the function to be called when the event specified by NotificationType occurs. See ` .

NotifyType

Describes the types of notification which this function will be receiving. See EFI_HII_DATABASE_NOTIFY for more a list of types.

NotifyHandle

Points to the unique handle assigned to the registered notification. Can be used in EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() to stop notifications.

Description

This function registers a function which will be called when specified actions related to packages of the specified type occur in the HII database. By registering a function, other HII-related drivers are notified when specific package types are added, removed or updated in the HII database.

Each driver or application which registers a notification should use EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify() before exiting.

If a driver registers a NULL PackageGuid when PackageType is EFI_HII_PACKAGE_TYPE_GUID, a notification will occur for every package of type EFI_HII_PACKAGE_TYPE_GUID that is registered.

Related Definitions

EFI_HII_PACKAGE_HEADER is defined in EFI_HII_PACKAGE_HEADER .

EFI_HII_DATABASE_NOTIFY is defined in EFI_HII_DATABASE_NOTIFY .

EIF_HII_DATABASE_NOTIFY_TYPE is defined in EFI_HII_DATABASE_NOTIFY_TYPE .

Returned Status Codes

EFI_SUCCESS

Notification registered successfully.

EFI_OUT_OF_RESOURCES

Unable to allocate necessary data structures.

EFI_INVALID_PARAMETER

NotifyHandle is NULL.

EFI_INVALID_PARAMETER

PackageType is not an EFI_HII_PACKAGE_TYPE_GUID but PackageGuid is not NULL.

EFI_INVALID_PARAMETER

PackageType is a EFI_HII_PACKAGE_TYPE_GUID but PackageGuid is NULL

34.8.8. EFI_HII_DATABASE_PROTOCOL.UnregisterPackageNotify()

Summary

Removes the specified HII database package-related notification.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DATABASE_UNREGISTER_NOTIFY) (
  IN CONST EFI_HII_DATABASE_PROTOCOL         *This,
  IN EFI_HANDLE                              NotificationHandle
  );

Parameters

This

A pointer to the EFI_HII_DATABASE_PROTOCOL instance.

NotificationHandle

The handle of the notification function being unregistered.

Returned Status Codes

EFI_SUCCESS

Invalidated

EFI_NOT_FOUND

The NotificationHandle could not be found in the database.

34.8.9. EFI_HII_DATABASE_PROTOCOL.FindKeyboardLayouts()

Summary

Retrieves a list of the keyboard layouts in the system.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_FIND_KEYBOARD_LAYOUTS) (
  IN CONST EFI_HII_DATABASE_PROTOCOL      *This,
  IN OUT UINT16                           *KeyGuidBufferLength,
  OUT EFI_GUID                            *KeyGuidBuffer
  );

Parameters

This

A pointer to the EFI_HII_DATABASE_PROTOCOL instance.

KeyGuidBufferLength

On input, a pointer to the length of the keyboard GUID buffer. On output, the length of the handle buffer that is required for the handles found.

KeyGuidBuffer

An array of keyboard layout GUID instances returned.

Description

This routine retrieves an array of GUID values for each keyboard layout that was previously registered in the system.

Status Codes Returned

EFI_SUCCESS

KeyGuidBuffer was updated successfully.

EFI_BUFFER_TOO_SMALL

The KeyGuidBufferLength parameter indicates that KeyGuidBuffer is too small to support the number of GUIDs. KeyGuidBufferLength is updated with a value that will enable the data to fit.

EFI_INVALID_PARAMETER

KeyGuidBufferLength is NULL.

EFI_INVALID_PARAMETER

The value referenced by KeyGuidBufferLength is not zero and KeyGuidBuffer is NULL.

34.8.10. EFI_HII_DATABASE_PROTOCOL.GetKeyboardLayout()

Summary

Retrieves the requested keyboard layout.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT) (
  IN CONST EFI_HII_DATABASE_PROTOCOL   *This,
  IN EFI_GUID                          *KeyGuid,
  IN OUT UINIT16                       *KeyboardLayoutLength,
  OUT EFI_HII_KEYBOARD_LAYOUT          *KeyboardLayout
  );

Parameters

This

A pointer to the EFI_HII_DATABASE_PROTOCOL instance.

KeyGuid

A pointer to the unique ID associated with a given keyboard layout. If KeyGuid is NULL then the current layout will be retrieved.

KeyboardLayout

A pointer to a buffer containing the retrieved keyboard layout. below.

KeyboardLayoutLength

On input, a pointer to the length of the KeyboardLayout buffer. On output, the length of the data placed into KeyboardLayout.

Description

This routine retrieves the requested keyboard layout. The layout is a physical description of the keys on a keyboard and the character(s) that are associated with a particular set of key strokes.

Related Definitions

//**********************************************
// EFI_HII_KEYBOARD_LAYOUT
//**********************************************
typedef struct {
  UINT16                   LayoutLength;
  EFI_GUID                 Guid;
  UINT32                   LayoutDescriptorStringOffset;
  UINT8                    DescriptorCount;
  EFI_KEY_DESCRIPTOR       Descriptors[];
}   EFI_HII_KEYBOARD_LAYOUT;
LayoutLength

The length of the current keyboard layout.

Guid

The unique ID associated with this keyboard layout.

LayoutDescriptorStringOffset

An offset location (0 is the beginning of the EFI_KEYBOARD_LAYOUT instance) of the string which describes this keyboard layout. The data that is being referenced is in EFI_DESCRIPTION_STRING_BUNDLE format.

DescriptorCount

The number of Descriptor entries in this layout.

Descriptors

An array of key descriptors.

//***************************************************
// EFI_DESCRIPTION_STRING - byte packed data
//***************************************************
CHAR16         Language[];
CHAR16         Space;
//CHAR16       DescriptionString[];
Language

The language in RFC 4646 format to associate with DescriptionString.

Space

A space (U-0x0020) character to force as a separator between the Language field and the formal description string.

DescriptionString

A null-terminated description string.

//***************************************************
// EFI_DESCRIPTION_STRING_BUNDLE - byte packed data
//
// Example: 2en-US English Keyboard<null>es-ES Keyboard en    ingles<null>
// <null> = U-0000
//***************************************************
UINT16                        DescriptionCount;
EFI_DESCRIPTION_STRING        DescriptionString[];
DescriptionCount

The number of description strings.

DescriptionString

An array of language-specific description strings.

//***************************************************
// EFI_KEY_DESCRIPTOR
//***************************************************
typedef struct {
  EFI_KEY               Key;
  CHAR16                Unicode;
  CHAR16                ShiftedUnicode;
  CHAR16                AltGrUnicode;
  CHAR16                ShiftedAltGrUnicode;
  UINT16                Modifier;
  UINT16                AffectedAttribute;
}   EFI_KEY_DESCRIPTOR;

// A key which is affected by all the standard shift    modifiers.
// Most keys would be expected to have this bit active.
#define EFI_AFFECTED_BY_STANDARD_SHIFT    0x0001

// This key is affected by the caps lock so that if a keyboard
// driver would need to disambiguate between a key which had a
// "1" defined versus a "a" character. Having this bit turned on
// would tell the keyboard driver to use the appropriate    shifted // state or not.
#define EFI_AFFECTED_BY_CAPS_LOCK         0x0002

// Similar to the case of CAPS lock, if this bit is active, the
// key is affected by the num lock being turned on.
#define EFI_AFFECTED_BY_NUM_LOCK 0x0004
Key

Used to describe a physical key on a keyboard. Type EFI_KEY is defined below.

Unicode

Unicode character code for the Key.

ShiftedUnicode

Unicode character code for the key with the shift key being held down.

AltGrUnicode

Unicode character code for the key with the Alt-GR being held down.

ShiftedAltGrUnicode

Unicode character code for the key with the Alt-GR and shift keys being held down.

Modifier

Modifier keys are defined to allow for special functionality that is not necessarily accomplished by a printable character. Many of these modifier keys are flags to toggle certain state bits on and off inside of a keyboard driver. Values for Modifier are defined below.

//***************************************************
// EFI_KEY
//***************************************************
typedef enum {
  EfiKeyLCtrl, EfiKeyA0, EfiKeyLAlt, EfiKeySpaceBar, EfiKeyA2,
  EfiKeyA3, EfiKeyA4, EfiKeyRCtrl, EfiKeyLeftArrow,
  EfiKeyDownArrow, EfiKeyRightArrow, EfiKeyZero, EfiKeyPeriod,
  EfiKeyEnter, EfiKeyLShift, EfiKeyB0, EfiKeyB1, EfiKeyB2,
  EfiKeyB3, EfiKeyB4, EfiKeyB5, EfiKeyB6, EfiKeyB7, EfiKeyB8,
  EfiKeyB9, EfiKeyB10, EfiKeyRShift, EfiKeyUpArrow, EfiKeyOne,
  EfiKeyTwo, EfiKeyThree, EfiKeyCapsLock, EfiKeyC1, EfiKeyC2,
  EfiKeyC3, EfiKeyC4, EfiKeyC5, EfiKeyC6, EfiKeyC7, EfiKeyC8,
  EfiKeyC9, EfiKeyC10, EfiKeyC11, EfiKeyC12, EfiKeyFour,
  EfiKeyFive, EfiKeySix, EfiKeyPlus, EfiKeyTab, EfiKeyD1,
  EfiKeyD2, EfiKeyD3, EfiKeyD4, EfiKeyD5, EfiKeyD6, EfiKeyD7,
  EfiKeyD8, EfiKeyD9, EfiKeyD10, EfiKeyD11, EfiKeyD12, EfiKeyD13,
  EfiKeyDel, EfiKeyEnd, EfiKeyPgDn, EfiKeySeven, EfiKeyEight,
  EfiKeyNine, EfiKeyE0, EfiKeyE1, EfiKeyE2, EfiKeyE3, EfiKeyE4,
  EfiKeyE5, EfiKeyE6, EfiKeyE7, EfiKeyE8, EfiKeyE9, EfiKeyE10,
  EfiKeyE11, EfiKeyE12, EfiKeyBackSpace, EfiKeyIns, EfiKeyHome,
  EfiKeyPgUp, EfiKeyNLck, EfiKeySlash, EfiKeyAsterisk,
  EfiKeyMinus, EfiKeyEsc, EfiKeyF1, EfiKeyF2, EfiKeyF3, EfiKeyF4,
  EfiKeyF5, EfiKeyF6, EfiKeyF7, EfiKeyF8, EfiKeyF9, EfiKeyF10,
  EfiKeyF11, EfiKeyF12, EfiKeyPrint, EfiKeySLck, EfiKeyPause,
  EfiKeyIntl0, EfiKeyIntl1, EfiKeyIntl2, EfiKeyIntl3,
  EfiKeyIntl4, EfiKeyIntl5, EfiKeyIntl6, EfiKeyIntl7,
  EfiKeyIntl8, EfiKeyIntl9
} EFI_KEY;

See the figure below for which key corresponds to the values in the enumeration above. For example, EfiKeyLCtrl corresponds to the left control key in the lower-left corner of the keyboard, EfiKeyFour corresponds to the 4 key on the numeric keypad, and EfiKeySLck corresponds to the Scroll Lock key in the upper-right corner of the keyboard.

_images/HII_Protocols-4.png

Fig. 34.3 Keyboard Layout

//***************************************************
// Modifier values
//***************************************************
#define EFI_NULL_MODIFIER                 0x0000
#define EFI_LEFT_CONTROL_MODIFIER         0x0001
#define EFI_RIGHT_CONTROL_MODIFIER        0x0002
#define EFI_LEFT_ALT_MODIFIER             0x0003
#define EFI_RIGHT_ALT_MODIFIER            0x0004
#define EFI_ALT_GR_MODIFIER               0x0005
#define EFI_INSERT_MODIFIER               0x0006
#define EFI_DELETE_MODIFIER               0x0007
#define EFI_PAGE_DOWN_MODIFIER            0x0008
#define EFI_PAGE_UP_MODIFIER              0x0009
#define EFI_HOME_MODIFIER                 0x000A
#define EFI_END_MODIFIER                  0x000B
#define EFI_LEFT_SHIFT_MODIFIER           0x000C
#define EFI_RIGHT_SHIFT_MODIFIER          0x000D
#define EFI_CAPS_LOCK_MODIFIER            0x000E
#define EFI_NUM_LOCK_MODIFIER             0x000F
#define EFI_LEFT_ARROW_MODIFIER           0x0010
#define EFI_RIGHT_ARROW_MODIFIER          0x0011
#define EFI_DOWN_ARROW_MODIFIER           0x0012
#define EFI_UP_ARROW_MODIFIER             0x0013
#define EFI_NS_KEY_MODIFIER               0x0014
#define EFI_NS_KEY_DEPENDENCY_MODIFIER    0x0015
#define EFI_FUNCTION_KEY_ONE_MODIFIER     0x0016
#define EFI_FUNCTION_KEY_TWO_MODIFIER     0x0017
#define EFI_FUNCTION_KEY_THREE_MODIFIER   0x0018
#define EFI_FUNCTION_KEY_FOUR_MODIFIER    0x0019
#define EFI_FUNCTION_KEY_FIVE_MODIFIER    0x001A
#define EFI_FUNCTION_KEY_SIX_MODIFIER     0x001B
#define EFI_FUNCTION_KEY_SEVEN_MODIFIER   0x001C
#define EFI_FUNCTION_KEY_EIGHT_MODIFIER   0x001D
#define EFI_FUNCTION_KEY_NINE_MODIFIER    0x001E
#define EFI_FUNCTION_KEY_TEN_MODIFIER     0x001F
#define EFI_FUNCTION_KEY_ELEVEN_MODIFIER  0x0020
#define EFI_FUNCTION_KEY_TWELVE_MODIFIER  0x0021
//
// Keys that have multiple control functions based on modifier
// settings are handled in the keyboard driver implementation.
// For instance PRINT_KEY might have a modifier held down and
// is still a nonprinting character, but might have an alternate
// control function like SYSREQUEST
//
#define EFI_PRINT_MODIFIER                0x0022
#define EFI_SYS_REQUEST_MODIFIER          0x0023
#define EFI_SCROLL_LOCK_MODIFIER          0x0024
#define EFI_PAUSE_MODIFIER                0x0025
#define EFI_BREAK_MODIFIER                0x0026
#define EFI_LEFT_LOGO_MODIFIER            0x0027
#define EFI_RIGHT_LOGO_MODIFIER           0x0028
#define EFI_MENU_MODIFIER                 0x0029

Status Codes Returned

EFI_SUCCESS

The keyboard layout was retrieved successfully.

EFI_NOT_FOUND

The requested keyboard layout was not found.

EFI_BUFFER_TOO_SMALL

The KeyboardLayoutLength parameter indicates the KeyboardLayout is too small to hold the keyboard layout.

EFI_INVALID_PARAMETER

KeyboardLayoutLength is NULL

EFI_INVALID_PARAMETER

The value referenced by KeyboardLayoutLength is not zero and KeyboardLayout is NULL.

34.8.11. EFI_HII_DATABASE_PROTOCOL.SetKeyboardLayout()

Summary

Sets the currently active keyboard layout.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_SET_KEYBOARD_LAYOUT) (
  IN CONST EFI_HII_DATABASE_PROTOCOL      *This,
  IN EFI_GUID                             *KeyGuid
  );

Parameters

This

A pointer to the EFI_HII_DATABASE_PROTOCOL instance.

KeyGuid

A pointer to the unique ID associated with a given keyboard layout.

Description

This routine sets the default keyboard layout to the one referenced by KeyGuid. When this routine is called, an event will be signaled of the EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID group type. This is so that agents which are sensitive to the current keyboard layout being changed can be notified of this change.

Related Definitions

GUID

#define EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID \
  { 0x14982a4f, 0xb0ed, 0x45b8, \
    { 0xa8, 0x11, 0x5a, 0x7a, 0x9b, 0xc2, 0x32, 0xdf }}

Status Codes Returned

EFI_SUCCESS

The current keyboard layout was successfully set.

EFI_NOT_FOUND

The referenced keyboard layout was not found, so action was taken.

EFI_INVALID_PARAMETER

KeyGuid is NULL.

34.8.12. EFI_HII_DATABASE_PROTOCOL.GetPackageListHandle()

Summary

Return the EFI handle associated with a package list.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DATABASE_GET_PACK_HANDLE) (
  IN CONST EFI_HII_DATABASE_PROTOCOL      *This,
  IN EFI_HII_HANDLE                       PackageListHandle,
  OUT EFI_HANDLE                          *DriverHandle
  );

Parameters

This

A pointer to the EFI_HII_DATABASE_PROTOCOL instance.

PackageListHandle

An EFI_HII_HANDLE that corresponds to the desired package list in the HIIdatabase.

DriverHandle

On return, contains the EFI_HANDLE which was registered with the package list in NewPackageList().

Status Codes Returned

EFI_SUCCESS

The DriverHandle was returned successfully.

EFI_INVALID_PARAMETER

The PackageListHandle was not valid.

EFI_INVALID_PARAMETER

The DriverHandle must not be NULL.

34.8.13. Database Structures

34.8.13.1. EFI_HII_DATABASE_NOTIFY

Summary

Handle a registered notification for a package change to the database.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_HII_DATABASE_NOTIFY) (
  IN UINT8                          PackageType,
  IN CONST EFI_GUID                 *PackageGuid,
  IN CONST EFI_HII_PACKAGE_HEADER   *Package,
  IN EFI_HII_HANDLE                 Handle,
  IN EFI_HII_DATABASE_NOTIFY_TYPE   NotifyType
  );

Parameters

PackageType

Package type of the notification.

PackageGuid

If PackageType is EFI_HII_PACKAGE_TYPE_GUID, then this is the pointer to the GUID from the Guid field of EFI_HII_GUID_PACKAGE_HDR. Otherwise, it must be NULL.

Package

Points to the package referred to by the notification

Handle

The handle of the package list which contains the specified package.

NotifyType

The type of change concerning the database. See EFI_HII_DATABASE_NOTIFY_TYPE .

Description

Functions which are registered to receive notification of database events have this prototype. The actual event is encoded in NotifyType. The following table describes how PackageType, PackageGuid, Handle, and Package are used for each of the notification types.

Notification Type

Parameter Description

NEW_PACK

PackageType and PackageGuid are the type of the new package. Package points to the new package. Handle is the handle of the package list which is being added to the database.

REMOVE_PACK

PackageType and PackageGuid are the type of the package which is being removed. Package points to the package being removed. Handle is the package list from which the package is being removed.

EXPORT_PACK

PackageType and PackageGuid are the type of the package being exported. Package points to the existing package in the database. Handle is the package list being exported.

ADD_PACK

PackageType and PackageGuid are the type of the package being added. Package points to the package being added. Handle is the package list to which the package is being added.

34.8.14. EFI_HII_DATABASE_NOTIFY_TYPE

typedef UINTN EFI_HII_DATABASE_NOTIFY_TYPE;

#define EFI_HII_DATABASE_NOTIFY_NEW_PACK      0x00000001
#define EFI_HII_DATABASE_NOTIFY_REMOVE_PACK   0x00000002
#define EFI_HII_DATABASE_NOTIFY_EXPORT_PACK   0x00000004
#define EFI_HII_DATABASE_NOTIFY_ADD_PACK      0x00000008