1 /** @file 2 The file provides services to manipulate string data. 3 4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 5 SPDX-License-Identifier: BSD-2-Clause-Patent 6 7 @par Revision Reference: 8 This Protocol was introduced in UEFI Specification 2.1. 9 10 **/ 11 12 #ifndef __HII_STRING_H__ 13 #define __HII_STRING_H__ 14 15 #include <Protocol/HiiFont.h> 16 17 #define EFI_HII_STRING_PROTOCOL_GUID \ 18 { 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } } 19 20 typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL; 21 22 /** 23 This function adds the string String to the group of strings owned by PackageList, with the 24 specified font information StringFontInfo, and returns a new string id. 25 The new string identifier is guaranteed to be unique within the package list. 26 That new string identifier is reserved for all languages in the package list. 27 28 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance. 29 @param PackageList The handle of the package list where this string will 30 be added. 31 @param StringId On return, contains the new strings id, which is 32 unique within PackageList. 33 @param Language Points to the language for the new string. 34 @param LanguageName Points to the printable language name to associate 35 with the passed in Language field.If LanguageName 36 is not NULL and the string package header's 37 LanguageName associated with a given Language is 38 not zero, the LanguageName being passed in will 39 be ignored. 40 @param String Points to the new null-terminated string. 41 @param StringFontInfo Points to the new string's font information or 42 NULL if the string should have the default system 43 font, size and style. 44 45 @retval EFI_SUCCESS The new string was added successfully. 46 @retval EFI_NOT_FOUND The specified PackageList could not be found in 47 database. 48 @retval EFI_OUT_OF_RESOURCES Could not add the string due to lack of resources. 49 @retval EFI_INVALID_PARAMETER String is NULL, or StringId is NULL, or Language is NULL. 50 @retval EFI_INVALID_PARAMETER The specified StringFontInfo does not exist in 51 current database. 52 53 **/ 54 typedef 55 EFI_STATUS 56 (EFIAPI *EFI_HII_NEW_STRING)( 57 IN CONST EFI_HII_STRING_PROTOCOL *This, 58 IN EFI_HII_HANDLE PackageList, 59 OUT EFI_STRING_ID *StringId, 60 IN CONST CHAR8 *Language, 61 IN CONST CHAR16 *LanguageName OPTIONAL, 62 IN CONST EFI_STRING String, 63 IN CONST EFI_FONT_INFO *StringFontInfo OPTIONAL 64 ); 65 66 /** 67 This function retrieves the string specified by StringId which is associated 68 with the specified PackageList in the language Language and copies it into 69 the buffer specified by String. 70 71 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance. 72 @param Language Points to the language for the retrieved string. 73 @param PackageList The package list in the HII database to search for 74 the specified string. 75 @param StringId The string's id, which is unique within 76 PackageList. 77 @param String Points to the new null-terminated string. 78 @param StringSize On entry, points to the size of the buffer pointed 79 to by String, in bytes. On return, points to the 80 length of the string, in bytes. 81 @param StringFontInfo If not NULL, points to the string's font 82 information. It's caller's responsibility to free 83 this buffer. 84 85 @retval EFI_SUCCESS The string was returned successfully. 86 @retval EFI_NOT_FOUND The string specified by StringId is not available. 87 The specified PackageList is not in the database. 88 @retval EFI_INVALID_LANGUAGE The string specified by StringId is available but 89 not in the specified language. 90 @retval EFI_BUFFER_TOO_SMALL The buffer specified by StringSize is too small to 91 hold the string. 92 @retval EFI_INVALID_PARAMETER The Language or StringSize was NULL. 93 @retval EFI_INVALID_PARAMETER The value referenced by StringSize was not zero and 94 String was NULL. 95 @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the 96 request. 97 98 **/ 99 typedef 100 EFI_STATUS 101 (EFIAPI *EFI_HII_GET_STRING)( 102 IN CONST EFI_HII_STRING_PROTOCOL *This, 103 IN CONST CHAR8 *Language, 104 IN EFI_HII_HANDLE PackageList, 105 IN EFI_STRING_ID StringId, 106 OUT EFI_STRING String, 107 IN OUT UINTN *StringSize, 108 OUT EFI_FONT_INFO **StringFontInfo OPTIONAL 109 ); 110 111 /** 112 This function updates the string specified by StringId in the specified PackageList to the text 113 specified by String and, optionally, the font information specified by StringFontInfo. 114 115 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance. 116 @param PackageList The package list containing the strings. 117 @param StringId The string's id, which is unique within 118 PackageList. 119 @param Language Points to the language for the updated string. 120 @param String Points to the new null-terminated string. 121 @param StringFontInfo Points to the string's font information or NULL if 122 the string font information is not changed. 123 124 @retval EFI_SUCCESS The string was updated successfully. 125 @retval EFI_NOT_FOUND The string specified by StringId is not in the 126 database. 127 @retval EFI_INVALID_PARAMETER The String or Language was NULL. 128 @retval EFI_INVALID_PARAMETER The specified StringFontInfo does not exist in 129 current database. 130 @retval EFI_OUT_OF_RESOURCES The system is out of resources to accomplish the 131 task. 132 133 **/ 134 typedef 135 EFI_STATUS 136 (EFIAPI *EFI_HII_SET_STRING)( 137 IN CONST EFI_HII_STRING_PROTOCOL *This, 138 IN EFI_HII_HANDLE PackageList, 139 IN EFI_STRING_ID StringId, 140 IN CONST CHAR8 *Language, 141 IN EFI_STRING String, 142 IN CONST EFI_FONT_INFO *StringFontInfo OPTIONAL 143 ); 144 145 /** 146 This function returns the list of supported languages. 147 148 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance. 149 @param PackageList The package list to examine. 150 @param Languages Points to the buffer to hold the returned 151 null-terminated ASCII string. 152 @param LanguagesSize On entry, points to the size of the buffer pointed 153 to by Languages, in bytes. On return, points to 154 the length of Languages, in bytes. 155 156 @retval EFI_SUCCESS The languages were returned successfully. 157 @retval EFI_INVALID_PARAMETER The LanguagesSize was NULL. 158 @retval EFI_INVALID_PARAMETER The value referenced by LanguagesSize is not zero 159 and Languages is 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 Each string package has associated with it a single primary language and zero 178 or more secondary languages. This routine returns the secondary languages 179 associated with a package list. 180 181 @param This A pointer to the EFI_HII_STRING_PROTOCOL instance. 182 @param PackageList The package list to examine. 183 @param PrimaryLanguage Points to the null-terminated ASCII string that specifies 184 the primary language. Languages are specified in the 185 format specified in Appendix M of the UEFI 2.0 specification. 186 @param SecondaryLanguages Points to the buffer to hold the returned null-terminated 187 ASCII string that describes the list of 188 secondary languages for the specified 189 PrimaryLanguage. If there are no secondary 190 languages, the function returns successfully, but 191 this is set to NULL. 192 @param SecondaryLanguagesSize On entry, points to the size of the buffer pointed 193 to by SecondaryLanguages, in bytes. On return, 194 points to the length of SecondaryLanguages in bytes. 195 196 @retval EFI_SUCCESS Secondary languages were correctly returned. 197 @retval EFI_INVALID_PARAMETER PrimaryLanguage or SecondaryLanguagesSize was NULL. 198 @retval EFI_INVALID_PARAMETER The value referenced by SecondaryLanguagesSize is not 199 zero and SecondaryLanguages is NULL. 200 @retval EFI_BUFFER_TOO_SMALL The buffer specified by SecondaryLanguagesSize is 201 too small to hold the returned information. 202 SecondaryLanguageSize is updated to hold the size of 203 the buffer required. 204 @retval EFI_INVALID_LANGUAGE The language specified by PrimaryLanguage is not 205 present in the specified package list. 206 @retval EFI_NOT_FOUND The specified PackageList is not in the Database. 207 208 **/ 209 typedef 210 EFI_STATUS 211 (EFIAPI *EFI_HII_GET_2ND_LANGUAGES)( 212 IN CONST EFI_HII_STRING_PROTOCOL *This, 213 IN EFI_HII_HANDLE PackageList, 214 IN CONST CHAR8 *PrimaryLanguage, 215 IN OUT CHAR8 *SecondaryLanguages, 216 IN OUT UINTN *SecondaryLanguagesSize 217 ); 218 219 /// 220 /// Services to manipulate the string. 221 /// 222 struct _EFI_HII_STRING_PROTOCOL { 223 EFI_HII_NEW_STRING NewString; 224 EFI_HII_GET_STRING GetString; 225 EFI_HII_SET_STRING SetString; 226 EFI_HII_GET_LANGUAGES GetLanguages; 227 EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages; 228 }; 229 230 extern EFI_GUID gEfiHiiStringProtocolGuid; 231 232 #endif 233