2 The file provides services to manipulate string data.
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
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.
15 #ifndef __HII_STRING_H__
16 #define __HII_STRING_H__
18 #error "UEFI 2.1 HII is not fully implemented for now, Please don't include this file now."
20 #define EFI_HII_STRING_PROTOCOL_GUID \
21 { 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } }
24 typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL
;
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.
33 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
35 @param PackageList Handle of the package list where this
38 @param Language Points to the language for the new string.
40 @param String Points to the new null-terminated string.
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
49 @retval EFI_SUCCESS The new string was added successfully
51 @retval EFI_OUT_OF_RESOURCES Could not add the string.
53 @retval EFI_INVALID_PARAMETER String is NULL or StringId is
54 NULL or Language is NULL.
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
,
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
84 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
86 @param PackageList The package list in the HII database to
87 search for the specified string.
89 @param Language Points to the language for the retrieved
92 @param StringId The string's id, which is unique within
95 @param String Points to the new null-terminated string.
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
102 @param StringFontInfo Points to the string's font
103 information or NULL if the string font
104 information is not desired.
106 @retval EFI_SUCCESS The string was returned successfully.
108 @retval EFI_NOT_FOUND The string specified by StringId is not
111 @retval EFI_INVALID_LANGUAGE The string specified by StringId
112 is available but not in the
115 @retval EFI_BUFFER_TOO_SMALL The buffer specified by
116 StringLength is too small to
119 @retval EFI_INVALID_PARAMETER The String or Language was NULL.
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
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
141 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
143 @param PackageList The package list containing the strings.
145 @param Language Points to the language for the updated string.
147 @param StringId The string id, which is unique within
150 @param String Points to the new null-terminated string.
152 @param StringFontInfo Points to the string's font information
153 or NULL if the string font information
156 @retval EFI_SUCCESS The string was successfully updated.
158 @retval EFI_NOT_FOUND The string specified by StringId is not
161 @retval EFI_INVALID_PARAMETER The String or Language was NULL.
163 @retval EFI_OUT_OF_RESOURCES The system is out of resources
164 to accomplish the task.
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
181 This function returns the list of supported languages.
183 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
185 @param PackageList The package list to examine.
187 @param Languages Points to the buffer to hold the returned
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.
196 @retval EFI_SUCCESS The languages were returned successfully.
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
204 @retval EFI_INVALID_PARAMETER Languages is NULL.
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
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.
224 @param This A pointer to the EFI_HII_STRING_PROTOCOL
227 @param PackageList The package list to examine.
229 @param FirstLanguage Points to the primary language.
231 @param Languages are specified in the format specified in
232 Appendix M of the UEFI 2.0 specification.
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.
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
247 @retval EFI_SUCCESS Secondary languages correctly returned
249 @retval EFI_BUFFER_TOO_SMALL The buffer specified by
250 SecondLanguagesSize is too small
252 information. SecondLanguageSize
253 is updated to hold the size of
256 @retval EFI_INVALID_LANGUAGE The language specified by
257 FirstLanguage is not present in
258 the specified package list.
260 @retval EFI_INVALID_PARAMETER FirstLanguage is NULL or
261 SecondLanguage is NULL.
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
276 Services to manipulate the string.
278 @param NewString Add a new string. GetString Retrieve a
279 string and related string information.
281 @param SetString Change a string.
283 @param GetLanguages List the languages for a particular
286 @param GetSecondaryLanguages List supported secondary
287 languages for a particular
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
;
300 extern EFI_GUID gEfiHiiStringProtocolGuid
;