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