2 The file provides services to manipulate string data.
4 Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials are licensed and made available under
6 the terms and conditions of the BSD License that accompanies this distribution.
7 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 #include <Protocol/HiiFont.h>
20 #define EFI_HII_STRING_PROTOCOL_GUID \
21 { 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } }
23 typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL
;
26 This function adds the string String to the group of strings owned by PackageList, with the
27 specified font information StringFontInfo, and returns a new string id.
28 The new string identifier is guaranteed to be unique within the package list.
29 That new string identifier is reserved for all languages in the package list.
31 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
32 @param PackageList The handle of the package list where this string will
34 @param StringId On return, contains the new strings id, which is
35 unique within PackageList.
36 @param Language Points to the language for the new string.
37 @param LanguageName Points to the printable language name to associate
38 with the passed in Language field.If LanguageName
39 is not NULL and the string package header's
40 LanguageName associated with a given Language is
41 not zero, the LanguageName being passed in will
43 @param String Points to the new null-terminated string.
44 @param StringFontInfo Points to the new string's font information or
45 NULL if the string should have the default system
48 @retval EFI_SUCCESS The new string was added successfully.
49 @retval EFI_NOT_FOUND The specified PackageList could not be found in
51 @retval EFI_OUT_OF_RESOURCES Could not add the string due to lack of resources.
52 @retval EFI_INVALID_PARAMETER String is NULL, or StringId is NULL, or Language is NULL.
53 @retval EFI_INVALID_PARAMETER The specified StringFontInfo does not exist in
59 (EFIAPI
*EFI_HII_NEW_STRING
)(
60 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
61 IN EFI_HII_HANDLE PackageList
,
62 OUT EFI_STRING_ID
*StringId
,
63 IN CONST CHAR8
*Language
,
64 IN CONST CHAR16
*LanguageName
, OPTIONAL
65 IN CONST EFI_STRING String
,
66 IN CONST EFI_FONT_INFO
*StringFontInfo OPTIONAL
71 This function retrieves the string specified by StringId which is associated
72 with the specified PackageList in the language Language and copies it into
73 the buffer specified by String.
75 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
76 @param Language Points to the language for the retrieved string.
77 @param PackageList The package list in the HII database to search for
79 @param StringId The string's id, which is unique within
81 @param String Points to the new null-terminated string.
82 @param StringSize On entry, points to the size of the buffer pointed
83 to by String, in bytes. On return, points to the
84 length of the string, in bytes.
85 @param StringFontInfo If not NULL, points to the string's font
86 information. It's caller's responsibility to free
89 @retval EFI_SUCCESS The string was returned successfully.
90 @retval EFI_NOT_FOUND The string specified by StringId is not available.
91 @retval EFI_NOT_FOUND The string specified by StringId is available but
92 not in the specified language.
93 The specified PackageList is not in the database.
94 @retval EFI_BUFFER_TOO_SMALL The buffer specified by StringSize is too small to
96 @retval EFI_INVALID_PARAMETER The String or Language or StringSize was NULL.
97 @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the
103 (EFIAPI
*EFI_HII_GET_STRING
)(
104 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
105 IN CONST CHAR8
*Language
,
106 IN EFI_HII_HANDLE PackageList
,
107 IN EFI_STRING_ID StringId
,
108 OUT EFI_STRING String
,
109 IN OUT UINTN
*StringSize
,
110 OUT EFI_FONT_INFO
**StringFontInfo OPTIONAL
114 This function updates the string specified by StringId in the specified PackageList to the text
115 specified by String and, optionally, the font information specified by StringFontInfo.
117 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
118 @param PackageList The package list containing the strings.
119 @param StringId The string's id, which is unique within
121 @param Language Points to the language for the updated string.
122 @param String Points to the new null-terminated string.
123 @param StringFontInfo Points to the string's font information or NULL if
124 the string font information is not changed.
126 @retval EFI_SUCCESS The string was updated successfully.
127 @retval EFI_NOT_FOUND The string specified by StringId is not in the
129 @retval EFI_INVALID_PARAMETER The String or Language was NULL.
130 @retval EFI_INVALID_PARAMETER The specified StringFontInfo does not exist in
132 @retval EFI_OUT_OF_RESOURCES The system is out of resources to accomplish the
138 (EFIAPI
*EFI_HII_SET_STRING
)(
139 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
140 IN EFI_HII_HANDLE PackageList
,
141 IN EFI_STRING_ID StringId
,
142 IN CONST CHAR8
*Language
,
143 IN EFI_STRING String
,
144 IN CONST EFI_FONT_INFO
*StringFontInfo OPTIONAL
149 This function returns the list of supported languages.
151 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
152 @param PackageList The package list to examine.
153 @param Languages Points to the buffer to hold the returned
154 null-terminated ASCII string.
155 @param LanguagesSize On entry, points to the size of the buffer pointed
156 to by Languages, in bytes. On return, points to
157 the length of Languages, in bytes.
159 @retval EFI_SUCCESS The languages were returned successfully.
160 @retval EFI_INVALID_PARAMETER The Languages or LanguagesSize was NULL.
161 @retval EFI_BUFFER_TOO_SMALL The LanguagesSize is too small to hold the list of
162 supported languages. LanguageSize is updated to
163 contain the required size.
164 @retval EFI_NOT_FOUND Could not find string package in specified
170 (EFIAPI
*EFI_HII_GET_LANGUAGES
)(
171 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
172 IN EFI_HII_HANDLE PackageList
,
173 IN OUT CHAR8
*Languages
,
174 IN OUT UINTN
*LanguagesSize
179 Each string package has associated with it a single primary language and zero
180 or more secondary languages. This routine returns the secondary languages
181 associated with a package list.
183 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
184 @param PackageList The package list to examine.
185 @param PrimaryLanguage Points to the null-terminated ASCII string that specifies
186 the primary language. Languages are specified in the
187 format specified in Appendix M of the UEFI 2.0 specification.
188 @param SecondaryLanguages Points to the buffer to hold the returned null-terminated
189 ASCII string that describes the list of
190 secondary languages for the specified
191 PrimaryLanguage. If there are no secondary
192 languages, the function returns successfully, but
194 @param SecondaryLanguagesSize On entry, points to the size of the buffer pointed
195 to by SecondaryLanguages, in bytes. On return,
196 points to the length of SecondaryLanguages in bytes.
198 @retval EFI_SUCCESS Secondary languages were correctly returned.
199 @retval EFI_INVALID_PARAMETER PrimaryLanguage or SecondaryLanguages or
200 SecondaryLanguagesSize was NULL.
201 @retval EFI_BUFFER_TOO_SMALL The buffer specified by SecondaryLanguagesSize is
202 too small to hold the returned information.
203 SecondaryLanguageSize is updated to hold the size of
205 @retval EFI_INVALID_LANGUAGE The language specified by PrimaryLanguage is not
206 present in the specified package list.
207 @retval EFI_NOT_FOUND The specified PackageList is not in the Database.
212 (EFIAPI
*EFI_HII_GET_2ND_LANGUAGES
)(
213 IN CONST EFI_HII_STRING_PROTOCOL
*This
,
214 IN EFI_HII_HANDLE PackageList
,
215 IN CONST CHAR8
*PrimaryLanguage
,
216 IN OUT CHAR8
*SecondaryLanguages
,
217 IN OUT UINTN
*SecondaryLanguagesSize
222 /// Services to manipulate the string.
224 struct _EFI_HII_STRING_PROTOCOL
{
225 EFI_HII_NEW_STRING NewString
;
226 EFI_HII_GET_STRING GetString
;
227 EFI_HII_SET_STRING SetString
;
228 EFI_HII_GET_LANGUAGES GetLanguages
;
229 EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages
;
233 extern EFI_GUID gEfiHiiStringProtocolGuid
;