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 254
