MdePkg/Include/Protocol/ComponentName2.h

   1 /** @file
   2   UEFI Component Name 2 Protocol as defined in the UEFI 2.1 specification.
   3   This protocol is used to retrieve user readable names of drivers
   4   and controllers managed by UEFI Drivers.
   5
   6   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef __EFI_COMPONENT_NAME2_H__
  12 #define __EFI_COMPONENT_NAME2_H__
  13
  14 ///
  15 /// Global ID for the Component Name Protocol
  16 ///
  17 #define EFI_COMPONENT_NAME2_PROTOCOL_GUID \
  18   {0x6a7a5cff, 0xe8d9, 0x4f70, { 0xba, 0xda, 0x75, 0xab, 0x30, 0x25, 0xce, 0x14 } }
  19
  20 typedef struct _EFI_COMPONENT_NAME2_PROTOCOL  EFI_COMPONENT_NAME2_PROTOCOL;
  21
  22
  23 /**
  24   Retrieves a string that is the user readable name of
  25   the EFI Driver.
  26
  27   @param  This       A pointer to the
  28                      EFI_COMPONENT_NAME2_PROTOCOL instance.
  29
  30   @param  Language   A pointer to a Null-terminated ASCII string
  31                      array indicating the language. This is the
  32                      language of the driver name that the caller
  33                      is requesting, and it must match one of the
  34                      languages specified in SupportedLanguages.
  35                      The number of languages supported by a
  36                      driver is up to the driver writer. Language
  37                      is specified in RFC 4646 language code
  38                      format.
  39
  40   @param  DriverName A pointer to the string to return.
  41                      This string is the name of the
  42                      driver specified by This in the language
  43                      specified by Language.
  44
  45   @retval EFI_SUCCESS           The string for the
  46                                 Driver specified by This and the
  47                                 language specified by Language
  48                                 was returned in DriverName.
  49
  50   @retval EFI_INVALID_PARAMETER Language is NULL.
  51
  52   @retval EFI_INVALID_PARAMETER DriverName is NULL.
  53
  54   @retval EFI_UNSUPPORTED       The driver specified by This
  55                                 does not support the language
  56                                 specified by Language.
  57
  58 **/
  59 typedef
  60 EFI_STATUS
  61 (EFIAPI *EFI_COMPONENT_NAME2_GET_DRIVER_NAME)(
  62   IN EFI_COMPONENT_NAME2_PROTOCOL          *This,
  63   IN  CHAR8                                *Language,
  64   OUT CHAR16                               **DriverName
  65   );
  66
  67
  68 /**
  69   Retrieves a string that is the user readable name of
  70   the controller that is being managed by an EFI Driver.
  71
  72   @param  This             A pointer to the
  73                            EFI_COMPONENT_NAME2_PROTOCOL instance.
  74
  75   @param  ControllerHandle The handle of a controller that the
  76                            driver specified by This is managing.
  77                            This handle specifies the controller
  78                            whose name is to be returned.
  79
  80   @param  ChildHandle      The handle of the child controller to
  81                            retrieve the name of.  This is an
  82                            optional parameter that may be NULL.
  83                            It will be NULL for device drivers.
  84                            It will also be NULL for bus
  85                            drivers that wish to retrieve the
  86                            name of the bus controller.  It will
  87                            not be NULL for a bus driver that
  88                            wishes to retrieve the name of a
  89                            child controller.
  90
  91   @param  Language         A pointer to a Null-terminated ASCII
  92                            string array indicating the language.
  93                            This is the language of the driver
  94                            name that the caller is requesting,
  95                            and it must match one of the
  96                            languages specified in
  97                            SupportedLanguages. The number of
  98                            languages supported by a driver is up
  99                            to the driver writer. Language is
 100                            specified in RFC 4646 language code
 101                            format.
 102
 103   @param  ControllerName   A pointer to the string to return.
 104                            This string is the name of the controller
 105                            specified by ControllerHandle and ChildHandle
 106                            in the language specified by Language
 107                            from the point of view of the driver
 108                            specified by This.
 109
 110   @retval EFI_SUCCESS           The string for the user
 111                                 readable name in the language
 112                                 specified by Language for the
 113                                 driver specified by This was
 114                                 returned in DriverName.
 115
 116   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 117
 118   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it
 119                                 is not a valid EFI_HANDLE.
 120
 121   @retval EFI_INVALID_PARAMETER Language is NULL.
 122
 123   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 124
 125   @retval EFI_UNSUPPORTED       The driver specified by This is
 126                                 not currently managing the
 127                                 controller specified by
 128                                 ControllerHandle and
 129                                 ChildHandle.
 130
 131   @retval EFI_UNSUPPORTED       The driver specified by This
 132                                 does not support the language
 133                                 specified by Language.
 134
 135 **/
 136 typedef
 137 EFI_STATUS
 138 (EFIAPI *EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME)(
 139   IN EFI_COMPONENT_NAME2_PROTOCOL *This,
 140   IN  EFI_HANDLE                  ControllerHandle,
 141   IN  EFI_HANDLE                  ChildHandle        OPTIONAL,
 142   IN  CHAR8                       *Language,
 143   OUT CHAR16                      **ControllerName
 144   );
 145
 146 ///
 147 /// This protocol is used to retrieve user readable names of drivers
 148 /// and controllers managed by UEFI Drivers.
 149 ///
 150 struct _EFI_COMPONENT_NAME2_PROTOCOL {
 151   EFI_COMPONENT_NAME2_GET_DRIVER_NAME      GetDriverName;
 152   EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME  GetControllerName;
 153
 154   ///
 155   /// A Null-terminated ASCII string array that contains one or more
 156   /// supported language codes. This is the list of language codes that
 157   /// this protocol supports. The number of languages supported by a
 158   /// driver is up to the driver writer. SupportedLanguages is
 159   /// specified in RFC 4646 format.
 160   ///
 161   CHAR8                                    *SupportedLanguages;
 162 };
 163
 164 extern EFI_GUID gEfiComponentName2ProtocolGuid;
 165
 166 #endif