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   Retrieves a string that is the user readable name of
  24   the EFI Driver.
  25
  26   @param  This       A pointer to the
  27                      EFI_COMPONENT_NAME2_PROTOCOL instance.
  28
  29   @param  Language   A pointer to a Null-terminated ASCII string
  30                      array indicating the language. This is the
  31                      language of the driver name that the caller
  32                      is requesting, and it must match one of the
  33                      languages specified in SupportedLanguages.
  34                      The number of languages supported by a
  35                      driver is up to the driver writer. Language
  36                      is specified in RFC 4646 language code
  37                      format.
  38
  39   @param  DriverName A pointer to the string to return.
  40                      This string is the name of the
  41                      driver specified by This in the language
  42                      specified by Language.
  43
  44   @retval EFI_SUCCESS           The string for the
  45                                 Driver specified by This and the
  46                                 language specified by Language
  47                                 was returned in DriverName.
  48
  49   @retval EFI_INVALID_PARAMETER Language is NULL.
  50
  51   @retval EFI_INVALID_PARAMETER DriverName is NULL.
  52
  53   @retval EFI_UNSUPPORTED       The driver specified by This
  54                                 does not support the language
  55                                 specified by Language.
  56
  57 **/
  58 typedef
  59 EFI_STATUS
  60 (EFIAPI *EFI_COMPONENT_NAME2_GET_DRIVER_NAME)(
  61   IN EFI_COMPONENT_NAME2_PROTOCOL          *This,
  62   IN  CHAR8                                *Language,
  63   OUT CHAR16                               **DriverName
  64   );
  65
  66 /**
  67   Retrieves a string that is the user readable name of
  68   the controller that is being managed by an EFI Driver.
  69
  70   @param  This             A pointer to the
  71                            EFI_COMPONENT_NAME2_PROTOCOL instance.
  72
  73   @param  ControllerHandle The handle of a controller that the
  74                            driver specified by This is managing.
  75                            This handle specifies the controller
  76                            whose name is to be returned.
  77
  78   @param  ChildHandle      The handle of the child controller to
  79                            retrieve the name of.  This is an
  80                            optional parameter that may be NULL.
  81                            It will be NULL for device drivers.
  82                            It will also be NULL for bus
  83                            drivers that wish to retrieve the
  84                            name of the bus controller.  It will
  85                            not be NULL for a bus driver that
  86                            wishes to retrieve the name of a
  87                            child controller.
  88
  89   @param  Language         A pointer to a Null-terminated ASCII
  90                            string array indicating the language.
  91                            This is the language of the driver
  92                            name that the caller is requesting,
  93                            and it must match one of the
  94                            languages specified in
  95                            SupportedLanguages. The number of
  96                            languages supported by a driver is up
  97                            to the driver writer. Language is
  98                            specified in RFC 4646 language code
  99                            format.
 100
 101   @param  ControllerName   A pointer to the string to return.
 102                            This string is the name of the controller
 103                            specified by ControllerHandle and ChildHandle
 104                            in the language specified by Language
 105                            from the point of view of the driver
 106                            specified by This.
 107
 108   @retval EFI_SUCCESS           The string for the user
 109                                 readable name in the language
 110                                 specified by Language for the
 111                                 driver specified by This was
 112                                 returned in DriverName.
 113
 114   @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
 115
 116   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it
 117                                 is not a valid EFI_HANDLE.
 118
 119   @retval EFI_INVALID_PARAMETER Language is NULL.
 120
 121   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 122
 123   @retval EFI_UNSUPPORTED       The driver specified by This is
 124                                 not currently managing the
 125                                 controller specified by
 126                                 ControllerHandle and
 127                                 ChildHandle.
 128
 129   @retval EFI_UNSUPPORTED       The driver specified by This
 130                                 does not support the language
 131                                 specified by Language.
 132
 133 **/
 134 typedef
 135 EFI_STATUS
 136 (EFIAPI *EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME)(
 137   IN EFI_COMPONENT_NAME2_PROTOCOL *This,
 138   IN  EFI_HANDLE                  ControllerHandle,
 139   IN  EFI_HANDLE                  ChildHandle        OPTIONAL,
 140   IN  CHAR8                       *Language,
 141   OUT CHAR16                      **ControllerName
 142   );
 143
 144 ///
 145 /// This protocol is used to retrieve user readable names of drivers
 146 /// and controllers managed by UEFI Drivers.
 147 ///
 148 struct _EFI_COMPONENT_NAME2_PROTOCOL {
 149   EFI_COMPONENT_NAME2_GET_DRIVER_NAME        GetDriverName;
 150   EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME    GetControllerName;
 151
 152   ///
 153   /// A Null-terminated ASCII string array that contains one or more
 154   /// supported language codes. This is the list of language codes that
 155   /// this protocol supports. The number of languages supported by a
 156   /// driver is up to the driver writer. SupportedLanguages is
 157   /// specified in RFC 4646 format.
 158   ///
 159   CHAR8    *SupportedLanguages;
 160 };
 161
 162 extern EFI_GUID  gEfiComponentName2ProtocolGuid;
 163
 164 #endif