/** @file\r
HII Library implementation that uses DXE protocols and services.\r
\r
- Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
+ Copyright (c) 2006 - 2021, Intel Corporation. All rights reserved.<BR>\r
+ (C) Copyright 2021 Hewlett Packard Enterprise Development LP<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
}\r
\r
/**\r
- Retrieves a string from a string package in a specific language. If the language\r
- is not specified, then a string from a string package in the current platform\r
- language is retrieved. If the string can not be retrieved using the specified\r
- language or the current platform language, then the string is retrieved from\r
- the string package in the first language the string package supports. The\r
- returned string is allocated using AllocatePool(). The caller is responsible\r
- for freeing the allocated buffer using FreePool().\r
-\r
- If HiiHandle is NULL, then ASSERT().\r
- If StringId is 0, then ASSET.\r
+ Retrieves a string from a string package in a specific language specified in Language\r
+ or in the best lanaguage. See HiiGetStringEx () for the details.\r
\r
@param[in] HiiHandle A handle that was previously registered in the HII Database.\r
@param[in] StringId The identifier of the string to retrieved from the string\r
IN EFI_STRING_ID StringId,\r
IN CONST CHAR8 *Language OPTIONAL\r
)\r
+{\r
+ return HiiGetStringEx (HiiHandle, StringId, Language, TRUE);\r
+}\r
+\r
+/**\r
+ Retrieves a string from a string package in a specific language or in the best\r
+ language at discretion of this function according to the priority of languages.\r
+ TryBestLanguage is used to get the string in the best language or in the language\r
+ specified in Language parameter. The behavior is,\r
+ If TryBestLanguage is TRUE, this function looks for the best language for the string.\r
+ - If the string can not be retrieved using the specified language or the current\r
+ platform language, then the string is retrieved from the string package in the\r
+ first language the string package supports.\r
+ If TryBestLanguage is FALSE, Language must be specified for retrieving the string.\r
+\r
+ The returned string is allocated using AllocatePool(). The caller is responsible\r
+ for freeing the allocated buffer using FreePool().\r
+\r
+ If HiiHandle is NULL, then ASSERT().\r
+ If StringId is 0, then ASSET.\r
+ If TryBestLanguage is FALE and Language is NULL, then ASSERT().\r
+\r
+ @param[in] HiiHandle A handle that was previously registered in the HII Database.\r
+ @param[in] StringId The identifier of the string to retrieved from the string\r
+ package associated with HiiHandle.\r
+ @param[in] Language The language of the string to retrieve. If this parameter\r
+ is NULL, then the current platform language is used. The\r
+ format of Language must follow the language format assumed\r
+ the HII Database.\r
+ @param[in] TryBestLanguage If TRUE, try to get the best matching language from all\r
+ supported languages.If FALSE, the Language must be assigned\r
+ for the StringID.\r
+\r
+ @retval NULL The string specified by StringId is not present in the string package.\r
+ @retval Other The string was returned.\r
+\r
+**/\r
+EFI_STRING\r
+EFIAPI\r
+HiiGetStringEx (\r
+ IN EFI_HII_HANDLE HiiHandle,\r
+ IN EFI_STRING_ID StringId,\r
+ IN CONST CHAR8 *Language OPTIONAL,\r
+ IN BOOLEAN TryBestLanguage\r
+ )\r
{\r
EFI_STATUS Status;\r
UINTN StringSize;\r
\r
ASSERT (HiiHandle != NULL);\r
ASSERT (StringId != 0);\r
-\r
+ //\r
+ // Language must be specified if TryBestLanguage = FALSE.\r
+ //\r
+ ASSERT (!(!TryBestLanguage && Language == NULL));\r
//\r
// Initialize all allocated buffers to NULL\r
//\r
Language = "";\r
}\r
\r
- //\r
- // Get the best matching language from SupportedLanguages\r
- //\r
- BestLanguage = GetBestLanguage (\r
- SupportedLanguages,\r
- FALSE, // RFC 4646 mode\r
- Language, // Highest priority\r
- PlatformLanguage != NULL ? PlatformLanguage : "", // Next highest priority\r
- SupportedLanguages, // Lowest priority\r
- NULL\r
- );\r
- if (BestLanguage == NULL) {\r
- goto Error;\r
+ if (TryBestLanguage) {\r
+ //\r
+ // Get the best matching language from SupportedLanguages\r
+ //\r
+ BestLanguage = GetBestLanguage (\r
+ SupportedLanguages,\r
+ FALSE, // RFC 4646 mode\r
+ Language, // Highest priority\r
+ PlatformLanguage != NULL ? PlatformLanguage : "", // Next highest priority\r
+ SupportedLanguages, // Lowest priority\r
+ NULL\r
+ );\r
+ if (BestLanguage == NULL) {\r
+ goto Error;\r
+ }\r
+ } else {\r
+ BestLanguage = (CHAR8 *) Language;\r
}\r
\r
+\r
//\r
// Retrieve the size of the string in the string package for the BestLanguage\r
//\r
if (PlatformLanguage != NULL) {\r
FreePool (PlatformLanguage);\r
}\r
- if (BestLanguage != NULL) {\r
+ if (TryBestLanguage && BestLanguage != NULL) {\r
FreePool (BestLanguage);\r
}\r
\r