MdeModulePkg/Library/UefiHiiLib/HiiString.c

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