[mirror_edk2.git] / MdePkg / Include / Protocol / HiiString.h

/** @file\r
  The file provides services to manipulate string data.\r
  \r
  Copyright (c) 2006 - 2007, Intel Corporation\r
  All rights reserved. This program and the accompanying materials                          \r
  are licensed and made available under the terms and conditions of the BSD License         \r
  which accompanies this distribution.  The full text of the license may be found at        \r
  http://opensource.org/licenses/bsd-license.php                                            \r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
\r
**/\r
\r
#ifndef __HII_STRING_H__\r
#define __HII_STRING_H__\r
\r
#define EFI_HII_STRING_PROTOCOL_GUID \\r
  { 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } }\r
\r
\r
typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL;\r
\r
\r
\r
/**\r
  This function adds the string String to the group of strings\r
  owned by PackageList, with the specified font information\r
  StringFontInfo and returns a new string id.\r
\r
  @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
\r
  @param PackageList  Handle of the package list where this\r
                      string will be added.\r
\r
  @param Language Points to the language for the new string.\r
\r
  @param String   Points to the new null-terminated string.\r
\r
  @param StringFontInfo Points to the new string's font\r
                        information or NULL if the string should\r
                        have the default system font, size and\r
                        style. StringId On return, contains the\r
                        new strings id, which is unique within\r
                        PackageList.\r
\r
  @retval EFI_SUCCESS The new string was added successfully\r
  \r
  @retval EFI_OUT_OF_RESOURCES  Could not add the string.\r
  \r
  @retval EFI_INVALID_PARAMETER String is NULL or StringId is\r
                                NULL or Language is NULL.\r
\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_NEW_STRING) (\r
  IN CONST  EFI_HII_STRING_PROTOCOL   *This,\r
  IN CONST  EFI_HII_HANDLE            PackageList,\r
  OUT       EFI_STRING_ID             *StringId\r
  IN CONST  CHAR8                     *Language,\r
  IN CONST  EFI_STRING                String,\r
  IN CONST  EFI_FONT_INFO             *StringFontInfo OPTIONAL,\r
);\r
\r
\r
/**\r
\r
  This function retrieves the string specified by StringId which\r
  is associated with the specified PackageList in the language\r
  Language and copies it into the buffer specified by String. If\r
  the string specified by StringId is not present in the\r
  specified PackageList, then EFI_NOT_FOUND is returned. If the\r
  string specified by StringId is present, but not in the\r
  specified language then EFI_INVALID_LANGUAGE is returned. If\r
  the buffer specified by StringSize is too small to hold the\r
  string, then EFI_BUFFER_TOO_SMALL will be returned. StringSize\r
  will be updated to the size of buffer actually required to\r
  hold the string.\r
\r
  @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
  \r
  @param PackageList  The package list in the HII database to\r
                      search for the specified string.\r
  \r
  @param Language   Points to the language for the retrieved\r
                    string.\r
  \r
  @param StringId   The string's id, which is unique within\r
                    PackageList.\r
  \r
  @param String   Points to the new null-terminated string.\r
  \r
  @param StringSize On entry, points to the size of the buffer\r
                    pointed to by String, in bytes. On return,\r
                    points to the length of the string, in\r
                    bytes.\r
  \r
  @param StringFontInfo   Points to the string's font\r
                          information or NULL if the string font\r
                          information is not desired.\r
  \r
  @retval EFI_SUCCESS The string was returned successfully.\r
  \r
  @retval EFI_NOT_FOUND The string specified by StringId is not\r
                        available.\r
  \r
  @retval EFI_INVALID_LANGUAGE  The string specified by StringId\r
                                is available but not in the\r
                                specified language.\r
  \r
  @retval EFI_BUFFER_TOO_SMALL  The buffer specified by\r
                                StringLength is too small to\r
                                hold the string.\r
  \r
  @retval EFI_INVALID_PARAMETER The String or Language was NULL.\r
  \r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_GET_STRING) (\r
  IN CONST  EFI_HII_STRING_PROTOCOL *This,\r
  IN CONST  CHAR8                   *Language,\r
  IN CONST  EFI_HII_HANDLE          PackageList,\r
  IN CONST  EFI_STRING_ID           StringId,\r
  OUT       EFI_STRING              String,\r
  IN OUT    UINTN                   StringSize,\r
  OUT       EFI_FONT_INFO           *StringFontInfo OPTIONAL\r
);\r
\r
/**\r
  This function updates the string specified by StringId in the\r
  specified PackageList to the text specified by String and,\r
  optionally, the font information specified by StringFontInfo.\r
  There is no way to change the font information without changing\r
  the string text.\r
\r
  @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
\r
  @param PackageList  The package list containing the strings.\r
\r
  @param Language Points to the language for the updated string.\r
\r
  @param StringId The string id, which is unique within\r
                  PackageList.\r
\r
  @param String   Points to the new null-terminated string.\r
\r
  @param StringFontInfo Points to the string's font information\r
                        or NULL if the string font information\r
                        is not changed.\r
\r
  @retval EFI_SUCCESS   The string was successfully updated.\r
  \r
  @retval EFI_NOT_FOUND The string specified by StringId is not\r
                        in the database.\r
  \r
  @retval EFI_INVALID_PARAMETER The String or Language was NULL.\r
  \r
  @retval EFI_OUT_OF_RESOURCES  The system is out of resources\r
                                to accomplish the task.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_SET_STRING) (\r
  IN CONST  EFI_HII_STRING_PROTOCOL *This,\r
  IN CONST  EFI_HII_HANDLE          PackageList,\r
  IN CONST  EFI_STRING_ID           StringId,\r
  IN CONST  CHAR8                   *Language,\r
  IN CONST  EFI_STRING              String,\r
  IN CONST  EFI_FONT_INFO           *StringFontInfo OPTIONAL\r
);\r
\r
\r
/**\r
\r
  This function returns the list of supported languages.\r
\r
  @param This A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
\r
  @param PackageList  The package list to examine.\r
\r
  @param Languages  Points to the buffer to hold the returned\r
                    string.\r
\r
  @param LanguageSize   On entry, points to the size of the\r
                        buffer pointed to by Languages, in\r
                        bytes. On return, points to the length\r
                        of Languages, in bytes.\r
\r
\r
  @retval EFI_SUCCESS The languages were returned successfully.\r
  \r
  @retval EFI_BUFFER_TOO_SMALL  The LanguagesSize is too small\r
                                to hold the list of supported\r
                                languages. LanguageSize is\r
                                updated to contain the required\r
                                size.\r
  \r
  @retval EFI_INVALID_PARAMETER Languages is NULL.\r
\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_HII_GET_LANGUAGES) (\r
  IN CONST  EFI_HII_DATABASE_PROTOCOL *This,\r
  IN CONST  EFI_HII_HANDLE            PackageList,\r
  IN OUT    CHAR8                     *Languages,\r
  IN OUT    UINTN                     LanguagesSize\r
);\r
\r
\r
/**\r
\r
  Each string package has associated with it a single primary\r
  language and zero or more secondary languages. This routine\r
  returns the secondary languages associated with a package list.\r
\r
  @param This   A pointer to the EFI_HII_STRING_PROTOCOL\r
                instance.\r
\r
  @param PackageList  The package list to examine.\r
\r
  @param FirstLanguage  Points to the primary language.\r
\r
  @param Languages  are specified in the format specified in\r
                    Appendix M of the UEFI 2.0 specification.\r
\r
  @param SecondaryLanguages Points to the buffer to hold the\r
                            returned list of secondary languages\r
                            for the specified FirstLanguage. If\r
                            there are no secondary languages,\r
                            the function returns successfully,\r
                            but this is set to NULL.\r
\r
  @param SecondaryLanguageSize  On entry, points to the size of\r
                                the buffer pointed to by\r
                                Languages, in bytes. On return,\r
                                points to the length of\r
                                Languages in bytes.\r
\r
  @retval EFI_SUCCESS   Secondary languages correctly returned\r
\r
  @retval EFI_BUFFER_TOO_SMALL  The buffer specified by\r
                                SecondLanguagesSize is too small\r
                                to hold the returned\r
                                information. SecondLanguageSize\r
                                is updated to hold the size of\r
                                the buffer required.\r
\r
  @retval EFI_INVALID_LANGUAGE  The language specified by\r
                                FirstLanguage is not present in\r
                                the specified package list.\r
\r
  @retval EFI_INVALID_PARAMETER FirstLanguage is NULL or\r
                                SecondLanguage is NULL.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_GET_2ND_LANGUAGES) (\r
  IN CONST  EFI_HII_DATABASE_PROTOCOL *This,\r
  IN CONST  EFI_HII_HANDLE            PackageList,\r
  IN CONST  CHAR8                     *FirstLanguage;\r
  IN OUT    CHAR8                     *SecondLanguages,\r
  IN OUT    UINTN                     SecondLanguagesSize\r
);\r
\r
\r
/**\r
  Services to manipulate the string.\r
   \r
  @param NewString  Add a new string. GetString Retrieve a\r
                    string and related string information.\r
\r
  @param SetString  Change a string. \r
\r
  @param GetLanguages   List the languages for a particular\r
                        package list.\r
\r
  @param GetSecondaryLanguages  List supported secondary\r
                                languages for a particular\r
                                primary language.\r
\r
**/\r
struct _EFI_HII_STRING_PROTOCOL {\r
  EFI_HII_NEW_STRING        NewString;\r
  EFI_HII_GET_STRING        GetString;\r
  EFI_HII_SET_STRING        SetString;\r
  EFI_HII_GET_LANGUAGES     GetLanguages;\r
  EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages;\r
};\r
\r
\r
extern EFI_GUID gEfiHiiStringProtocolGuid;\r
\r
#endif\r
\r
Commit	Line	Data
d1f95000	1	/** @file\r
	2	The file provides services to manipulate string data.\r
	3	\r
	4	Copyright (c) 2006 - 2007, Intel Corporation\r
	5	All rights reserved. This program and the accompanying materials \r
	6	are licensed and made available under the terms and conditions of the BSD License \r
	7	which accompanies this distribution. The full text of the license may be found at \r
	8	http://opensource.org/licenses/bsd-license.php \r
	9	\r
	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	12	\r
d1f95000	13	**/\r
	14	\r
	15	#ifndef __HII_STRING_H__\r
	16	#define __HII_STRING_H__\r
	17	\r
	18	#define EFI_HII_STRING_PROTOCOL_GUID \\r
	19	{ 0xfd96974, 0x23aa, 0x4cdc, { 0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a } }\r
	20	\r
	21	\r
	22	typedef struct _EFI_HII_STRING_PROTOCOL EFI_HII_STRING_PROTOCOL;\r
	23	\r
	24	\r
	25	\r
	26	/**\r
	27	This function adds the string String to the group of strings\r
	28	owned by PackageList, with the specified font information\r
	29	StringFontInfo and returns a new string id.\r
	30	\r
	31	@param This A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
	32	\r
	33	@param PackageList Handle of the package list where this\r
	34	string will be added.\r
	35	\r
	36	@param Language Points to the language for the new string.\r
	37	\r
	38	@param String Points to the new null-terminated string.\r
	39	\r
	40	@param StringFontInfo Points to the new string's font\r
	41	information or NULL if the string should\r
	42	have the default system font, size and\r
	43	style. StringId On return, contains the\r
	44	new strings id, which is unique within\r
	45	PackageList.\r
	46	\r
	47	@retval EFI_SUCCESS The new string was added successfully\r
	48	\r
	49	@retval EFI_OUT_OF_RESOURCES Could not add the string.\r
	50	\r
	51	@retval EFI_INVALID_PARAMETER String is NULL or StringId is\r
	52	NULL or Language is NULL.\r
	53	\r
	54	\r
	55	**/\r
	56	typedef\r
	57	EFI_STATUS\r
	58	(EFIAPI *EFI_HII_NEW_STRING) (\r
	59	IN CONST EFI_HII_STRING_PROTOCOL *This,\r
	60	IN CONST EFI_HII_HANDLE PackageList,\r
	61	OUT EFI_STRING_ID *StringId\r
	62	IN CONST CHAR8 *Language,\r
	63	IN CONST EFI_STRING String,\r
	64	IN CONST EFI_FONT_INFO *StringFontInfo OPTIONAL,\r
	65	);\r
	66	\r
	67	\r
	68	/**\r
	69	\r
	70	This function retrieves the string specified by StringId which\r
	71	is associated with the specified PackageList in the language\r
	72	Language and copies it into the buffer specified by String. If\r
	73	the string specified by StringId is not present in the\r
	74	specified PackageList, then EFI_NOT_FOUND is returned. If the\r
	75	string specified by StringId is present, but not in the\r
	76	specified language then EFI_INVALID_LANGUAGE is returned. If\r
77	the buffer specified by StringSize is too small to hold the\r
78	string, then EFI_BUFFER_TOO_SMALL will be returned. StringSize\r
79	will be updated to the size of buffer actually required to\r
80	hold the string.\r
81	\r
82	@param This A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
83	\r
84	@param PackageList The package list in the HII database to\r
85	search for the specified string.\r
86	\r
87	@param Language Points to the language for the retrieved\r
88	string.\r
89	\r
90	@param StringId The string's id, which is unique within\r
91	PackageList.\r
92	\r
93	@param String Points to the new null-terminated string.\r
94	\r
95	@param StringSize On entry, points to the size of the buffer\r
96	pointed to by String, in bytes. On return,\r
97	points to the length of the string, in\r
98	bytes.\r
99	\r
100	@param StringFontInfo Points to the string's font\r
101	information or NULL if the string font\r
102	information is not desired.\r
103	\r
104	@retval EFI_SUCCESS The string was returned successfully.\r
105	\r
106	@retval EFI_NOT_FOUND The string specified by StringId is not\r
107	available.\r
108	\r
109	@retval EFI_INVALID_LANGUAGE The string specified by StringId\r
110	is available but not in the\r
111	specified language.\r
112	\r
113	@retval EFI_BUFFER_TOO_SMALL The buffer specified by\r
114	StringLength is too small to\r
115	hold the string.\r
116	\r
117	@retval EFI_INVALID_PARAMETER The String or Language was NULL.\r
118	\r
119	**/\r
120	typedef\r
121	EFI_STATUS\r
122	(EFIAPI *EFI_HII_GET_STRING) (\r
123	IN CONST EFI_HII_STRING_PROTOCOL *This,\r
124	IN CONST CHAR8 *Language,\r
125	IN CONST EFI_HII_HANDLE PackageList,\r
126	IN CONST EFI_STRING_ID StringId,\r
127	OUT EFI_STRING String,\r
128	IN OUT UINTN StringSize,\r
129	OUT EFI_FONT_INFO *StringFontInfo OPTIONAL\r
130	);\r
131	\r
132	/**\r
133	This function updates the string specified by StringId in the\r
134	specified PackageList to the text specified by String and,\r
135	optionally, the font information specified by StringFontInfo.\r
136	There is no way to change the font information without changing\r
137	the string text.\r
138	\r
139	@param This A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
140	\r
141	@param PackageList The package list containing the strings.\r
142	\r
143	@param Language Points to the language for the updated string.\r
144	\r
145	@param StringId The string id, which is unique within\r
146	PackageList.\r
147	\r
148	@param String Points to the new null-terminated string.\r
149	\r
150	@param StringFontInfo Points to the string's font information\r
151	or NULL if the string font information\r
152	is not changed.\r
153	\r
154	@retval EFI_SUCCESS The string was successfully updated.\r
155	\r
156	@retval EFI_NOT_FOUND The string specified by StringId is not\r
157	in the database.\r
158	\r
159	@retval EFI_INVALID_PARAMETER The String or Language was NULL.\r
160	\r
161	@retval EFI_OUT_OF_RESOURCES The system is out of resources\r
162	to accomplish the task.\r
163	\r
164	**/\r
165	typedef\r
166	EFI_STATUS\r
167	(EFIAPI *EFI_HII_SET_STRING) (\r
168	IN CONST EFI_HII_STRING_PROTOCOL *This,\r
169	IN CONST EFI_HII_HANDLE PackageList,\r
170	IN CONST EFI_STRING_ID StringId,\r
171	IN CONST CHAR8 *Language,\r
172	IN CONST EFI_STRING String,\r
173	IN CONST EFI_FONT_INFO *StringFontInfo OPTIONAL\r
174	);\r
175	\r
176	\r
177	/**\r
178	\r
179	This function returns the list of supported languages.\r
180	\r
181	@param This A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
182	\r
183	@param PackageList The package list to examine.\r
184	\r
185	@param Languages Points to the buffer to hold the returned\r
186	string.\r
187	\r
188	@param LanguageSize On entry, points to the size of the\r
189	buffer pointed to by Languages, in\r
190	bytes. On return, points to the length\r
191	of Languages, in bytes.\r
192	\r
193	\r
194	@retval EFI_SUCCESS The languages were returned successfully.\r
195	\r
196	@retval EFI_BUFFER_TOO_SMALL The LanguagesSize is too small\r
197	to hold the list of supported\r
198	languages. LanguageSize is\r
199	updated to contain the required\r
200	size.\r
201	\r
202	@retval EFI_INVALID_PARAMETER Languages is NULL.\r
203	\r
204	\r
205	**/\r
206	typedef\r
207	EFI_STATUS\r
208	(EFIAPI *EFI_HII_GET_LANGUAGES) (\r
209	IN CONST EFI_HII_DATABASE_PROTOCOL *This,\r
210	IN CONST EFI_HII_HANDLE PackageList,\r
211	IN OUT CHAR8 *Languages,\r
212	IN OUT UINTN LanguagesSize\r
213	);\r
214	\r
215	\r
216	/**\r
217	\r
218	Each string package has associated with it a single primary\r
219	language and zero or more secondary languages. This routine\r
220	returns the secondary languages associated with a package list.\r
221	\r
222	@param This A pointer to the EFI_HII_STRING_PROTOCOL\r
223	instance.\r
224	\r
225	@param PackageList The package list to examine.\r
226	\r
227	@param FirstLanguage Points to the primary language.\r
228	\r
229	@param Languages are specified in the format specified in\r
230	Appendix M of the UEFI 2.0 specification.\r
231	\r
232	@param SecondaryLanguages Points to the buffer to hold the\r
233	returned list of secondary languages\r
234	for the specified FirstLanguage. If\r
235	there are no secondary languages,\r
236	the function returns successfully,\r
237	but this is set to NULL.\r
238	\r
239	@param SecondaryLanguageSize On entry, points to the size of\r
240	the buffer pointed to by\r
241	Languages, in bytes. On return,\r
242	points to the length of\r
243	Languages in bytes.\r
244	\r
245	@retval EFI_SUCCESS Secondary languages correctly returned\r
246	\r
247	@retval EFI_BUFFER_TOO_SMALL The buffer specified by\r
248	SecondLanguagesSize is too small\r
249	to hold the returned\r
250	information. SecondLanguageSize\r
251	is updated to hold the size of\r
252	the buffer required.\r
253	\r
254	@retval EFI_INVALID_LANGUAGE The language specified by\r
255	FirstLanguage is not present in\r
256	the specified package list.\r
257	\r
258	@retval EFI_INVALID_PARAMETER FirstLanguage is NULL or\r
259	SecondLanguage is NULL.\r
260	\r
261	**/\r
262	typedef\r
263	EFI_STATUS\r
264	(EFIAPI *EFI_GET_2ND_LANGUAGES) (\r
265	IN CONST EFI_HII_DATABASE_PROTOCOL *This,\r
266	IN CONST EFI_HII_HANDLE PackageList,\r
267	IN CONST CHAR8 *FirstLanguage;\r
268	IN OUT CHAR8 *SecondLanguages,\r
269	IN OUT UINTN SecondLanguagesSize\r
270	);\r
271	\r
272	\r
273	/**\r
274	Services to manipulate the string.\r
275	\r
276	@param NewString Add a new string. GetString Retrieve a\r
277	string and related string information.\r
278	\r
279	@param SetString Change a string. \r
280	\r
281	@param GetLanguages List the languages for a particular\r
282	package list.\r
283	\r
284	@param GetSecondaryLanguages List supported secondary\r
285	languages for a particular\r
286	primary language.\r
287	\r
288	**/\r
289	struct _EFI_HII_STRING_PROTOCOL {\r
290	EFI_HII_NEW_STRING NewString;\r
291	EFI_HII_GET_STRING GetString;\r
292	EFI_HII_SET_STRING SetString;\r
293	EFI_HII_GET_LANGUAGES GetLanguages;\r
294	EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages;\r
295	};\r
296	\r
297	\r
298	extern EFI_GUID gEfiHiiStringProtocolGuid;\r
299	\r
300	#endif\r
301	\r