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

   1 /*++
   2
   3 Copyright (c) 2007, 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
  58   Arguments:
  59     This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.
  60     PackageList       - Handle of the package list where this string will be added.
  61     StringId          - On return, contains the new strings id, which is unique within PackageList.
  62     Language          - Points to the language for the new string.
  63     LanguageName      - Points to the printable language name to associate with the passed in
  64                         Language field.If LanguageName is not NULL and the string package header's LanguageName
  65                         associated with a given Language is not zero, the LanguageName being passed
  66                         in will be ignored.
  67     String            - Points to the new null-terminated string.
  68     StringFontInfo    - Points to the new string's font information or NULL if the string should have the
  69                         default system font, size and style.
  70
  71   Returns:
  72     EFI_SUCCESS            - The new string was added successfully.
  73     EFI_NOT_FOUND          - The specified PackageList could not be found in database.
  74     EFI_OUT_OF_RESOURCES   - Could not add the string due to lack of resources.
  75     EFI_INVALID_PARAMETER  - String is NULL or StringId is NULL or Language is NULL.
  76
  77 --*/
  78 ;
  79
  80 typedef
  81 EFI_STATUS
  82 (EFIAPI *EFI_HII_GET_STRING) (
  83   IN  CONST EFI_HII_STRING_PROTOCOL   *This,
  84   IN  CONST CHAR8                     *Language,
  85   IN  EFI_HII_HANDLE                  PackageList,
  86   IN  EFI_STRING_ID                   StringId,
  87   OUT EFI_STRING                      String,
  88   IN  OUT UINTN                       *StringSize,
  89   OUT EFI_FONT_INFO                   **StringFontInfo OPTIONAL
  90   )
  91 /*++
  92
  93   Routine Description:
  94     This function retrieves the string specified by StringId which is associated
  95     with the specified PackageList in the language Language and copies it into
  96     the buffer specified by String.
  97
  98   Arguments:
  99     This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.
 100     Language          - Points to the language for the retrieved string.
 101     PackageList       - The package list in the HII database to search for the
 102                         specified string.
 103     StringId          - The string's id, which is unique within PackageList.
 104     String            - Points to the new null-terminated string.
 105     StringSize        - On entry, points to the size of the buffer pointed to by
 106                         String, in bytes. On return,
 107                         points to the length of the string, in bytes.
 108     StringFontInfo    - If not NULL, points to the string's font information.
 109                         It's caller's responsibility to free this buffer.
 110
 111   Returns:
 112     EFI_SUCCESS            - The string was returned successfully.
 113     EFI_NOT_FOUND          - The string specified by StringId is not available.
 114     EFI_BUFFER_TOO_SMALL   - The buffer specified by StringSize is too small to
 115                              hold the string.
 116     EFI_INVALID_PARAMETER  - The String or Language or StringSize was NULL.
 117     EFI_OUT_OF_RESOURCES   - There were insufficient resources to complete the
 118                              request.
 119
 120 --*/
 121 ;
 122
 123 typedef
 124 EFI_STATUS
 125 (EFIAPI *EFI_HII_SET_STRING) (
 126   IN CONST EFI_HII_STRING_PROTOCOL    *This,
 127   IN EFI_HII_HANDLE                   PackageList,
 128   IN EFI_STRING_ID                    StringId,
 129   IN CONST CHAR8                      *Language,
 130   IN CONST EFI_STRING                 String,
 131   IN CONST EFI_FONT_INFO              *StringFontInfo OPTIONAL
 132   )
 133 /*++
 134
 135   Routine Description:
 136     This function updates the string specified by StringId in the specified PackageList to the text
 137     specified by String and, optionally, the font information specified by StringFontInfo.
 138
 139   Arguments:
 140     This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.
 141     PackageList       - The package list containing the strings.
 142     StringId          - The string's id, which is unique within PackageList.
 143     Language          - Points to the language for the updated string.
 144     String            - Points to the new null-terminated string.
 145     StringFontInfo    - Points to the string's font information or NULL if the string font information is not
 146                         changed.
 147
 148   Returns:
 149     EFI_SUCCESS            - The string was updated successfully.
 150     EFI_NOT_FOUND          - The string specified by StringId is not in the database.
 151     EFI_INVALID_PARAMETER  - The String or Language was NULL.
 152     EFI_OUT_OF_RESOURCES   - The system is out of resources to accomplish the task.
 153
 154 --*/
 155 ;
 156
 157 typedef
 158 EFI_STATUS
 159 (EFIAPI *EFI_HII_GET_LANGUAGES) (
 160   IN CONST EFI_HII_STRING_PROTOCOL    *This,
 161   IN EFI_HII_HANDLE                   PackageList,
 162   IN OUT CHAR8                        *Languages,
 163   IN OUT UINTN                        *LanguagesSize
 164   )
 165 /*++
 166
 167   Routine Description:
 168     This function returns the list of supported languages, in the format specified
 169     in Appendix M of UEFI 2.1 spec.
 170
 171   Arguments:
 172     This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.
 173     PackageList       - The package list to examine.
 174     Languages         - Points to the buffer to hold the returned string.
 175     LanguagesSize     - On entry, points to the size of the buffer pointed to by
 176                         Languages, in bytes. On
 177                         return, points to the length of Languages, in bytes.
 178
 179   Returns:
 180     EFI_SUCCESS            - The languages were returned successfully.
 181     EFI_INVALID_PARAMETER  - The Languages or LanguagesSize was NULL.
 182     EFI_BUFFER_TOO_SMALL   - The LanguagesSize is too small to hold the list of
 183                              supported languages. LanguageSize is updated to
 184                              contain the required size.
 185
 186 --*/
 187 ;
 188
 189 typedef
 190 EFI_STATUS
 191 (EFIAPI *EFI_HII_GET_2ND_LANGUAGES) (
 192   IN CONST EFI_HII_STRING_PROTOCOL   *This,
 193   IN EFI_HII_HANDLE                  PackageList,
 194   IN CONST CHAR8                     *FirstLanguage,
 195   IN OUT CHAR8                       *SecondLanguages,
 196   IN OUT UINTN                       *SecondLanguagesSize
 197   )
 198 /*++
 199
 200   Routine Description:
 201     Each string package has associated with it a single primary language and zero
 202     or more secondary languages. This routine returns the secondary languages
 203     associated with a package list.
 204
 205   Arguments:
 206     This                   - A pointer to the EFI_HII_STRING_PROTOCOL instance.
 207     PackageList            - The package list to examine.
 208     FirstLanguage          - Points to the primary language.
 209     SecondaryLanguages     - Points to the buffer to hold the returned list of
 210                              secondary languages for the specified FirstLanguage.
 211                              If there are no secondary languages, the function
 212                              returns successfully, but this is set to NULL.
 213     SecondaryLanguageSize  - On entry, points to the size of the buffer pointed to
 214                              by SecondLanguages, in bytes. On return, points to
 215                              the length of SecondLanguages in bytes.
 216
 217   Returns:
 218     EFI_SUCCESS            - Secondary languages were correctly returned.
 219     EFI_INVALID_PARAMETER  - FirstLanguage or SecondLanguages or SecondLanguagesSize was NULL.
 220     EFI_BUFFER_TOO_SMALL   - The buffer specified by SecondLanguagesSize is
 221                              too small to hold the returned information.
 222                              SecondLanguageSize is updated to hold the size of
 223                              the buffer required.
 224
 225 --*/
 226 ;
 227 //
 228 // Interface structure for the EFI_HII_STRING_PROTOCOL
 229 //
 230 struct _EFI_HII_STRING_PROTOCOL {
 231   EFI_HII_NEW_STRING        NewString;
 232   EFI_HII_GET_STRING        GetString;
 233   EFI_HII_SET_STRING        SetString;
 234   EFI_HII_GET_LANGUAGES     GetLanguages;
 235   EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages;
 236 };
 237
 238 extern EFI_GUID gEfiHiiStringProtocolGuid;
 239
 240 #endif