MdePkg/Include/Protocol/HiiString.h

   1 /** @file
   2   The file provides services to manipulate string data.
   3
   4 Copyright (c) 2006 - 2018, 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.
   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   @par Revision Reference:
  14   This Protocol was introduced in UEFI Specification 2.1.
  15
  16 **/
  17
  18 #ifndef __HII_STRING_H__
  19 #define __HII_STRING_H__
  20
  21 #include <Protocol/HiiFont.h>
  22
  23 #define EFI_HII_STRING_PROTOCOL_GUID \
  24   { 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } }
  25
  26 typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL;
  27
  28 /**
  29   This function adds the string String to the group of strings owned by PackageList, with the
  30   specified font information StringFontInfo, and returns a new string id.
  31   The new string identifier is guaranteed to be unique within the package list.
  32   That new string identifier is reserved for all languages in the package list.
  33
  34   @param  This                   A pointer to the EFI_HII_STRING_PROTOCOL instance.
  35   @param  PackageList            The handle of the package list where this string will
  36                                  be added.
  37   @param  StringId               On return, contains the new strings id, which is
  38                                  unique within PackageList.
  39   @param  Language               Points to the language for the new string.
  40   @param  LanguageName           Points to the printable language name to associate
  41                                  with the passed in  Language field.If LanguageName
  42                                  is not NULL and the string package header's
  43                                  LanguageName  associated with a given Language is
  44                                  not zero, the LanguageName being passed in will
  45                                  be ignored.
  46   @param  String                 Points to the new null-terminated string.
  47   @param  StringFontInfo         Points to the new string's font information or
  48                                  NULL if the string should have the default system
  49                                  font, size and style.
  50
  51   @retval EFI_SUCCESS            The new string was added successfully.
  52   @retval EFI_NOT_FOUND          The specified PackageList could not be found in
  53                                  database.
  54   @retval EFI_OUT_OF_RESOURCES   Could not add the string due to lack of resources.
  55   @retval EFI_INVALID_PARAMETER  String is NULL, or StringId is NULL, or Language is NULL.
  56   @retval EFI_INVALID_PARAMETER  The specified StringFontInfo does not exist in
  57                                  current database.
  58
  59 **/
  60 typedef
  61 EFI_STATUS
  62 (EFIAPI *EFI_HII_NEW_STRING)(
  63   IN CONST  EFI_HII_STRING_PROTOCOL   *This,
  64   IN        EFI_HII_HANDLE            PackageList,
  65   OUT       EFI_STRING_ID             *StringId,
  66   IN CONST  CHAR8                     *Language,
  67   IN  CONST CHAR16                    *LanguageName, OPTIONAL
  68   IN CONST  EFI_STRING                String,
  69   IN CONST  EFI_FONT_INFO             *StringFontInfo OPTIONAL
  70 );
  71
  72
  73 /**
  74   This function retrieves the string specified by StringId which is associated
  75   with the specified PackageList in the language Language and copies it into
  76   the buffer specified by String.
  77
  78   @param  This                   A pointer to the EFI_HII_STRING_PROTOCOL instance.
  79   @param  Language               Points to the language for the retrieved string.
  80   @param  PackageList            The package list in the HII database to search for
  81                                  the  specified string.
  82   @param  StringId               The string's id, which is unique within
  83                                  PackageList.
  84   @param  String                 Points to the new null-terminated string.
  85   @param  StringSize             On entry, points to the size of the buffer pointed
  86                                  to by  String, in bytes. On return, points to the
  87                                  length of the string, in bytes.
  88   @param  StringFontInfo         If not NULL, points to the string's font
  89                                  information.  It's caller's responsibility to free
  90                                  this buffer.
  91
  92   @retval EFI_SUCCESS            The string was returned successfully.
  93   @retval EFI_NOT_FOUND          The string specified by StringId is not available.
  94                                  The specified PackageList is not in the database.
  95   @retval EFI_INVALID_LANGUAGE    The string specified by StringId is available but
  96                                   not in the specified language.
  97   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by StringSize is too small to
  98                                  hold the string.
  99   @retval EFI_INVALID_PARAMETER   The Language or StringSize was NULL.
 100   @retval EFI_INVALID_PARAMETER   The value referenced by StringSize was not zero and
 101                                   String was NULL.
 102   @retval EFI_OUT_OF_RESOURCES    There were insufficient resources to complete the
 103                                   request.
 104
 105 **/
 106 typedef
 107 EFI_STATUS
 108 (EFIAPI *EFI_HII_GET_STRING)(
 109   IN CONST  EFI_HII_STRING_PROTOCOL *This,
 110   IN CONST  CHAR8                   *Language,
 111   IN        EFI_HII_HANDLE          PackageList,
 112   IN        EFI_STRING_ID           StringId,
 113   OUT       EFI_STRING              String,
 114   IN OUT    UINTN                   *StringSize,
 115   OUT       EFI_FONT_INFO           **StringFontInfo OPTIONAL
 116 );
 117
 118 /**
 119   This function updates the string specified by StringId in the specified PackageList to the text
 120   specified by String and, optionally, the font information specified by StringFontInfo.
 121
 122   @param  This                   A pointer to the EFI_HII_STRING_PROTOCOL instance.
 123   @param  PackageList            The package list containing the strings.
 124   @param  StringId               The string's id, which is unique within
 125                                  PackageList.
 126   @param  Language               Points to the language for the updated string.
 127   @param  String                 Points to the new null-terminated string.
 128   @param  StringFontInfo         Points to the string's font information or NULL if
 129                                  the  string font information is not changed.
 130
 131   @retval EFI_SUCCESS            The string was updated successfully.
 132   @retval EFI_NOT_FOUND          The string specified by StringId is not in the
 133                                  database.
 134   @retval EFI_INVALID_PARAMETER  The String or Language was NULL.
 135   @retval EFI_INVALID_PARAMETER  The specified StringFontInfo does not exist in
 136                                  current database.
 137   @retval EFI_OUT_OF_RESOURCES   The system is out of resources to accomplish the
 138                                  task.
 139
 140 **/
 141 typedef
 142 EFI_STATUS
 143 (EFIAPI *EFI_HII_SET_STRING)(
 144   IN CONST  EFI_HII_STRING_PROTOCOL *This,
 145   IN        EFI_HII_HANDLE          PackageList,
 146   IN        EFI_STRING_ID           StringId,
 147   IN CONST  CHAR8                   *Language,
 148   IN        EFI_STRING              String,
 149   IN CONST  EFI_FONT_INFO           *StringFontInfo OPTIONAL
 150 );
 151
 152
 153 /**
 154   This function returns the list of supported languages.
 155
 156   @param  This                   A pointer to the EFI_HII_STRING_PROTOCOL instance.
 157   @param  PackageList            The package list to examine.
 158   @param  Languages              Points to the buffer to hold the returned
 159                                  null-terminated ASCII string.
 160   @param  LanguagesSize          On entry, points to the size of the buffer pointed
 161                                  to by Languages, in bytes. On return, points to
 162                                  the length of Languages, in bytes.
 163
 164   @retval EFI_SUCCESS            The languages were returned successfully.
 165   @retval EFI_INVALID_PARAMETER  The LanguagesSize was NULL.
 166   @retval EFI_INVALID_PARAMETER  The value referenced by LanguagesSize is not zero
 167                                  and Languages is NULL.
 168   @retval EFI_BUFFER_TOO_SMALL   The LanguagesSize is too small to hold the list of
 169                                  supported languages. LanguageSize is updated to
 170                                  contain the required size.
 171   @retval EFI_NOT_FOUND          Could not find string package in specified
 172                                  packagelist.
 173
 174 **/
 175 typedef
 176 EFI_STATUS
 177 (EFIAPI *EFI_HII_GET_LANGUAGES)(
 178   IN CONST  EFI_HII_STRING_PROTOCOL   *This,
 179   IN        EFI_HII_HANDLE            PackageList,
 180   IN OUT    CHAR8                     *Languages,
 181   IN OUT    UINTN                     *LanguagesSize
 182 );
 183
 184
 185 /**
 186   Each string package has associated with it a single primary language and zero
 187   or more secondary languages. This routine returns the secondary languages
 188   associated with a package list.
 189
 190   @param  This                   A pointer to the EFI_HII_STRING_PROTOCOL instance.
 191   @param  PackageList            The package list to examine.
 192   @param  PrimaryLanguage        Points to the null-terminated ASCII string that specifies
 193                                  the primary language. Languages are specified in the
 194                                  format specified in Appendix M of the UEFI 2.0 specification.
 195   @param  SecondaryLanguages     Points to the buffer to hold the returned null-terminated
 196                                  ASCII string that describes the list of
 197                                  secondary languages for the specified
 198                                  PrimaryLanguage. If there are no secondary
 199                                  languages, the function returns successfully, but
 200                                  this is set to NULL.
 201   @param  SecondaryLanguagesSize On entry, points to the size of the buffer pointed
 202                                  to by SecondaryLanguages, in bytes. On return,
 203                                  points to the length of SecondaryLanguages in bytes.
 204
 205   @retval EFI_SUCCESS            Secondary languages were correctly returned.
 206   @retval EFI_INVALID_PARAMETER  PrimaryLanguage or SecondaryLanguagesSize was NULL.
 207   @retval EFI_INVALID_PARAMETER  The value referenced by SecondaryLanguagesSize is not
 208                                  zero and SecondaryLanguages is NULL.
 209   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by SecondaryLanguagesSize is
 210                                  too small to hold the returned information.
 211                                  SecondaryLanguageSize is updated to hold the size of
 212                                  the buffer required.
 213   @retval EFI_INVALID_LANGUAGE   The language specified by PrimaryLanguage is not
 214                                  present in the specified package list.
 215   @retval EFI_NOT_FOUND          The specified PackageList is not in the Database.
 216
 217 **/
 218 typedef
 219 EFI_STATUS
 220 (EFIAPI *EFI_HII_GET_2ND_LANGUAGES)(
 221   IN CONST  EFI_HII_STRING_PROTOCOL   *This,
 222   IN        EFI_HII_HANDLE            PackageList,
 223   IN CONST  CHAR8                     *PrimaryLanguage,
 224   IN OUT    CHAR8                     *SecondaryLanguages,
 225   IN OUT    UINTN                     *SecondaryLanguagesSize
 226 );
 227
 228
 229 ///
 230 /// Services to manipulate the string.
 231 ///
 232 struct _EFI_HII_STRING_PROTOCOL {
 233   EFI_HII_NEW_STRING        NewString;
 234   EFI_HII_GET_STRING        GetString;
 235   EFI_HII_SET_STRING        SetString;
 236   EFI_HII_GET_LANGUAGES     GetLanguages;
 237   EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages;
 238 };
 239
 240
 241 extern EFI_GUID gEfiHiiStringProtocolGuid;
 242
 243 #endif
 244