MdeModulePkg/Library/UefiHiiLib/HiiString.c

   1 /** @file
   2   HII Library implementation that uses DXE protocols and services.
   3
   4   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9
  10 #include "InternalHiiLib.h"
  11
  12 /**
  13   This function create a new string in String Package or updates an existing
  14   string in a String Package.  If StringId is 0, then a new string is added to
  15   a String Package.  If StringId is not zero, then a string in String Package is
  16   updated.  If SupportedLanguages is NULL, then the string is added or updated
  17   for all the languages that the String Package supports.  If SupportedLanguages
  18   is not NULL, then the string is added or updated for the set of languages
  19   specified by SupportedLanguages.
  20
  21   If HiiHandle is NULL, then ASSERT().
  22   If String is NULL, then ASSERT().
  23
  24   @param[in]  HiiHandle           A handle that was previously registered in the
  25                                   HII Database.
  26   @param[in]  StringId            If zero, then a new string is created in the
  27                                   String Package associated with HiiHandle.  If
  28                                   non-zero, then the string specified by StringId
  29                                   is updated in the String Package  associated
  30                                   with HiiHandle.
  31   @param[in]  String              A pointer to the Null-terminated Unicode string
  32                                   to add or update in the String Package associated
  33                                   with HiiHandle.
  34   @param[in]  SupportedLanguages  A pointer to a Null-terminated ASCII string of
  35                                   language codes.  If this parameter is NULL, then
  36                                   String is added or updated in the String Package
  37                                   associated with HiiHandle for all the languages
  38                                   that the String Package supports.  If this
  39                                   parameter is not NULL, then then String is added
  40                                   or updated in the String Package associated with
  41                                   HiiHandle for the set oflanguages specified by
  42                                   SupportedLanguages.  The format of
  43                                   SupportedLanguages must follow the language
  44                                   format assumed the HII Database.
  45
  46   @retval 0      The string could not be added or updated in the String Package.
  47   @retval Other  The EFI_STRING_ID of the newly added or updated string.
  48
  49 **/
  50 EFI_STRING_ID
  51 EFIAPI
  52 HiiSetString (
  53   IN EFI_HII_HANDLE    HiiHandle,
  54   IN EFI_STRING_ID     StringId,            OPTIONAL
  55   IN CONST EFI_STRING  String,
  56   IN CONST CHAR8       *SupportedLanguages  OPTIONAL
  57   )
  58 {
  59   EFI_STATUS     Status;
  60   CHAR8          *AllocatedLanguages;
  61   CHAR8          *Supported;
  62   CHAR8          *Language;
  63
  64   ASSERT (HiiHandle != NULL);
  65   ASSERT (String != NULL);
  66
  67   if (SupportedLanguages == NULL) {
  68     //
  69     // Retrieve the languages that the package specified by HiiHandle supports
  70     //
  71     AllocatedLanguages = HiiGetSupportedLanguages (HiiHandle);
  72   } else {
  73     //
  74     // Allocate a copy of the SupportLanguages string that passed in
  75     //
  76     AllocatedLanguages = AllocateCopyPool (AsciiStrSize (SupportedLanguages), SupportedLanguages);
  77   }
  78
  79   //
  80   // If there are not enough resources for the supported languages string, then return a StringId of 0
  81   //
  82   if (AllocatedLanguages == NULL) {
  83     return (EFI_STRING_ID)(0);
  84   }
  85
  86   Status = EFI_INVALID_PARAMETER;
  87   //
  88   // Loop through each language that the string supports
  89   //
  90   for (Supported = AllocatedLanguages; *Supported != '\0'; ) {
  91     //
  92     // Cache a pointer to the beginning of the current language in the list of languages
  93     //
  94     Language = Supported;
  95
  96     //
  97     // Search for the next language separator and replace it with a Null-terminator
  98     //
  99     for (; *Supported != 0 && *Supported != ';'; Supported++);
 100     if (*Supported != 0) {
 101       *(Supported++) = '\0';
 102     }
 103
 104     if ((SupportedLanguages == NULL) && AsciiStrnCmp (Language, UEFI_CONFIG_LANG, AsciiStrLen (UEFI_CONFIG_LANG)) == 0) {
 105       //
 106       // Skip string package used for keyword protocol.
 107       //
 108       continue;
 109     }
 110
 111     //
 112     // If StringId is 0, then call NewString().  Otherwise, call SetString()
 113     //
 114     if (StringId == (EFI_STRING_ID)(0)) {
 115       Status = gHiiString->NewString (gHiiString, HiiHandle, &StringId, Language, NULL, String, NULL);
 116     } else {
 117       Status = gHiiString->SetString (gHiiString, HiiHandle, StringId, Language, String, NULL);
 118     }
 119
 120     //
 121     // If there was an error, then break out of the loop and return a StringId of 0
 122     //
 123     if (EFI_ERROR (Status)) {
 124       break;
 125     }
 126   }
 127
 128   //
 129   // Free the buffer of supported languages
 130   //
 131   FreePool (AllocatedLanguages);
 132
 133   if (EFI_ERROR (Status)) {
 134     return (EFI_STRING_ID)(0);
 135   } else {
 136     return StringId;
 137   }
 138 }
 139
 140
 141 /**
 142   Retrieves a string from a string package names by GUID in a specific language.
 143   If the language is not specified, then a string from a string package in the
 144   current platform  language is retrieved.  If the string can not be retrieved
 145   using the specified language or the current platform language, then the string
 146   is retrieved from the string package in the first language the string package
 147   supports.  The returned string is allocated using AllocatePool().  The caller
 148   is responsible for freeing the allocated buffer using FreePool().
 149
 150   If PackageListGuid is NULL, then ASSERT().
 151   If StringId is 0, then ASSERT.
 152
 153   @param[in]  PackageListGuid  The GUID of a package list that was previously
 154                                registered in the HII Database.
 155   @param[in]  StringId         The identifier of the string to retrieved from the
 156                                string package associated with PackageListGuid.
 157   @param[in]  Language         The language of the string to retrieve.  If this
 158                                parameter is NULL, then the current platform
 159                                language is used.  The format of Language must
 160                                follow the language format assumed the HII Database.
 161
 162   @retval NULL   The package list specified by PackageListGuid is not present in the
 163                  HII Database.
 164   @retval NULL   The string specified by StringId is not present in the string package.
 165   @retval Other  The string was returned.
 166
 167 **/
 168 EFI_STRING
 169 EFIAPI
 170 HiiGetPackageString (
 171   IN CONST EFI_GUID  *PackageListGuid,
 172   IN EFI_STRING_ID   StringId,
 173   IN CONST CHAR8     *Language  OPTIONAL
 174   )
 175 {
 176   EFI_HANDLE  *HiiHandleBuffer;
 177   EFI_HANDLE  HiiHandle;
 178
 179   ASSERT (PackageListGuid != NULL);
 180
 181   HiiHandleBuffer = HiiGetHiiHandles (PackageListGuid);
 182   if (HiiHandleBuffer == NULL) {
 183     return NULL;
 184   }
 185
 186   HiiHandle = HiiHandleBuffer[0];
 187   FreePool (HiiHandleBuffer);
 188
 189   return HiiGetString (HiiHandle, StringId, Language);
 190 }
 191
 192 /**
 193   Retrieves a string from a string package in a specific language.  If the language
 194   is not specified, then a string from a string package in the current platform
 195   language is retrieved.  If the string can not be retrieved using the specified
 196   language or the current platform language, then the string is retrieved from
 197   the string package in the first language the string package supports.  The
 198   returned string is allocated using AllocatePool().  The caller is responsible
 199   for freeing the allocated buffer using FreePool().
 200
 201   If HiiHandle is NULL, then ASSERT().
 202   If StringId is 0, then ASSET.
 203
 204   @param[in]  HiiHandle  A handle that was previously registered in the HII Database.
 205   @param[in]  StringId   The identifier of the string to retrieved from the string
 206                          package associated with HiiHandle.
 207   @param[in]  Language   The language of the string to retrieve.  If this parameter
 208                          is NULL, then the current platform language is used.  The
 209                          format of Language must follow the language format assumed
 210                          the HII Database.
 211
 212   @retval NULL   The string specified by StringId is not present in the string package.
 213   @retval Other  The string was returned.
 214
 215 **/
 216 EFI_STRING
 217 EFIAPI
 218 HiiGetString (
 219   IN EFI_HII_HANDLE  HiiHandle,
 220   IN EFI_STRING_ID   StringId,
 221   IN CONST CHAR8     *Language  OPTIONAL
 222   )
 223 {
 224   EFI_STATUS  Status;
 225   UINTN       StringSize;
 226   CHAR16      TempString;
 227   EFI_STRING  String;
 228   CHAR8       *SupportedLanguages;
 229   CHAR8       *PlatformLanguage;
 230   CHAR8       *BestLanguage;
 231
 232   ASSERT (HiiHandle != NULL);
 233   ASSERT (StringId != 0);
 234
 235   //
 236   // Initialize all allocated buffers to NULL
 237   //
 238   SupportedLanguages = NULL;
 239   PlatformLanguage   = NULL;
 240   BestLanguage       = NULL;
 241   String             = NULL;
 242
 243   //
 244   // Get the languages that the package specified by HiiHandle supports
 245   //
 246   SupportedLanguages = HiiGetSupportedLanguages (HiiHandle);
 247   if (SupportedLanguages == NULL) {
 248     goto Error;
 249   }
 250
 251   //
 252   // Get the current platform language setting
 253   //
 254   GetEfiGlobalVariable2 (L"PlatformLang", (VOID**)&PlatformLanguage, NULL);
 255
 256   //
 257   // If Languag is NULL, then set it to an empty string, so it will be
 258   // skipped by GetBestLanguage()
 259   //
 260   if (Language == NULL) {
 261     Language = "";
 262   }
 263
 264   //
 265   // Get the best matching language from SupportedLanguages
 266   //
 267   BestLanguage = GetBestLanguage (
 268                    SupportedLanguages,
 269                    FALSE,                                             // RFC 4646 mode
 270                    Language,                                          // Highest priority
 271                    PlatformLanguage != NULL ? PlatformLanguage : "",  // Next highest priority
 272                    SupportedLanguages,                                // Lowest priority
 273                    NULL
 274                    );
 275   if (BestLanguage == NULL) {
 276     goto Error;
 277   }
 278
 279   //
 280   // Retrieve the size of the string in the string package for the BestLanguage
 281   //
 282   StringSize = 0;
 283   Status = gHiiString->GetString (
 284                          gHiiString,
 285                          BestLanguage,
 286                          HiiHandle,
 287                          StringId,
 288                          &TempString,
 289                          &StringSize,
 290                          NULL
 291                          );
 292   //
 293   // If GetString() returns EFI_SUCCESS for a zero size,
 294   // then there are no supported languages registered for HiiHandle.  If GetString()
 295   // returns an error other than EFI_BUFFER_TOO_SMALL, then HiiHandle is not present
 296   // in the HII Database
 297   //
 298   if (Status != EFI_BUFFER_TOO_SMALL) {
 299     goto Error;
 300   }
 301
 302   //
 303   // Allocate a buffer for the return string
 304   //
 305   String = AllocateZeroPool (StringSize);
 306   if (String == NULL) {
 307     goto Error;
 308   }
 309
 310   //
 311   // Retrieve the string from the string package
 312   //
 313   Status = gHiiString->GetString (
 314                          gHiiString,
 315                          BestLanguage,
 316                          HiiHandle,
 317                          StringId,
 318                          String,
 319                          &StringSize,
 320                          NULL
 321                          );
 322   if (EFI_ERROR (Status)) {
 323     //
 324     // Free the buffer and return NULL if the supported languages can not be retrieved.
 325     //
 326     FreePool (String);
 327     String = NULL;
 328   }
 329
 330 Error:
 331   //
 332   // Free allocated buffers
 333   //
 334   if (SupportedLanguages != NULL) {
 335     FreePool (SupportedLanguages);
 336   }
 337   if (PlatformLanguage != NULL) {
 338     FreePool (PlatformLanguage);
 339   }
 340   if (BestLanguage != NULL) {
 341     FreePool (BestLanguage);
 342   }
 343
 344   //
 345   // Return the Null-terminated Unicode string
 346   //
 347   return String;
 348 }
 349