EFI COMPONENT NAME2 PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Used to retrieve user readable names of drivers and controllers managed by UEFI Drivers.

Contents

GUID

#define EFI_COMPONENT_NAME2_PROTOCOL_GUID \
  {0x6a7a5cff, 0xe8d9, 0x4f70, 0xba, 0xda, 0x75, 0xab, 0x30, 0x25, 0xce, 0x14}

=Protocol Interface Structur

typedef struct _EFI_COMPONENT_NAME2_PROTOCOL {
  EFI_COMPONENT_NAME_GET_DRIVER_NAME     GetDriverName;
  EFI_COMPONENT_NAME_GET_CONTROLLER_NAME GetControllerName;
  CHAR8                                  *SupportedLanguages;
} EFI_COMPONENT_NAME2_PROTOCOL;

Parameters

Parameter Description
GetDriverName Retrieves a Unicode string that is the user readable name of the driver.
GetControllerName Retrieves a Unicode string that is the user readable name of a controller that is being managed by a driver.
SupportedLanguages A Null-terminated ASCII string array that contains one or more supported language codes. This is the list of language codes that this protocol supports. The number of languages supported by a driver is up to the driver writer. SupportedLanguages is specified in RFC 4646 format.

Description

The EFI_COMPONENT_NAME2_PROTOCOL is used retrieve a driver's user readable name and the names of all the controllers that a driver is managing from the driver's point of view. Each of these names is returned as a Null-terminated Unicode string. The caller is required to specify the language in which the Unicode string is returned, and this language must be present in the list of languages that this protocol supports specified by SupportedLanguages.

GetDriverName()

Retrieves a string that is the user readable name of the driver.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_COMPONENT_NAME_GET_DRIVER_NAME) (
  IN  EFI_COMPONENT_NAME2_PROTOCOL *This,
  IN  CHAR8                        *Language,
  OUT CHAR16                       **DriverName
  );

Parameters

Parameter Description
This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL instance.
Language A pointer to a Null-terminated ASCII string array indicating the language. This is the language of the driver name that the caller is requesting, and it must match one of the languages specified in SupportedLanguages. The number of languages supported by a driver is up to the driver writer. Language is specified in RFC 4646 language code format.
DriverName A pointer to the Unicode string to return. This Unicode string is the name of the driver specified by This in the language specified by Language.

Description
This function retrieves the user readable name of a driver in the form of a Unicode string. If the driver specified by This has a user readable name in the language specified by Language, then a pointer to the driver name is returned in DriverName, and EFI_SUCCESS is returned. If the driver specified by This does not support the language specified by Language, then EFI_UNSUPPORTED is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The string for the user readable name in the language specified by Language for the driver specified by This was returned in DriverName.
EFI_INVALID_PARAMETER Language is NULL.
EFI_INVALID_PARAMETER DriverName is NULL.
EFI_UNSUPPORTED The driver specified by This does not support the language specified by Language.

GetControllerName()

Retrieves a string that is the user readable name of the controller that is being managed by a driver.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_COMPONENT_NAME_GET_CONTROLLER_NAME) (
  IN  EFI_COMPONENT_NAME2_PROTOCOL *This,
  IN  EFI_HANDLE                   ControllerHandle,
  IN  EFI_HANDLE                   ChildHandle OPTIONAL,
  IN  CHAR8                        *Language,
  OUT CHAR16                       **ControllerName
  );

Parameters

Parameter Description
This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL instance.
ControllerHandle The handle of a controller that the driver specified by This is managing. This handle specifies the controller whose name is to be returned.
ChildHandle The handle of the child controller to retrieve the name of. This is an optional parameter that may be NULL. It will be NULL for device drivers. It will also be NULL for bus drivers that attempt to retrieve the name of the bus controller. It will not be NULL for a bus driver that attempts to retrieve the name of a child controller.
Language A pointer to a Null- terminated ASCII string array indicating the language. This is the language of the controller name that the caller is requesting, and it must match one of the languages specified in SupportedLanguages. The number of languages supported by a driver is up to the driver writer. Language is specified in RFC 4646 language code format.
ControllerName A pointer to the string to return. This Unicode string is the name of the controller specified by ControllerHandle and ChildHandle in the language specified by Language from the point of view of the driver specified by This.

Description
This function retrieves the user readable name of the controller specified by ControllerHandle and ChildHandle in the form of a Unicode string. If the driver specified by This has a user readable name in the language specified by Language, then a pointer to the controller name is returned in ControllerName, and EFI_SUCCESS is returned.

If the driver specified by This is not currently managing the controller specified by ControllerHandle and ChildHandle, then EFI_UNSUPPORTED is returned.

If the driver specified by This does not support the language specified by Language, then EFI_UNSUPPORTED is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The string for the user readable name specified by This, ControllerHandle, ChildHandle, and Language was returned in ControllerName.
EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER The driver specified by This is not a device driver, and ChildHandle is not NULL, and ChildHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER Language is NULL.
EFI_INVALID_PARAMETER ControllerName is NULL.
EFI_UNSUPPORTED The driver specified by This is a device driver and ChildHandle is not NULL.
EFI_UNSUPPORTED The driver specified by This is not currently managing the controller specified by ControllerHandle and ChildHandle.
EFI_UNSUPPORTED The driver specified by This does not support the language specified by Language.

Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools