2 HII Library implementation that uses DXE protocols and services.
4 Copyright (c) 2006 - 2008, Intel Corporation<BR>
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.
16 #include "InternalHiiLib.h"
19 This function create a new string in String Package or updates an existing
20 string in a String Package. If StringId is 0, then a new string is added to
21 a String Package. If StringId is not zero, then a string in String Package is
22 updated. If SupportedLanguages is NULL, then the string is added or updated
23 for all the languages that the String Package supports. If SupportedLanguages
24 is not NULL, then the string is added or updated for the set of languages
25 specified by SupportedLanguages.
27 If HiiHandle is NULL, then ASSERT().
28 If String is NULL, then ASSERT().
30 @param[in] HiiHandle A handle that was previously registered in the
32 @param[in] StringId If zero, then a new string is created in the
33 String Package associated with HiiHandle. If
34 non-zero, then the string specified by StringId
35 is updated in the String Package associated
37 @param[in] String A pointer to the Null-terminated Unicode string
38 to add or update in the String Package associated
40 @param[in] SupportedLanguages A pointer to a Null-terminated ASCII string of
41 language codes. If this parameter is NULL, then
42 String is added or updated in the String Package
43 associated with HiiHandle for all the languages
44 that the String Package supports. If this
45 parameter is not NULL, then then String is added
46 or updated in the String Package associated with
47 HiiHandle for the set oflanguages specified by
48 SupportedLanguages. The format of
49 SupportedLanguages must follow the language
50 format assumed the HII Database.
52 @retval 0 The string could not be added or updated in the String Package.
53 @retval Other The EFI_STRING_ID of the newly added or updated string.
59 IN EFI_HII_HANDLE HiiHandle
,
60 IN EFI_STRING_ID StringId
, OPTIONAL
61 IN CONST EFI_STRING String
,
62 IN CONST CHAR8
*SupportedLanguages OPTIONAL
66 CHAR8
*AllocatedLanguages
;
69 EFI_STRING_ID NewStringId
;
71 ASSERT (HiiHandle
!= NULL
);
72 ASSERT (String
!= NULL
);
74 if (SupportedLanguages
== NULL
) {
76 // Retrieve the languages that the package specified by HiiHandle supports
78 AllocatedLanguages
= HiiGetSupportedLanguages (HiiHandle
);
81 // Allocate a copy of the SupportLanguages string that passed in
83 AllocatedLanguages
= AllocateCopyPool (AsciiStrSize (SupportedLanguages
), SupportedLanguages
);
87 // If there are not enough resources for the supported languages string, then return a StringId of 0
89 if (AllocatedLanguages
== NULL
) {
90 return (EFI_STRING_ID
)(0);
94 Status
= EFI_INVALID_PARAMETER
;
96 // Loop through each language that the string supports
98 for (Supported
= AllocatedLanguages
; *Supported
!= '\0'; ) {
100 // Cache a pointer to the beginning of the current language in the list of languages
102 Language
= Supported
;
105 // Search for the next language seperator and replace it with a Null-terminator
107 for (; *Supported
!= 0 && *Supported
!= ';'; Supported
++);
108 if (*Supported
!= 0) {
109 *(Supported
++) = '\0';
113 // If StringId is 0, then call NewString(). Otherwise, call SetString()
115 if (StringId
== (EFI_STRING_ID
)(0)) {
116 Status
= gHiiString
->NewString (gHiiString
, HiiHandle
, &NewStringId
, Language
, NULL
, String
, NULL
);
118 Status
= gHiiString
->SetString (gHiiString
, HiiHandle
, StringId
, Language
, String
, NULL
);
122 // If there was an error, then break out of the loop and return a StringId of 0
124 if (EFI_ERROR (Status
)) {
130 // Free the buffer of supported languages
132 FreePool (AllocatedLanguages
);
134 if (EFI_ERROR (Status
)) {
135 return (EFI_STRING_ID
)(0);
136 } else if (StringId
== (EFI_STRING_ID
)(0)) {
145 Retrieves a string from a string package names by GUID in a specific language.
146 If the language is not specified, then a string from a string package in the
147 current platform language is retrieved. If the string can not be retrieved
148 using the specified language or the current platform language, then the string
149 is retrieved from the string package in the first language the string package
150 supports. The returned string is allocated using AllocatePool(). The caller
151 is responsible for freeing the allocated buffer using FreePool().
153 If PackageListGuid is NULL, then ASSERT().
154 If StringId is 0, then ASSERT.
156 @param[in] PackageListGuid The GUID of a package list that was previously
157 registered in the HII Database.
158 @param[in] StringId The identifier of the string to retrieved from the
159 string package associated with PackageListGuid.
160 @param[in] Language The language of the string to retrieve. If this
161 parameter is NULL, then the current platform
162 language is used. The format of Language must
163 follow the language format assumed the HII Database.
165 @retval NULL The package list specified by PackageListGuid is not present in the
167 @retval NULL The string specified by StringId is not present in the string package.
168 @retval Other The string was returned.
173 HiiGetPackageString (
174 IN CONST EFI_GUID
*PackageListGuid
,
175 IN EFI_STRING_ID StringId
,
176 IN CONST CHAR8
*Language OPTIONAL
179 EFI_HANDLE
*HiiHandleBuffer
;
180 EFI_HANDLE HiiHandle
;
182 ASSERT (PackageListGuid
!= NULL
);
184 HiiHandleBuffer
= HiiGetHiiHandles (PackageListGuid
);
185 if (HiiHandleBuffer
== NULL
) {
189 HiiHandle
= HiiHandleBuffer
[0];
190 FreePool (HiiHandleBuffer
);
192 return HiiGetString (HiiHandle
, StringId
, Language
);
196 Retrieves a string from a string package in a specific language. If the language
197 is not specified, then a string from a string package in the current platform
198 language is retrieved. If the string can not be retrieved using the specified
199 language or the current platform language, then the string is retrieved from
200 the string package in the first language the string package supports. The
201 returned string is allocated using AllocatePool(). The caller is responsible
202 for freeing the allocated buffer using FreePool().
204 If HiiHandle is NULL, then ASSERT().
205 If StringId is 0, then ASSET.
207 @param[in] HiiHandle A handle that was previously registered in the HII Database.
208 @param[in] StringId The identifier of the string to retrieved from the string
209 package associated with HiiHandle.
210 @param[in] Language The language of the string to retrieve. If this parameter
211 is NULL, then the current platform language is used. The
212 format of Language must follow the language format assumed
215 @retval NULL The string specified by StringId is not present in the string package.
216 @retval Other The string was returned.
222 IN EFI_HII_HANDLE HiiHandle
,
223 IN EFI_STRING_ID StringId
,
224 IN CONST CHAR8
*Language OPTIONAL
231 CHAR8
*SupportedLanguages
;
232 CHAR8
*PlatformLanguage
;
235 ASSERT (HiiHandle
!= NULL
);
236 ASSERT (StringId
!= 0);
239 // Initialize all allocated buffers to NULL
241 SupportedLanguages
= NULL
;
242 PlatformLanguage
= NULL
;
247 // Get the languages that the package specified by HiiHandle supports
249 SupportedLanguages
= HiiGetSupportedLanguages (HiiHandle
);
250 if (SupportedLanguages
== NULL
) {
255 // Get the current platform language setting
257 PlatformLanguage
= GetEfiGlobalVariable (L
"PlatformLang");
260 // If Languag is NULL, then set it to an empty string, so it will be
261 // skipped by GetBestLanguage()
263 if (Language
== NULL
) {
268 // Get the best matching language from SupportedLanguages
270 BestLanguage
= GetBestLanguage (
272 FALSE
, // RFC 4646 mode
273 Language
, // Highest priority
274 PlatformLanguage
!= NULL
? PlatformLanguage
: "", // Next highest priority
275 SupportedLanguages
, // Lowest priority
278 if (BestLanguage
== NULL
) {
283 // Retrieve the size of the string in the string package for the BestLanguage
286 Status
= gHiiString
->GetString (
296 // If GetString() returns EFI_SUCCESS for a zero size,
297 // then there are no supported languages registered for HiiHandle. If GetString()
298 // returns an error other than EFI_BUFFER_TOO_SMALL, then HiiHandle is not present
299 // in the HII Database
301 if (Status
!= EFI_BUFFER_TOO_SMALL
) {
306 // Allocate a buffer for the return string
308 String
= AllocateZeroPool (StringSize
);
309 if (String
== NULL
) {
314 // Retrieve the string from the string package
316 Status
= gHiiString
->GetString (
325 if (EFI_ERROR (Status
)) {
327 // Free the buffer and return NULL if the supported languages can not be retrieved.
335 // Free allocated buffers
337 if (SupportedLanguages
!= NULL
) {
338 FreePool (SupportedLanguages
);
340 if (PlatformLanguage
!= NULL
) {
341 FreePool (PlatformLanguage
);
343 if (BestLanguage
!= NULL
) {
344 FreePool (BestLanguage
);
348 // Return the Null-terminated Unicode string