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