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

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