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