1 /** @file 2 The file provides services to manipulate string data. 3 4 Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> 5 This program and the accompanying materials are licensed and made available under 6 the terms and conditions of the BSD License that accompanies this distribution. 7 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 #include <Protocol/HiiFont.h> 19 20 #define EFI_HII_STRING_PROTOCOL_GUID \ 21 { 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } } 22 23 typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL; 24 25 /** 26 This function adds the string String to the group of strings owned by PackageList, with the 27 specified font information StringFontInfo, and returns a new string id. 28 The new string identifier is guaranteed to be unique within the package list. 29 That new string identifier is reserved for all languages in the package list. 30 31 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance. 32 @param PackageList The 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 The specified PackageList is not in the database. 92 @retval EFI_INVALID_LANGUAGE The string specified by StringId is available but 93 not in the specified language. 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 Language or StringSize was NULL. 97 @retval EFI_INVALID_PARAMETER The value referenced by StringSize was not zero and 98 String was NULL. 99 @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the 100 request. 101 102 **/ 103 typedef 104 EFI_STATUS 105 (EFIAPI *EFI_HII_GET_STRING)( 106 IN CONST EFI_HII_STRING_PROTOCOL *This, 107 IN CONST CHAR8 *Language, 108 IN EFI_HII_HANDLE PackageList, 109 IN EFI_STRING_ID StringId, 110 OUT EFI_STRING String, 111 IN OUT UINTN *StringSize, 112 OUT EFI_FONT_INFO **StringFontInfo OPTIONAL 113 ); 114 115 /** 116 This function updates the string specified by StringId in the specified PackageList to the text 117 specified by String and, optionally, the font information specified by StringFontInfo. 118 119 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance. 120 @param PackageList The package list containing the strings. 121 @param StringId The string's id, which is unique within 122 PackageList. 123 @param Language Points to the language for the updated string. 124 @param String Points to the new null-terminated string. 125 @param StringFontInfo Points to the string's font information or NULL if 126 the string font information is not changed. 127 128 @retval EFI_SUCCESS The string was updated successfully. 129 @retval EFI_NOT_FOUND The string specified by StringId is not in the 130 database. 131 @retval EFI_INVALID_PARAMETER The String or Language was NULL. 132 @retval EFI_INVALID_PARAMETER The specified StringFontInfo does not exist in 133 current database. 134 @retval EFI_OUT_OF_RESOURCES The system is out of resources to accomplish the 135 task. 136 137 **/ 138 typedef 139 EFI_STATUS 140 (EFIAPI *EFI_HII_SET_STRING)( 141 IN CONST EFI_HII_STRING_PROTOCOL *This, 142 IN EFI_HII_HANDLE PackageList, 143 IN EFI_STRING_ID StringId, 144 IN CONST CHAR8 *Language, 145 IN EFI_STRING String, 146 IN CONST EFI_FONT_INFO *StringFontInfo OPTIONAL 147 ); 148 149 150 /** 151 This function returns the list of supported languages. 152 153 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance. 154 @param PackageList The package list to examine. 155 @param Languages Points to the buffer to hold the returned 156 null-terminated ASCII string. 157 @param LanguagesSize On entry, points to the size of the buffer pointed 158 to by Languages, in bytes. On return, points to 159 the length of Languages, in bytes. 160 161 @retval EFI_SUCCESS The languages were returned successfully. 162 @retval EFI_INVALID_PARAMETER The LanguagesSize was NULL. 163 @retval EFI_INVALID_PARAMETER The value referenced by LanguagesSize is not zero 164 and Languages is NULL. 165 @retval EFI_BUFFER_TOO_SMALL The LanguagesSize is too small to hold the list of 166 supported languages. LanguageSize is updated to 167 contain the required size. 168 @retval EFI_NOT_FOUND Could not find string package in specified 169 packagelist. 170 171 **/ 172 typedef 173 EFI_STATUS 174 (EFIAPI *EFI_HII_GET_LANGUAGES)( 175 IN CONST EFI_HII_STRING_PROTOCOL *This, 176 IN EFI_HII_HANDLE PackageList, 177 IN OUT CHAR8 *Languages, 178 IN OUT UINTN *LanguagesSize 179 ); 180 181 182 /** 183 Each string package has associated with it a single primary language and zero 184 or more secondary languages. This routine returns the secondary languages 185 associated with a package list. 186 187 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance. 188 @param PackageList The package list to examine. 189 @param PrimaryLanguage Points to the null-terminated ASCII string that specifies 190 the primary language. Languages are specified in the 191 format specified in Appendix M of the UEFI 2.0 specification. 192 @param SecondaryLanguages Points to the buffer to hold the returned null-terminated 193 ASCII string that describes the list of 194 secondary languages for the specified 195 PrimaryLanguage. If there are no secondary 196 languages, the function returns successfully, but 197 this is set to NULL. 198 @param SecondaryLanguagesSize On entry, points to the size of the buffer pointed 199 to by SecondaryLanguages, in bytes. On return, 200 points to the length of SecondaryLanguages in bytes. 201 202 @retval EFI_SUCCESS Secondary languages were correctly returned. 203 @retval EFI_INVALID_PARAMETER PrimaryLanguage or SecondaryLanguagesSize was NULL. 204 @retval EFI_INVALID_PARAMETER The value referenced by SecondaryLanguagesSize is not 205 zero and SecondaryLanguages is NULL. 206 @retval EFI_BUFFER_TOO_SMALL The buffer specified by SecondaryLanguagesSize is 207 too small to hold the returned information. 208 SecondaryLanguageSize is updated to hold the size of 209 the buffer required. 210 @retval EFI_INVALID_LANGUAGE The language specified by PrimaryLanguage is not 211 present in the specified package list. 212 @retval EFI_NOT_FOUND The specified PackageList is not in the Database. 213 214 **/ 215 typedef 216 EFI_STATUS 217 (EFIAPI *EFI_HII_GET_2ND_LANGUAGES)( 218 IN CONST EFI_HII_STRING_PROTOCOL *This, 219 IN EFI_HII_HANDLE PackageList, 220 IN CONST CHAR8 *PrimaryLanguage, 221 IN OUT CHAR8 *SecondaryLanguages, 222 IN OUT UINTN *SecondaryLanguagesSize 223 ); 224 225 226 /// 227 /// Services to manipulate the string. 228 /// 229 struct _EFI_HII_STRING_PROTOCOL { 230 EFI_HII_NEW_STRING NewString; 231 EFI_HII_GET_STRING GetString; 232 EFI_HII_SET_STRING SetString; 233 EFI_HII_GET_LANGUAGES GetLanguages; 234 EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages; 235 }; 236 237 238 extern EFI_GUID gEfiHiiStringProtocolGuid; 239 240 #endif 241 242