MdePkg/Include/Protocol/HiiString.h

   1 /** @file
   2   The file provides services to manipulate string data.
   3
   4   Copyright (c) 2006 - 2007, Intel Corporation
   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
   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 #ifndef __HII_STRING_H__
  16 #define __HII_STRING_H__
  17
  18 #define EFI_HII_STRING_PROTOCOL_GUID \
  19   { 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } }
  20
  21 #include <Protocol/HiiDatabase.h>
  22 #include <Protocol/HiiFont.h>
  23
  24
  25 typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL;
  26
  27
  28
  29 /**
  30   This function adds the string String to the group of strings
  31   owned by PackageList, with the specified font information
  32   StringFontInfo and returns a new string id.
  33
  34   @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
  35
  36   @param PackageList  Handle of the package list where this
  37                       string will be added.
  38
  39   @param Language Points to the language for the new string.
  40
  41   @param String   Points to the new null-terminated string.
  42
  43   @param StringFontInfo Points to the new string's font
  44                         information or NULL if the string should
  45                         have the default system font, size and
  46                         style. StringId On return, contains the
  47                         new strings id, which is unique within
  48                         PackageList.
  49
  50   @retval EFI_SUCCESS The new string was added successfully
  51
  52   @retval EFI_OUT_OF_RESOURCES  Could not add the string.
  53
  54   @retval EFI_INVALID_PARAMETER String is NULL or StringId is
  55                                 NULL or Language is NULL.
  56
  57
  58 **/
  59 typedef
  60 EFI_STATUS
  61 (EFIAPI *EFI_HII_NEW_STRING) (
  62   IN CONST  EFI_HII_STRING_PROTOCOL   *This,
  63   IN        EFI_HII_HANDLE            PackageList,
  64   OUT       EFI_STRING_ID             *StringId,
  65   IN CONST  CHAR8                     *Language,
  66   IN  CONST CHAR16                    *LanguageName, OPTIONAL
  67   IN CONST  EFI_STRING                String,
  68   IN CONST  EFI_FONT_INFO             *StringFontInfo OPTIONAL
  69 );
  70
  71
  72 /**
  73
  74   This function retrieves the string specified by StringId which
  75   is associated with the specified PackageList in the language
  76   Language and copies it into the buffer specified by String. If
  77   the string specified by StringId is not present in the
  78   specified PackageList, then EFI_NOT_FOUND is returned. If the
  79   string specified by StringId is present, but not in the
  80   specified language then EFI_INVALID_LANGUAGE is returned. If
  81   the buffer specified by StringSize is too small to hold the
  82   string, then EFI_BUFFER_TOO_SMALL will be returned. StringSize
  83   will be updated to the size of buffer actually required to
  84   hold the string.
  85
  86   @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
  87
  88   @param PackageList  The package list in the HII database to
  89                       search for the specified string.
  90
  91   @param Language   Points to the language for the retrieved
  92                     string.
  93
  94   @param StringId   The string's id, which is unique within
  95                     PackageList.
  96
  97   @param String   Points to the new null-terminated string.
  98
  99   @param StringSize On entry, points to the size of the buffer
 100                     pointed to by String, in bytes. On return,
 101                     points to the length of the string, in
 102                     bytes.
 103
 104   @param StringFontInfo   Points to the string's font
 105                           information or NULL if the string font
 106                           information is not desired.
 107
 108   @retval EFI_SUCCESS The string was returned successfully.
 109
 110   @retval EFI_NOT_FOUND The string specified by StringId is not
 111                         available.
 112
 113   @retval EFI_INVALID_LANGUAGE  The string specified by StringId
 114                                 is available but not in the
 115                                 specified language.
 116
 117   @retval EFI_BUFFER_TOO_SMALL  The buffer specified by
 118                                 StringLength is too small to
 119                                 hold the string.
 120
 121   @retval EFI_INVALID_PARAMETER The String or Language was NULL.
 122
 123 **/
 124 typedef
 125 EFI_STATUS
 126 (EFIAPI *EFI_HII_GET_STRING) (
 127   IN CONST  EFI_HII_STRING_PROTOCOL *This,
 128   IN CONST  CHAR8                   *Language,
 129   IN        EFI_HII_HANDLE          PackageList,
 130   IN        EFI_STRING_ID           StringId,
 131   OUT       EFI_STRING              String,
 132   IN OUT    UINTN                   *StringSize,
 133   OUT       EFI_FONT_INFO           **StringFontInfo OPTIONAL
 134 );
 135
 136 /**
 137   This function updates the string specified by StringId in the
 138   specified PackageList to the text specified by String and,
 139   optionally, the font information specified by StringFontInfo.
 140   There is no way to change the font information without changing
 141   the string text.
 142
 143   @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
 144
 145   @param PackageList  The package list containing the strings.
 146
 147   @param Language Points to the language for the updated string.
 148
 149   @param StringId The string id, which is unique within
 150                   PackageList.
 151
 152   @param String   Points to the new null-terminated string.
 153
 154   @param StringFontInfo Points to the string's font information
 155                         or NULL if the string font information
 156                         is not changed.
 157
 158   @retval EFI_SUCCESS   The string was successfully updated.
 159
 160   @retval EFI_NOT_FOUND The string specified by StringId is not
 161                         in the database.
 162
 163   @retval EFI_INVALID_PARAMETER The String or Language was NULL.
 164
 165   @retval EFI_OUT_OF_RESOURCES  The system is out of resources
 166                                 to accomplish the task.
 167
 168 **/
 169 typedef
 170 EFI_STATUS
 171 (EFIAPI *EFI_HII_SET_STRING) (
 172   IN CONST  EFI_HII_STRING_PROTOCOL *This,
 173   IN        EFI_HII_HANDLE          PackageList,
 174   IN        EFI_STRING_ID           StringId,
 175   IN CONST  CHAR8                   *Language,
 176   IN        EFI_STRING              String,
 177   IN CONST  EFI_FONT_INFO           *StringFontInfo OPTIONAL
 178 );
 179
 180
 181 /**
 182
 183   This function returns the list of supported languages.
 184
 185   @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
 186
 187   @param PackageList  The package list to examine.
 188
 189   @param Languages  Points to the buffer to hold the returned
 190                     string.
 191
 192   @param LanguageSize   On entry, points to the size of the
 193                         buffer pointed to by Languages, in
 194                         bytes. On return, points to the length
 195                         of Languages, in bytes.
 196
 197
 198   @retval EFI_SUCCESS The languages were returned successfully.
 199
 200   @retval EFI_BUFFER_TOO_SMALL  The LanguagesSize is too small
 201                                 to hold the list of supported
 202                                 languages. LanguageSize is
 203                                 updated to contain the required
 204                                 size.
 205
 206   @retval EFI_INVALID_PARAMETER Languages is NULL.
 207
 208
 209 **/
 210 typedef
 211 EFI_STATUS
 212 (EFIAPI *EFI_HII_GET_LANGUAGES) (
 213   IN CONST  EFI_HII_STRING_PROTOCOL   *This,
 214   IN        EFI_HII_HANDLE            PackageList,
 215   IN OUT    CHAR8                     *Languages,
 216   IN OUT    UINTN                     *LanguagesSize
 217 );
 218
 219
 220 /**
 221
 222   Each string package has associated with it a single primary
 223   language and zero or more secondary languages. This routine
 224   returns the secondary languages associated with a package list.
 225
 226   @param This   A pointer to the EFI_HII_STRING_PROTOCOL
 227                 instance.
 228
 229   @param PackageList  The package list to examine.
 230
 231   @param FirstLanguage  Points to the primary language.
 232
 233   @param Languages  are specified in the format specified in
 234                     Appendix M of the UEFI 2.0 specification.
 235
 236   @param SecondaryLanguages Points to the buffer to hold the
 237                             returned list of secondary languages
 238                             for the specified FirstLanguage. If
 239                             there are no secondary languages,
 240                             the function returns successfully,
 241                             but this is set to NULL.
 242
 243   @param SecondaryLanguageSize  On entry, points to the size of
 244                                 the buffer pointed to by
 245                                 Languages, in bytes. On return,
 246                                 points to the length of
 247                                 Languages in bytes.
 248
 249   @retval EFI_SUCCESS   Secondary languages correctly returned
 250
 251   @retval EFI_BUFFER_TOO_SMALL  The buffer specified by
 252                                 SecondLanguagesSize is too small
 253                                 to hold the returned
 254                                 information. SecondLanguageSize
 255                                 is updated to hold the size of
 256                                 the buffer required.
 257
 258   @retval EFI_INVALID_LANGUAGE  The language specified by
 259                                 FirstLanguage is not present in
 260                                 the specified package list.
 261
 262   @retval EFI_INVALID_PARAMETER FirstLanguage is NULL or
 263                                 SecondLanguage is NULL.
 264
 265 **/
 266 typedef
 267 EFI_STATUS
 268 (EFIAPI *EFI_HII_GET_2ND_LANGUAGES) (
 269   IN CONST  EFI_HII_STRING_PROTOCOL   *This,
 270   IN        EFI_HII_HANDLE            PackageList,
 271   IN CONST  CHAR8                     *FirstLanguage,
 272   IN OUT    CHAR8                     *SecondLanguages,
 273   IN OUT    UINTN                     *SecondLanguagesSize
 274 );
 275
 276
 277 /**
 278   Services to manipulate the string.
 279
 280   @param NewString  Add a new string. GetString Retrieve a
 281                     string and related string information.
 282
 283   @param SetString  Change a string.
 284
 285   @param GetLanguages   List the languages for a particular
 286                         package list.
 287
 288   @param GetSecondaryLanguages  List supported secondary
 289                                 languages for a particular
 290                                 primary language.
 291
 292 **/
 293 struct _EFI_HII_STRING_PROTOCOL {
 294   EFI_HII_NEW_STRING        NewString;
 295   EFI_HII_GET_STRING        GetString;
 296   EFI_HII_SET_STRING        SetString;
 297   EFI_HII_GET_LANGUAGES     GetLanguages;
 298   EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages;
 299 };
 300
 301
 302 extern EFI_GUID gEfiHiiStringProtocolGuid;
 303
 304 #endif
 305
 306