[efi] Provide component name protocol and device path protocol interfaces
[people/asdlkf/gpxe.git] / src / include / gpxe / efi / 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 - 2008, Intel Corporation
7   All rights reserved. This program and the accompanying materials
8   are licensed and made available under the terms and conditions of the BSD License
9   which accompanies this distribution.  The full text of the license may be found at
10   http://opensource.org/licenses/bsd-license.php
11
12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
14
15 **/
16
17 #ifndef __EFI_COMPONENT_NAME2_H__
18 #define __EFI_COMPONENT_NAME2_H__
19
20 ///
21 /// Global ID for the Component Name Protocol
22 ///
23 #define EFI_COMPONENT_NAME2_PROTOCOL_GUID \
24   {0x6a7a5cff, 0xe8d9, 0x4f70, { 0xba, 0xda, 0x75, 0xab, 0x30, 0x25, 0xce, 0x14 } }
25
26 typedef struct _EFI_COMPONENT_NAME2_PROTOCOL  EFI_COMPONENT_NAME2_PROTOCOL;
27
28
29 /**
30   Retrieves a Unicode string that is the user readable name of
31   the EFI Driver.
32
33   @param  This       A pointer to the
34                      EFI_COMPONENT_NAME2_PROTOCOL instance.
35
36   @param  Language   A pointer to a Null-terminated ASCII string
37                      array indicating the language. This is the
38                      language of the driver name that the caller
39                      is requesting, and it must match one of the
40                      languages specified in SupportedLanguages.
41                      The number of languages supported by a
42                      driver is up to the driver writer. Language
43                      is specified in RFC 3066 language code
44                      format.
45
46   @param  DriverName A pointer to the Unicode string to return.
47                      This Unicode string is the name of the
48                      driver specified by This in the language
49                      specified by Language.
50
51   @retval EFI_SUCCESS           The Unicode string for the
52                                 Driver specified by This and the
53                                 language specified by Language
54                                 was returned in DriverName.
55
56   @retval EFI_INVALID_PARAMETER Language is NULL.
57
58   @retval EFI_INVALID_PARAMETER DriverName is NULL.
59
60   @retval EFI_UNSUPPORTED       The driver specified by This
61                                 does not support the language
62                                 specified by Language.
63
64 **/
65 typedef
66 EFI_STATUS
67 (EFIAPI *EFI_COMPONENT_NAME2_GET_DRIVER_NAME)(
68   IN EFI_COMPONENT_NAME2_PROTOCOL          *This,
69   IN  CHAR8                                *Language,
70   OUT CHAR16                               **DriverName
71   );
72
73
74 /**
75   Retrieves a Unicode string that is the user readable name of
76   the controller that is being managed by an EFI Driver.
77
78   @param  This             A pointer to the
79                            EFI_COMPONENT_NAME2_PROTOCOL instance.
80
81   @param  ControllerHandle The handle of a controller that the
82                            driver specified by This is managing.
83                            This handle specifies the controller
84                            whose name is to be returned.
85
86   @param ChildHandle      The handle of the child controller to
87                            retrieve the name of.  This is an
88                            optional parameter that may be NULL.
89                            It will be NULL for device drivers.
90                            It will also be NULL for a bus
91                            drivers that wish to retrieve the
92                            name of the bus controller.  It will
93                            not be NULL for a bus driver that
94                            wishes to retrieve the name of a
95                            child controller.
96
97   @param  Language         A pointer to a Null-terminated ASCII
98                            string array indicating the language.
99                            This is the language of the driver
100                            name that the caller is requesting,
101                            and it must match one of the
102                            languages specified in
103                            SupportedLanguages. The number of
104                            languages supported by a driver is up
105                            to the driver writer. Language is
106                            specified in RFC 3066 language code
107                            format.
108
109   @param  ControllerName   A pointer to the Unicode string to
110                            return.  This Unicode string is the
111                            name of the controller specified by
112                            ControllerHandle and ChildHandle in
113                            the language specified by Language
114                            from the point of view of the driver
115                            specified by This.
116
117   @retval EFI_SUCCESS           The Unicode string for the user
118                                 readable name in the language
119                                 specified by Language for the
120                                 driver specified by This was
121                                 returned in DriverName.
122
123   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid
124                                 EFI_HANDLE.
125
126   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it
127                                 is not a valid EFI_HANDLE.
128
129   @retval EFI_INVALID_PARAMETER Language is NULL.
130
131   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
132
133   @retval EFI_UNSUPPORTED       The driver specified by This is
134                                 not currently managing the
135                                 controller specified by
136                                 ControllerHandle and
137                                 ChildHandle.
138
139   @retval EFI_UNSUPPORTED       The driver specified by This
140                                 does not support the language
141                                 specified by Language.
142
143 **/
144 typedef
145 EFI_STATUS
146 (EFIAPI *EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME)(
147   IN EFI_COMPONENT_NAME2_PROTOCOL *This,
148   IN  EFI_HANDLE                  ControllerHandle,
149   IN  EFI_HANDLE                  ChildHandle        OPTIONAL,
150   IN  CHAR8                       *Language,
151   OUT CHAR16                      **ControllerName
152   );
153
154 ///
155 /// This protocol is used to retrieve user readable names of drivers
156 /// and controllers managed by UEFI Drivers.
157 ///
158 struct _EFI_COMPONENT_NAME2_PROTOCOL {
159   EFI_COMPONENT_NAME2_GET_DRIVER_NAME      GetDriverName;
160   EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME  GetControllerName;
161
162   ///
163   /// A Null-terminated ASCII string array that contains one or more
164   /// supported language codes. This is the list of language codes that
165   /// this protocol supports. The number of languages supported by a
166   /// driver is up to the driver writer. SupportedLanguages is
167   /// specified in RFC 3066 format.
168   ///
169   CHAR8                                    *SupportedLanguages;
170 };
171
172 extern EFI_GUID gEfiComponentName2ProtocolGuid;
173
174 #endif