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