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