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