iPXE
ComponentName2.h
Go to the documentation of this file.
00001 /** @file
00002   UEFI Component Name 2 Protocol as defined in the UEFI 2.1 specification.
00003   This protocol is used to retrieve user readable names of drivers
00004   and controllers managed by UEFI Drivers.
00005 
00006   Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
00007   This program and the accompanying materials
00008   are licensed and made available under the terms and conditions of the BSD License
00009   which accompanies this distribution.  The full text of the license may be found at
00010   http://opensource.org/licenses/bsd-license.php
00011 
00012   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00013   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00014 
00015 **/
00016 
00017 #ifndef __EFI_COMPONENT_NAME2_H__
00018 #define __EFI_COMPONENT_NAME2_H__
00019 
00020 FILE_LICENCE ( BSD3 );
00021 
00022 ///
00023 /// Global ID for the Component Name Protocol
00024 ///
00025 #define EFI_COMPONENT_NAME2_PROTOCOL_GUID \
00026   {0x6a7a5cff, 0xe8d9, 0x4f70, { 0xba, 0xda, 0x75, 0xab, 0x30, 0x25, 0xce, 0x14 } }
00027 
00028 typedef struct _EFI_COMPONENT_NAME2_PROTOCOL  EFI_COMPONENT_NAME2_PROTOCOL;
00029 
00030 
00031 /**
00032   Retrieves a string that is the user readable name of
00033   the EFI Driver.
00034 
00035   @param  This       A pointer to the
00036                      EFI_COMPONENT_NAME2_PROTOCOL instance.
00037 
00038   @param  Language   A pointer to a Null-terminated ASCII string
00039                      array indicating the language. This is the
00040                      language of the driver name that the caller
00041                      is requesting, and it must match one of the
00042                      languages specified in SupportedLanguages.
00043                      The number of languages supported by a
00044                      driver is up to the driver writer. Language
00045                      is specified in RFC 4646 language code
00046                      format.
00047 
00048   @param  DriverName A pointer to the string to return.
00049                      This string is the name of the
00050                      driver specified by This in the language
00051                      specified by Language.
00052 
00053   @retval EFI_SUCCESS           The string for the
00054                                 Driver specified by This and the
00055                                 language specified by Language
00056                                 was returned in DriverName.
00057 
00058   @retval EFI_INVALID_PARAMETER Language is NULL.
00059 
00060   @retval EFI_INVALID_PARAMETER DriverName is NULL.
00061 
00062   @retval EFI_UNSUPPORTED       The driver specified by This
00063                                 does not support the language
00064                                 specified by Language.
00065 
00066 **/
00067 typedef
00068 EFI_STATUS
00069 (EFIAPI *EFI_COMPONENT_NAME2_GET_DRIVER_NAME)(
00070   IN EFI_COMPONENT_NAME2_PROTOCOL          *This,
00071   IN  CHAR8                                *Language,
00072   OUT CHAR16                               **DriverName
00073   );
00074 
00075 
00076 /**
00077   Retrieves a string that is the user readable name of
00078   the controller that is being managed by an EFI Driver.
00079 
00080   @param  This             A pointer to the
00081                            EFI_COMPONENT_NAME2_PROTOCOL instance.
00082 
00083   @param  ControllerHandle The handle of a controller that the
00084                            driver specified by This is managing.
00085                            This handle specifies the controller
00086                            whose name is to be returned.
00087 
00088   @param  ChildHandle      The handle of the child controller to
00089                            retrieve the name of.  This is an
00090                            optional parameter that may be NULL.
00091                            It will be NULL for device drivers.
00092                            It will also be NULL for bus
00093                            drivers that wish to retrieve the
00094                            name of the bus controller.  It will
00095                            not be NULL for a bus driver that
00096                            wishes to retrieve the name of a
00097                            child controller.
00098 
00099   @param  Language         A pointer to a Null-terminated ASCII
00100                            string array indicating the language.
00101                            This is the language of the driver
00102                            name that the caller is requesting,
00103                            and it must match one of the
00104                            languages specified in
00105                            SupportedLanguages. The number of
00106                            languages supported by a driver is up
00107                            to the driver writer. Language is
00108                            specified in RFC 4646 language code
00109                            format.
00110 
00111   @param  ControllerName   A pointer to the string to return.
00112                            This string is the name of the controller
00113                            specified by ControllerHandle and ChildHandle
00114                            in the language specified by Language
00115                            from the point of view of the driver
00116                            specified by This.
00117 
00118   @retval EFI_SUCCESS           The string for the user
00119                                 readable name in the language
00120                                 specified by Language for the
00121                                 driver specified by This was
00122                                 returned in DriverName.
00123 
00124   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
00125 
00126   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it
00127                                 is not a valid EFI_HANDLE.
00128 
00129   @retval EFI_INVALID_PARAMETER Language is NULL.
00130 
00131   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
00132 
00133   @retval EFI_UNSUPPORTED       The driver specified by This is
00134                                 not currently managing the
00135                                 controller specified by
00136                                 ControllerHandle and
00137                                 ChildHandle.
00138 
00139   @retval EFI_UNSUPPORTED       The driver specified by This
00140                                 does not support the language
00141                                 specified by Language.
00142 
00143 **/
00144 typedef
00145 EFI_STATUS
00146 (EFIAPI *EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME)(
00147   IN EFI_COMPONENT_NAME2_PROTOCOL *This,
00148   IN  EFI_HANDLE                  ControllerHandle,
00149   IN  EFI_HANDLE                  ChildHandle        OPTIONAL,
00150   IN  CHAR8                       *Language,
00151   OUT CHAR16                      **ControllerName
00152   );
00153 
00154 ///
00155 /// This protocol is used to retrieve user readable names of drivers
00156 /// and controllers managed by UEFI Drivers.
00157 ///
00158 struct _EFI_COMPONENT_NAME2_PROTOCOL {
00159   EFI_COMPONENT_NAME2_GET_DRIVER_NAME      GetDriverName;
00160   EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME  GetControllerName;
00161 
00162   ///
00163   /// A Null-terminated ASCII string array that contains one or more
00164   /// supported language codes. This is the list of language codes that
00165   /// this protocol supports. The number of languages supported by a
00166   /// driver is up to the driver writer. SupportedLanguages is
00167   /// specified in RFC 4646 format.
00168   ///
00169   CHAR8                                    *SupportedLanguages;
00170 };
00171 
00172 extern EFI_GUID gEfiComponentName2ProtocolGuid;
00173 
00174 #endif