add a error macro to prevent this file from included for now #error "UEFI 2.1 HII...
[mirror_edk2.git] / MdePkg / Include / Protocol / HiiString.h
1 /** @file
2 The file provides services to manipulate string data.
3
4 Copyright (c) 2006 - 2007, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 **/
14
15 #ifndef __HII_STRING_H__
16 #define __HII_STRING_H__
17
18 #error "UEFI 2.1 HII is not fully implemented for now, Please don't include this file now."
19
20 #define EFI_HII_STRING_PROTOCOL_GUID \
21 { 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } }
22
23
24 typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL;
25
26
27
28 /**
29 This function adds the string String to the group of strings
30 owned by PackageList, with the specified font information
31 StringFontInfo and returns a new string id.
32
33 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
34
35 @param PackageList Handle of the package list where this
36 string will be added.
37
38 @param Language Points to the language for the new string.
39
40 @param String Points to the new null-terminated string.
41
42 @param StringFontInfo Points to the new string's font
43 information or NULL if the string should
44 have the default system font, size and
45 style. StringId On return, contains the
46 new strings id, which is unique within
47 PackageList.
48
49 @retval EFI_SUCCESS The new string was added successfully
50
51 @retval EFI_OUT_OF_RESOURCES Could not add the string.
52
53 @retval EFI_INVALID_PARAMETER String is NULL or StringId is
54 NULL or Language is NULL.
55
56
57 **/
58 typedef
59 EFI_STATUS
60 (EFIAPI *EFI_HII_NEW_STRING) (
61 IN CONST EFI_HII_STRING_PROTOCOL *This,
62 IN CONST EFI_HII_HANDLE PackageList,
63 OUT EFI_STRING_ID *StringId
64 IN CONST CHAR8 *Language,
65 IN CONST EFI_STRING String,
66 IN CONST EFI_FONT_INFO *StringFontInfo OPTIONAL,
67 );
68
69
70 /**
71
72 This function retrieves the string specified by StringId which
73 is associated with the specified PackageList in the language
74 Language and copies it into the buffer specified by String. If
75 the string specified by StringId is not present in the
76 specified PackageList, then EFI_NOT_FOUND is returned. If the
77 string specified by StringId is present, but not in the
78 specified language then EFI_INVALID_LANGUAGE is returned. If
79 the buffer specified by StringSize is too small to hold the
80 string, then EFI_BUFFER_TOO_SMALL will be returned. StringSize
81 will be updated to the size of buffer actually required to
82 hold the string.
83
84 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
85
86 @param PackageList The package list in the HII database to
87 search for the specified string.
88
89 @param Language Points to the language for the retrieved
90 string.
91
92 @param StringId The string's id, which is unique within
93 PackageList.
94
95 @param String Points to the new null-terminated string.
96
97 @param StringSize On entry, points to the size of the buffer
98 pointed to by String, in bytes. On return,
99 points to the length of the string, in
100 bytes.
101
102 @param StringFontInfo Points to the string's font
103 information or NULL if the string font
104 information is not desired.
105
106 @retval EFI_SUCCESS The string was returned successfully.
107
108 @retval EFI_NOT_FOUND The string specified by StringId is not
109 available.
110
111 @retval EFI_INVALID_LANGUAGE The string specified by StringId
112 is available but not in the
113 specified language.
114
115 @retval EFI_BUFFER_TOO_SMALL The buffer specified by
116 StringLength is too small to
117 hold the string.
118
119 @retval EFI_INVALID_PARAMETER The String or Language was NULL.
120
121 **/
122 typedef
123 EFI_STATUS
124 (EFIAPI *EFI_HII_GET_STRING) (
125 IN CONST EFI_HII_STRING_PROTOCOL *This,
126 IN CONST CHAR8 *Language,
127 IN CONST EFI_HII_HANDLE PackageList,
128 IN CONST EFI_STRING_ID StringId,
129 OUT EFI_STRING String,
130 IN OUT UINTN StringSize,
131 OUT EFI_FONT_INFO *StringFontInfo OPTIONAL
132 );
133
134 /**
135 This function updates the string specified by StringId in the
136 specified PackageList to the text specified by String and,
137 optionally, the font information specified by StringFontInfo.
138 There is no way to change the font information without changing
139 the string text.
140
141 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
142
143 @param PackageList The package list containing the strings.
144
145 @param Language Points to the language for the updated string.
146
147 @param StringId The string id, which is unique within
148 PackageList.
149
150 @param String Points to the new null-terminated string.
151
152 @param StringFontInfo Points to the string's font information
153 or NULL if the string font information
154 is not changed.
155
156 @retval EFI_SUCCESS The string was successfully updated.
157
158 @retval EFI_NOT_FOUND The string specified by StringId is not
159 in the database.
160
161 @retval EFI_INVALID_PARAMETER The String or Language was NULL.
162
163 @retval EFI_OUT_OF_RESOURCES The system is out of resources
164 to accomplish the task.
165
166 **/
167 typedef
168 EFI_STATUS
169 (EFIAPI *EFI_HII_SET_STRING) (
170 IN CONST EFI_HII_STRING_PROTOCOL *This,
171 IN CONST EFI_HII_HANDLE PackageList,
172 IN CONST EFI_STRING_ID StringId,
173 IN CONST CHAR8 *Language,
174 IN CONST EFI_STRING String,
175 IN CONST EFI_FONT_INFO *StringFontInfo OPTIONAL
176 );
177
178
179 /**
180
181 This function returns the list of supported languages.
182
183 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
184
185 @param PackageList The package list to examine.
186
187 @param Languages Points to the buffer to hold the returned
188 string.
189
190 @param LanguageSize On entry, points to the size of the
191 buffer pointed to by Languages, in
192 bytes. On return, points to the length
193 of Languages, in bytes.
194
195
196 @retval EFI_SUCCESS The languages were returned successfully.
197
198 @retval EFI_BUFFER_TOO_SMALL The LanguagesSize is too small
199 to hold the list of supported
200 languages. LanguageSize is
201 updated to contain the required
202 size.
203
204 @retval EFI_INVALID_PARAMETER Languages is NULL.
205
206
207 **/
208 typedef
209 EFI_STATUS
210 (EFIAPI *EFI_HII_GET_LANGUAGES) (
211 IN CONST EFI_HII_DATABASE_PROTOCOL *This,
212 IN CONST EFI_HII_HANDLE PackageList,
213 IN OUT CHAR8 *Languages,
214 IN OUT UINTN LanguagesSize
215 );
216
217
218 /**
219
220 Each string package has associated with it a single primary
221 language and zero or more secondary languages. This routine
222 returns the secondary languages associated with a package list.
223
224 @param This A pointer to the EFI_HII_STRING_PROTOCOL
225 instance.
226
227 @param PackageList The package list to examine.
228
229 @param FirstLanguage Points to the primary language.
230
231 @param Languages are specified in the format specified in
232 Appendix M of the UEFI 2.0 specification.
233
234 @param SecondaryLanguages Points to the buffer to hold the
235 returned list of secondary languages
236 for the specified FirstLanguage. If
237 there are no secondary languages,
238 the function returns successfully,
239 but this is set to NULL.
240
241 @param SecondaryLanguageSize On entry, points to the size of
242 the buffer pointed to by
243 Languages, in bytes. On return,
244 points to the length of
245 Languages in bytes.
246
247 @retval EFI_SUCCESS Secondary languages correctly returned
248
249 @retval EFI_BUFFER_TOO_SMALL The buffer specified by
250 SecondLanguagesSize is too small
251 to hold the returned
252 information. SecondLanguageSize
253 is updated to hold the size of
254 the buffer required.
255
256 @retval EFI_INVALID_LANGUAGE The language specified by
257 FirstLanguage is not present in
258 the specified package list.
259
260 @retval EFI_INVALID_PARAMETER FirstLanguage is NULL or
261 SecondLanguage is NULL.
262
263 **/
264 typedef
265 EFI_STATUS
266 (EFIAPI *EFI_GET_2ND_LANGUAGES) (
267 IN CONST EFI_HII_DATABASE_PROTOCOL *This,
268 IN CONST EFI_HII_HANDLE PackageList,
269 IN CONST CHAR8 *FirstLanguage;
270 IN OUT CHAR8 *SecondLanguages,
271 IN OUT UINTN SecondLanguagesSize
272 );
273
274
275 /**
276 Services to manipulate the string.
277
278 @param NewString Add a new string. GetString Retrieve a
279 string and related string information.
280
281 @param SetString Change a string.
282
283 @param GetLanguages List the languages for a particular
284 package list.
285
286 @param GetSecondaryLanguages List supported secondary
287 languages for a particular
288 primary language.
289
290 **/
291 struct _EFI_HII_STRING_PROTOCOL {
292 EFI_HII_NEW_STRING NewString;
293 EFI_HII_GET_STRING GetString;
294 EFI_HII_SET_STRING SetString;
295 EFI_HII_GET_LANGUAGES GetLanguages;
296 EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages;
297 };
298
299
300 extern EFI_GUID gEfiHiiStringProtocolGuid;
301
302 #endif
303