2 The file provides services to manipulate string data.
4 Copyright (c) 2006 - 2008, 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 } }
21 #include <Protocol/HiiDatabase.h>
22 #include <Protocol/HiiFont.h>
25 typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL
;
30 This function adds the string String to the group of strings
31 owned by PackageList, with the specified font information
32 StringFontInfo and returns a new string id.
34 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
36 @param PackageList Handle of the package list where this
39 @param Language Points to the language for the new string.
41 @param String Points to the new null-terminated string.
43 @param StringFontInfo Points to the new string's font
44 information or NULL if the string should
45 have the default system font, size and
46 style. StringId On return, contains the
47 new strings id, which is unique within
50 @retval EFI_SUCCESS The new string was added successfully
52 @retval EFI_OUT_OF_RESOURCES Could not add the string.
54 @retval EFI_INVALID_PARAMETER String is NULL or StringId is
55 NULL or Language is NULL.
61 (EFIAPI
*EFI_HII_NEW_STRING
) (
62 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
63 IN EFI_HII_HANDLE PackageList
,
64 OUT EFI_STRING_ID
*StringId
,
65 IN CONST CHAR8
*Language
,
66 IN CONST CHAR16
*LanguageName
, OPTIONAL
67 IN CONST EFI_STRING String
,
68 IN CONST EFI_FONT_INFO
*StringFontInfo OPTIONAL
74 This function retrieves the string specified by StringId which
75 is associated with the specified PackageList in the language
76 Language and copies it into the buffer specified by String. If
77 the string specified by StringId is not present in the
78 specified PackageList, then EFI_NOT_FOUND is returned. If the
79 string specified by StringId is present, but not in the
80 specified language then EFI_INVALID_LANGUAGE is returned. If
81 the buffer specified by StringSize is too small to hold the
82 string, then EFI_BUFFER_TOO_SMALL will be returned. StringSize
83 will be updated to the size of buffer actually required to
86 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
88 @param PackageList The package list in the HII database to
89 search for the specified string.
91 @param Language Points to the language for the retrieved
94 @param StringId The string's id, which is unique within
97 @param String Points to the new null-terminated string.
99 @param StringSize On entry, points to the size of the buffer
100 pointed to by String, in bytes. On return,
101 points to the length of the string, in
104 @param StringFontInfo Points to a buffer that will be callee allocated and will
105 have the string's font information into this buffer.
106 The caller is responsible for freeing this buffer.
107 If the parameter is NULL a buffer will not be allocated
108 and the string font information will not be returned.
110 @retval EFI_SUCCESS The string was returned successfully.
112 @retval EFI_NOT_FOUND The string specified by StringId is not
113 available. The specified PackageList is not in the database.
115 @retval EFI_INVALID_LANGUAGE The string specified by StringId
116 is available but not in the
119 @retval EFI_BUFFER_TOO_SMALL The buffer specified by
120 StringLength is too small to
123 @retval EFI_INVALID_PARAMETER The String or Language was NULL.
128 (EFIAPI
*EFI_HII_GET_STRING
) (
129 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
130 IN CONST CHAR8
*Language
,
131 IN EFI_HII_HANDLE PackageList
,
132 IN EFI_STRING_ID StringId
,
133 OUT EFI_STRING String
,
134 IN OUT UINTN
*StringSize
,
135 OUT EFI_FONT_INFO
**StringFontInfo OPTIONAL
139 This function updates the string specified by StringId in the
140 specified PackageList to the text specified by String and,
141 optionally, the font information specified by StringFontInfo.
142 There is no way to change the font information without changing
145 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
147 @param PackageList The package list containing the strings.
149 @param Language Points to the language for the updated string.
151 @param StringId The string id, which is unique within
154 @param String Points to the new null-terminated string.
156 @param StringFontInfo Points to the string's font information
157 or NULL if the string font information
160 @retval EFI_SUCCESS The string was successfully updated.
162 @retval EFI_NOT_FOUND The string specified by StringId is not
163 in the database. The specified PackageList is not in the database.
165 @retval EFI_INVALID_PARAMETER The String or Language was NULL.
167 @retval EFI_OUT_OF_RESOURCES The system is out of resources
168 to accomplish the task.
173 (EFIAPI
*EFI_HII_SET_STRING
) (
174 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
175 IN EFI_HII_HANDLE PackageList
,
176 IN EFI_STRING_ID StringId
,
177 IN CONST CHAR8
*Language
,
178 IN EFI_STRING String
,
179 IN CONST EFI_FONT_INFO
*StringFontInfo OPTIONAL
185 This function returns the list of supported languages.
187 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
189 @param PackageList The package list to examine.
191 @param Languages Points to the buffer to hold the returned
194 @param LanguageSize On entry, points to the size of the
195 buffer pointed to by Languages, in
196 bytes. On return, points to the length
197 of Languages, in bytes.
200 @retval EFI_SUCCESS The languages were returned successfully.
202 @retval EFI_BUFFER_TOO_SMALL The LanguagesSize is too small
203 to hold the list of supported
204 languages. LanguageSize is
205 updated to contain the required
208 @retval EFI_INVALID_PARAMETER Languages or LanguagesSize is NULL.
209 @retval EFI_NOT_FOUND The specified PackageList is not in the database.
215 (EFIAPI
*EFI_HII_GET_LANGUAGES
) (
216 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
217 IN EFI_HII_HANDLE PackageList
,
218 IN OUT CHAR8
*Languages
,
219 IN OUT UINTN
*LanguagesSize
225 Each string package has associated with it a single primary
226 language and zero or more secondary languages. This routine
227 returns the secondary languages associated with a package list.
229 @param This A pointer to the EFI_HII_STRING_PROTOCOL
232 @param PackageList The package list to examine.
234 @param FirstLanguage Points to the primary language.
236 @param Languages are specified in the format specified in
237 Appendix M of the UEFI 2.0 specification.
239 @param SecondaryLanguages Points to the buffer to hold the
240 returned list of secondary languages
241 for the specified FirstLanguage. If
242 there are no secondary languages,
243 the function returns successfully,
244 but this is set to NULL.
246 @param SecondaryLanguageSize On entry, points to the size of
247 the buffer pointed to by
248 Languages, in bytes. On return,
249 points to the length of
252 @retval EFI_SUCCESS Secondary languages correctly returned
254 @retval EFI_BUFFER_TOO_SMALL The buffer specified by
255 SecondLanguagesSize is too small
257 information. SecondLanguageSize
258 is updated to hold the size of
261 @retval EFI_INVALID_LANGUAGE The language specified by
262 FirstLanguage is not present in
263 the specified package list.
265 @retval EFI_INVALID_PARAMETER FirstLanguage is NULL or
266 SecondLanguage is NULL.
267 @retval EFI_NOT_FOUND The specified PackageList is not in the database.
272 (EFIAPI
*EFI_HII_GET_2ND_LANGUAGES
) (
273 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
274 IN EFI_HII_HANDLE PackageList
,
275 IN CONST CHAR8
*FirstLanguage
,
276 IN OUT CHAR8
*SecondLanguages
,
277 IN OUT UINTN
*SecondLanguagesSize
282 Services to manipulate the string.
284 @param NewString Add a new string. GetString Retrieve a
285 string and related string information.
287 @param SetString Change a string.
289 @param GetLanguages List the languages for a particular
292 @param GetSecondaryLanguages List supported secondary
293 languages for a particular
297 struct _EFI_HII_STRING_PROTOCOL
{
298 EFI_HII_NEW_STRING NewString
;
299 EFI_HII_GET_STRING GetString
;
300 EFI_HII_SET_STRING SetString
;
301 EFI_HII_GET_LANGUAGES GetLanguages
;
302 EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages
;
306 extern EFI_GUID gEfiHiiStringProtocolGuid
;