EdkCompatibilityPkg/Foundation/Efi/Protocol/HiiString/HiiString.h

   1 /*++
   2
   3 Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR>
   4 This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14     HiiString.h
  15
  16 Abstract:
  17
  18     EFI_HII_STRING_PROTOCOL from UEFI 2.1 specification.
  19
  20     This protocol provides interfaces to manipulate string data.
  21
  22 Revision History
  23
  24 --*/
  25
  26 #ifndef __EFI_HII_STRING_PROTOCOL_H__
  27 #define __EFI_HII_STRING_PROTOCOL_H__
  28
  29 #include EFI_PROTOCOL_DEFINITION (HiiFont)
  30
  31 //
  32 // Global ID for the Hii String Protocol.
  33 //
  34 #define EFI_HII_STRING_PROTOCOL_GUID \
  35   { \
  36     0xfd96974, 0x23aa, 0x4cdc, {0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a} \
  37   }
  38
  39 EFI_FORWARD_DECLARATION (EFI_HII_STRING_PROTOCOL);
  40
  41 typedef
  42 EFI_STATUS
  43 (EFIAPI *EFI_HII_NEW_STRING) (
  44   IN  CONST EFI_HII_STRING_PROTOCOL   *This,
  45   IN  EFI_HII_HANDLE                  PackageList,
  46   OUT EFI_STRING_ID                   *StringId,
  47   IN  CONST CHAR8                     *Language,
  48   IN  CONST CHAR16                    *LanguageName, OPTIONAL
  49   IN  CONST EFI_STRING                String,
  50   IN  CONST EFI_FONT_INFO             *StringFontInfo OPTIONAL
  51   )
  52 /*++
  53
  54   Routine Description:
  55     This function adds the string String to the group of strings owned by PackageList, with the
  56     specified font information StringFontInfo and returns a new string id.
  57     The new string identifier is guaranteed to be unique within the package list.
  58     That new string identifier is reserved for all languages in the package list.
  59
  60   Arguments:
  61     This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.
  62     PackageList       - Handle of the package list where this string will be added.
  63     StringId          - On return, contains the new strings id, which is unique within PackageList.
  64     Language          - Points to the language for the new string.
  65     LanguageName      - Points to the printable language name to associate with the passed in
  66                         Language field.If LanguageName is not NULL and the string package header's LanguageName
  67                         associated with a given Language is not zero, the LanguageName being passed
  68                         in will be ignored.
  69     String            - Points to the new null-terminated string.
  70     StringFontInfo    - Points to the new string's font information or NULL if the string should have the
  71                         default system font, size and style.
  72
  73   Returns:
  74     EFI_SUCCESS            - The new string was added successfully.
  75     EFI_NOT_FOUND          - The specified PackageList could not be found in database.
  76     EFI_OUT_OF_RESOURCES   - Could not add the string due to lack of resources.
  77     EFI_INVALID_PARAMETER  - String is NULL or StringId is NULL or Language is NULL.
  78
  79 --*/
  80 ;
  81
  82 typedef
  83 EFI_STATUS
  84 (EFIAPI *EFI_HII_GET_STRING) (
  85   IN  CONST EFI_HII_STRING_PROTOCOL   *This,
  86   IN  CONST CHAR8                     *Language,
  87   IN  EFI_HII_HANDLE                  PackageList,
  88   IN  EFI_STRING_ID                   StringId,
  89   OUT EFI_STRING                      String,
  90   IN  OUT UINTN                       *StringSize,
  91   OUT EFI_FONT_INFO                   **StringFontInfo OPTIONAL
  92   )
  93 /*++
  94
  95   Routine Description:
  96     This function retrieves the string specified by StringId which is associated
  97     with the specified PackageList in the language Language and copies it into
  98     the buffer specified by String.
  99
 100   Arguments:
 101     This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.
 102     Language          - Points to the language for the retrieved string.
 103     PackageList       - The package list in the HII database to search for the
 104                         specified string.
 105     StringId          - The string's id, which is unique within PackageList.
 106     String            - Points to the new null-terminated string.
 107     StringSize        - On entry, points to the size of the buffer pointed to by
 108                         String, in bytes. On return,
 109                         points to the length of the string, in bytes.
 110     StringFontInfo    - Points to a buffer that will be callee allocated and will
 111                         have the string's font information into this buffer.
 112                         The caller is responsible for freeing this buffer.
 113                         If the parameter is NULL a buffer will not be allocated
 114                         and the string font information will not be returned.
 115
 116   Returns:
 117     EFI_SUCCESS            - The string was returned successfully.
 118     EFI_NOT_FOUND          - The string specified by StringId is not available.
 119                              The specified PackageList is not in the database.
 120     EFI_INVALID_LANGUAGE   - The string specified by StringId is available but
 121                              not in the specified language.
 122     EFI_BUFFER_TOO_SMALL   - The buffer specified by StringSize is too small to
 123                              hold the string.
 124     EFI_INVALID_PARAMETER  - The String or Language or StringSize was NULL.
 125     EFI_OUT_OF_RESOURCES   - There were insufficient resources to complete the
 126                              request.
 127
 128 --*/
 129 ;
 130
 131 typedef
 132 EFI_STATUS
 133 (EFIAPI *EFI_HII_SET_STRING) (
 134   IN CONST EFI_HII_STRING_PROTOCOL    *This,
 135   IN EFI_HII_HANDLE                   PackageList,
 136   IN EFI_STRING_ID                    StringId,
 137   IN CONST CHAR8                      *Language,
 138   IN CONST EFI_STRING                 String,
 139   IN CONST EFI_FONT_INFO              *StringFontInfo OPTIONAL
 140   )
 141 /*++
 142
 143   Routine Description:
 144     This function updates the string specified by StringId in the specified PackageList to the text
 145     specified by String and, optionally, the font information specified by StringFontInfo.
 146
 147   Arguments:
 148     This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.
 149     PackageList       - The package list containing the strings.
 150     StringId          - The string's id, which is unique within PackageList.
 151     Language          - Points to the language for the updated string.
 152     String            - Points to the new null-terminated string.
 153     StringFontInfo    - Points to the string's font information or NULL if the string font information is not
 154                         changed.
 155
 156   Returns:
 157     EFI_SUCCESS            - The string was updated successfully.
 158     EFI_NOT_FOUND          - The string specified by StringId is not in the database.
 159                              The specified PackageList is not in the database.
 160     EFI_INVALID_PARAMETER  - The String or Language was NULL.
 161     EFI_OUT_OF_RESOURCES   - The system is out of resources to accomplish the task.
 162
 163 --*/
 164 ;
 165
 166 typedef
 167 EFI_STATUS
 168 (EFIAPI *EFI_HII_GET_LANGUAGES) (
 169   IN CONST EFI_HII_STRING_PROTOCOL    *This,
 170   IN EFI_HII_HANDLE                   PackageList,
 171   IN OUT CHAR8                        *Languages,
 172   IN OUT UINTN                        *LanguagesSize
 173   )
 174 /*++
 175
 176   Routine Description:
 177     This function returns the list of supported languages, in the format specified
 178     in Appendix M of UEFI 2.1 spec.
 179
 180   Arguments:
 181     This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.
 182     PackageList       - The package list to examine.
 183     Languages         - Points to the buffer to hold the returned string.
 184     LanguagesSize     - On entry, points to the size of the buffer pointed to by
 185                         Languages, in bytes. On
 186                         return, points to the length of Languages, in bytes.
 187
 188   Returns:
 189     EFI_SUCCESS            - The languages were returned successfully.
 190     EFI_INVALID_PARAMETER  - The Languages or LanguagesSize was NULL.
 191     EFI_BUFFER_TOO_SMALL   - The LanguagesSize is too small to hold the list of
 192                              supported languages. LanguageSize is updated to
 193                              contain the required size.
 194     EFI_NOT_FOUND          - The specified PackageList is not in the database.
 195
 196 --*/
 197 ;
 198
 199 typedef
 200 EFI_STATUS
 201 (EFIAPI *EFI_HII_GET_2ND_LANGUAGES) (
 202   IN CONST EFI_HII_STRING_PROTOCOL   *This,
 203   IN EFI_HII_HANDLE                  PackageList,
 204   IN CONST CHAR8                     *FirstLanguage,
 205   IN OUT CHAR8                       *SecondLanguages,
 206   IN OUT UINTN                       *SecondLanguagesSize
 207   )
 208 /*++
 209
 210   Routine Description:
 211     Each string package has associated with it a single primary language and zero
 212     or more secondary languages. This routine returns the secondary languages
 213     associated with a package list.
 214
 215   Arguments:
 216     This                   - A pointer to the EFI_HII_STRING_PROTOCOL instance.
 217     PackageList            - The package list to examine.
 218     FirstLanguage          - Points to the primary language.
 219     SecondaryLanguages     - Points to the buffer to hold the returned list of
 220                              secondary languages for the specified FirstLanguage.
 221                              If there are no secondary languages, the function
 222                              returns successfully, but this is set to NULL.
 223     SecondaryLanguageSize  - On entry, points to the size of the buffer pointed to
 224                              by SecondLanguages, in bytes. On return, points to
 225                              the length of SecondLanguages in bytes.
 226
 227   Returns:
 228     EFI_SUCCESS            - Secondary languages were correctly returned.
 229     EFI_INVALID_PARAMETER  - FirstLanguage or SecondLanguages or SecondLanguagesSize was NULL.
 230     EFI_BUFFER_TOO_SMALL   - The buffer specified by SecondLanguagesSize is
 231                              too small to hold the returned information.
 232                              SecondLanguageSize is updated to hold the size of
 233                              the buffer required.
 234     EFI_INVALID_LANGUAGE   - The language specified by FirstLanguage is not
 235                              present in the specified package list.
 236     EFI_NOT_FOUND          - The specified PackageList is not in the Database.
 237
 238 --*/
 239 ;
 240 //
 241 // Interface structure for the EFI_HII_STRING_PROTOCOL
 242 //
 243 struct _EFI_HII_STRING_PROTOCOL {
 244   EFI_HII_NEW_STRING        NewString;
 245   EFI_HII_GET_STRING        GetString;
 246   EFI_HII_SET_STRING        SetString;
 247   EFI_HII_GET_LANGUAGES     GetLanguages;
 248   EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages;
 249 };
 250
 251 extern EFI_GUID gEfiHiiStringProtocolGuid;
 252
 253 #endif