MdePkg/Include/Protocol/HiiString.h

   1 /** @file
   2   The file provides services to manipulate string data.
   3
   4   Copyright (c) 2006 - 2008, 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 a buffer that will be callee allocated and will
 105                       have the string's font information into this buffer.
 106                       The caller is responsible for freeing this buffer.
 107                       If the parameter is NULL a buffer will not be allocated
 108                       and the string font information will not be returned.
 109
 110   @retval EFI_SUCCESS The string was returned successfully.
 111
 112   @retval EFI_NOT_FOUND The string specified by StringId is not
 113                         available. The specified PackageList is not in the database.
 114
 115   @retval EFI_INVALID_LANGUAGE  The string specified by StringId
 116                                 is available but not in the
 117                                 specified language.
 118
 119   @retval EFI_BUFFER_TOO_SMALL  The buffer specified by
 120                                 StringLength is too small to
 121                                 hold the string.
 122
 123   @retval EFI_INVALID_PARAMETER The String or Language was NULL.
 124
 125 **/
 126 typedef
 127 EFI_STATUS
 128 (EFIAPI *EFI_HII_GET_STRING) (
 129   IN CONST  EFI_HII_STRING_PROTOCOL *This,
 130   IN CONST  CHAR8                   *Language,
 131   IN        EFI_HII_HANDLE          PackageList,
 132   IN        EFI_STRING_ID           StringId,
 133   OUT       EFI_STRING              String,
 134   IN OUT    UINTN                   *StringSize,
 135   OUT       EFI_FONT_INFO           **StringFontInfo OPTIONAL
 136 );
 137
 138 /**
 139   This function updates the string specified by StringId in the
 140   specified PackageList to the text specified by String and,
 141   optionally, the font information specified by StringFontInfo.
 142   There is no way to change the font information without changing
 143   the string text.
 144
 145   @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
 146
 147   @param PackageList  The package list containing the strings.
 148
 149   @param Language Points to the language for the updated string.
 150
 151   @param StringId The string id, which is unique within
 152                   PackageList.
 153
 154   @param String   Points to the new null-terminated string.
 155
 156   @param StringFontInfo Points to the string's font information
 157                         or NULL if the string font information
 158                         is not changed.
 159
 160   @retval EFI_SUCCESS   The string was successfully updated.
 161
 162   @retval EFI_NOT_FOUND The string specified by StringId is not
 163                         in the database. The specified PackageList is not in the database.
 164
 165   @retval EFI_INVALID_PARAMETER The String or Language was NULL.
 166
 167   @retval EFI_OUT_OF_RESOURCES  The system is out of resources
 168                                 to accomplish the task.
 169
 170 **/
 171 typedef
 172 EFI_STATUS
 173 (EFIAPI *EFI_HII_SET_STRING) (
 174   IN CONST  EFI_HII_STRING_PROTOCOL *This,
 175   IN        EFI_HII_HANDLE          PackageList,
 176   IN        EFI_STRING_ID           StringId,
 177   IN CONST  CHAR8                   *Language,
 178   IN        EFI_STRING              String,
 179   IN CONST  EFI_FONT_INFO           *StringFontInfo OPTIONAL
 180 );
 181
 182
 183 /**
 184
 185   This function returns the list of supported languages.
 186
 187   @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.
 188
 189   @param PackageList  The package list to examine.
 190
 191   @param Languages  Points to the buffer to hold the returned
 192                     string.
 193
 194   @param LanguageSize   On entry, points to the size of the
 195                         buffer pointed to by Languages, in
 196                         bytes. On return, points to the length
 197                         of Languages, in bytes.
 198
 199
 200   @retval EFI_SUCCESS The languages were returned successfully.
 201
 202   @retval EFI_BUFFER_TOO_SMALL  The LanguagesSize is too small
 203                                 to hold the list of supported
 204                                 languages. LanguageSize is
 205                                 updated to contain the required
 206                                 size.
 207
 208   @retval EFI_INVALID_PARAMETER Languages or LanguagesSize is NULL.
 209   @retval EFI_NOT_FOUND The specified PackageList is not in the database.
 210
 211
 212 **/
 213 typedef
 214 EFI_STATUS
 215 (EFIAPI *EFI_HII_GET_LANGUAGES) (
 216   IN CONST  EFI_HII_STRING_PROTOCOL   *This,
 217   IN        EFI_HII_HANDLE            PackageList,
 218   IN OUT    CHAR8                     *Languages,
 219   IN OUT    UINTN                     *LanguagesSize
 220 );
 221
 222
 223 /**
 224
 225   Each string package has associated with it a single primary
 226   language and zero or more secondary languages. This routine
 227   returns the secondary languages associated with a package list.
 228
 229   @param This   A pointer to the EFI_HII_STRING_PROTOCOL
 230                 instance.
 231
 232   @param PackageList  The package list to examine.
 233
 234   @param FirstLanguage  Points to the primary language.
 235
 236   @param Languages  are specified in the format specified in
 237                     Appendix M of the UEFI 2.0 specification.
 238
 239   @param SecondaryLanguages Points to the buffer to hold the
 240                             returned list of secondary languages
 241                             for the specified FirstLanguage. If
 242                             there are no secondary languages,
 243                             the function returns successfully,
 244                             but this is set to NULL.
 245
 246   @param SecondaryLanguageSize  On entry, points to the size of
 247                                 the buffer pointed to by
 248                                 Languages, in bytes. On return,
 249                                 points to the length of
 250                                 Languages in bytes.
 251
 252   @retval EFI_SUCCESS   Secondary languages correctly returned
 253
 254   @retval EFI_BUFFER_TOO_SMALL  The buffer specified by
 255                                 SecondLanguagesSize is too small
 256                                 to hold the returned
 257                                 information. SecondLanguageSize
 258                                 is updated to hold the size of
 259                                 the buffer required.
 260
 261   @retval EFI_INVALID_LANGUAGE  The language specified by
 262                                 FirstLanguage is not present in
 263                                 the specified package list.
 264
 265   @retval EFI_INVALID_PARAMETER FirstLanguage is NULL or
 266                                 SecondLanguage is NULL.
 267   @retval EFI_NOT_FOUND The specified PackageList is not in the database.
 268
 269 **/
 270 typedef
 271 EFI_STATUS
 272 (EFIAPI *EFI_HII_GET_2ND_LANGUAGES) (
 273   IN CONST  EFI_HII_STRING_PROTOCOL   *This,
 274   IN        EFI_HII_HANDLE            PackageList,
 275   IN CONST  CHAR8                     *FirstLanguage,
 276   IN OUT    CHAR8                     *SecondLanguages,
 277   IN OUT    UINTN                     *SecondLanguagesSize
 278 );
 279
 280
 281 /**
 282   Services to manipulate the string.
 283
 284   @param NewString  Add a new string. GetString Retrieve a
 285                     string and related string information.
 286
 287   @param SetString  Change a string.
 288
 289   @param GetLanguages   List the languages for a particular
 290                         package list.
 291
 292   @param GetSecondaryLanguages  List supported secondary
 293                                 languages for a particular
 294                                 primary language.
 295
 296 **/
 297 struct _EFI_HII_STRING_PROTOCOL {
 298   EFI_HII_NEW_STRING        NewString;
 299   EFI_HII_GET_STRING        GetString;
 300   EFI_HII_SET_STRING        SetString;
 301   EFI_HII_GET_LANGUAGES     GetLanguages;
 302   EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages;
 303 };
 304
 305
 306 extern EFI_GUID gEfiHiiStringProtocolGuid;
 307
 308 #endif
 309
 310