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 #define EFI_HII_STRING_PROTOCOL_GUID \
19 { 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } }
22 typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL
;
27 This function adds the string String to the group of strings
28 owned by PackageList, with the specified font information
29 StringFontInfo and returns a new string id.
31 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
33 @param PackageList Handle of the package list where this
36 @param Language Points to the language for the new string.
38 @param String Points to the new null-terminated string.
40 @param StringFontInfo Points to the new string's font
41 information or NULL if the string should
42 have the default system font, size and
43 style. StringId On return, contains the
44 new strings id, which is unique within
47 @retval EFI_SUCCESS The new string was added successfully
49 @retval EFI_OUT_OF_RESOURCES Could not add the string.
51 @retval EFI_INVALID_PARAMETER String is NULL or StringId is
52 NULL or Language is NULL.
58 (EFIAPI
*EFI_HII_NEW_STRING
) (
59 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
60 IN CONST EFI_HII_HANDLE PackageList
,
61 OUT EFI_STRING_ID
*StringId
62 IN CONST CHAR8
*Language
,
63 IN CONST EFI_STRING String
,
64 IN CONST EFI_FONT_INFO
*StringFontInfo OPTIONAL
,
70 This function retrieves the string specified by StringId which
71 is associated with the specified PackageList in the language
72 Language and copies it into the buffer specified by String. If
73 the string specified by StringId is not present in the
74 specified PackageList, then EFI_NOT_FOUND is returned. If the
75 string specified by StringId is present, but not in the
76 specified language then EFI_INVALID_LANGUAGE is returned. If
77 the buffer specified by StringSize is too small to hold the
78 string, then EFI_BUFFER_TOO_SMALL will be returned. StringSize
79 will be updated to the size of buffer actually required to
82 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
84 @param PackageList The package list in the HII database to
85 search for the specified string.
87 @param Language Points to the language for the retrieved
90 @param StringId The string's id, which is unique within
93 @param String Points to the new null-terminated string.
95 @param StringSize On entry, points to the size of the buffer
96 pointed to by String, in bytes. On return,
97 points to the length of the string, in
100 @param StringFontInfo Points to the string's font
101 information or NULL if the string font
102 information is not desired.
104 @retval EFI_SUCCESS The string was returned successfully.
106 @retval EFI_NOT_FOUND The string specified by StringId is not
109 @retval EFI_INVALID_LANGUAGE The string specified by StringId
110 is available but not in the
113 @retval EFI_BUFFER_TOO_SMALL The buffer specified by
114 StringLength is too small to
117 @retval EFI_INVALID_PARAMETER The String or Language was NULL.
122 (EFIAPI
*EFI_HII_GET_STRING
) (
123 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
124 IN CONST CHAR8
*Language
,
125 IN CONST EFI_HII_HANDLE PackageList
,
126 IN CONST EFI_STRING_ID StringId
,
127 OUT EFI_STRING String
,
128 IN OUT UINTN StringSize
,
129 OUT EFI_FONT_INFO
*StringFontInfo OPTIONAL
133 This function updates the string specified by StringId in the
134 specified PackageList to the text specified by String and,
135 optionally, the font information specified by StringFontInfo.
136 There is no way to change the font information without changing
139 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
141 @param PackageList The package list containing the strings.
143 @param Language Points to the language for the updated string.
145 @param StringId The string id, which is unique within
148 @param String Points to the new null-terminated string.
150 @param StringFontInfo Points to the string's font information
151 or NULL if the string font information
154 @retval EFI_SUCCESS The string was successfully updated.
156 @retval EFI_NOT_FOUND The string specified by StringId is not
159 @retval EFI_INVALID_PARAMETER The String or Language was NULL.
161 @retval EFI_OUT_OF_RESOURCES The system is out of resources
162 to accomplish the task.
167 (EFIAPI
*EFI_HII_SET_STRING
) (
168 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
169 IN CONST EFI_HII_HANDLE PackageList
,
170 IN CONST EFI_STRING_ID StringId
,
171 IN CONST CHAR8
*Language
,
172 IN CONST EFI_STRING String
,
173 IN CONST EFI_FONT_INFO
*StringFontInfo OPTIONAL
179 This function returns the list of supported languages.
181 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
183 @param PackageList The package list to examine.
185 @param Languages Points to the buffer to hold the returned
188 @param LanguageSize On entry, points to the size of the
189 buffer pointed to by Languages, in
190 bytes. On return, points to the length
191 of Languages, in bytes.
194 @retval EFI_SUCCESS The languages were returned successfully.
196 @retval EFI_BUFFER_TOO_SMALL The LanguagesSize is too small
197 to hold the list of supported
198 languages. LanguageSize is
199 updated to contain the required
202 @retval EFI_INVALID_PARAMETER Languages is NULL.
208 (EFIAPI
*EFI_HII_GET_LANGUAGES
) (
209 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
210 IN CONST EFI_HII_HANDLE PackageList
,
211 IN OUT CHAR8
*Languages
,
212 IN OUT UINTN LanguagesSize
218 Each string package has associated with it a single primary
219 language and zero or more secondary languages. This routine
220 returns the secondary languages associated with a package list.
222 @param This A pointer to the EFI_HII_STRING_PROTOCOL
225 @param PackageList The package list to examine.
227 @param FirstLanguage Points to the primary language.
229 @param Languages are specified in the format specified in
230 Appendix M of the UEFI 2.0 specification.
232 @param SecondaryLanguages Points to the buffer to hold the
233 returned list of secondary languages
234 for the specified FirstLanguage. If
235 there are no secondary languages,
236 the function returns successfully,
237 but this is set to NULL.
239 @param SecondaryLanguageSize On entry, points to the size of
240 the buffer pointed to by
241 Languages, in bytes. On return,
242 points to the length of
245 @retval EFI_SUCCESS Secondary languages correctly returned
247 @retval EFI_BUFFER_TOO_SMALL The buffer specified by
248 SecondLanguagesSize is too small
250 information. SecondLanguageSize
251 is updated to hold the size of
254 @retval EFI_INVALID_LANGUAGE The language specified by
255 FirstLanguage is not present in
256 the specified package list.
258 @retval EFI_INVALID_PARAMETER FirstLanguage is NULL or
259 SecondLanguage is NULL.
264 (EFIAPI
*EFI_GET_2ND_LANGUAGES
) (
265 IN CONST EFI_HII_DATABASE_PROTOCOL
*This
,
266 IN CONST EFI_HII_HANDLE PackageList
,
267 IN CONST CHAR8
*FirstLanguage
;
268 IN OUT CHAR8
*SecondLanguages
,
269 IN OUT UINTN SecondLanguagesSize
274 Services to manipulate the string.
276 @param NewString Add a new string. GetString Retrieve a
277 string and related string information.
279 @param SetString Change a string.
281 @param GetLanguages List the languages for a particular
284 @param GetSecondaryLanguages List supported secondary
285 languages for a particular
289 struct _EFI_HII_STRING_PROTOCOL
{
290 EFI_HII_NEW_STRING NewString
;
291 EFI_HII_GET_STRING GetString
;
292 EFI_HII_SET_STRING SetString
;
293 EFI_HII_GET_LANGUAGES GetLanguages
;
294 EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages
;
298 extern EFI_GUID gEfiHiiStringProtocolGuid
;