Ronak Kanabar | 1ae366f | 2023-06-07 01:21:56 +0530 | [diff] [blame^] | 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 |