[mirror_edk2.git] / EdkCompatibilityPkg / Foundation / Efi / Protocol / HiiString / HiiString.h

/*++\r
\r
Copyright (c) 2007, Intel Corporation. All rights reserved.<BR>\r
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
Module Name:\r
\r
    HiiString.h\r
    \r
Abstract:\r
\r
    EFI_HII_STRING_PROTOCOL from UEFI 2.1 specification.\r
    \r
    This protocol provides interfaces to manipulate string data.\r
\r
Revision History\r
\r
--*/\r
\r
#ifndef __EFI_HII_STRING_PROTOCOL_H__\r
#define __EFI_HII_STRING_PROTOCOL_H__\r
\r
#include EFI_PROTOCOL_DEFINITION (HiiFont)\r
\r
//\r
// Global ID for the Hii String Protocol.\r
//\r
#define EFI_HII_STRING_PROTOCOL_GUID \\r
  { \\r
    0xfd96974, 0x23aa, 0x4cdc, {0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a} \\r
  }\r
\r
EFI_FORWARD_DECLARATION (EFI_HII_STRING_PROTOCOL);\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
  Routine Description:\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
  Arguments:          \r
    This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
    PackageList       - Handle of the package list where this string will be added.                        \r
    StringId          - On return, contains the new strings id, which is unique within PackageList.    \r
    Language          - Points to the language for the new string.\r
    LanguageName      - Points to the printable language name to associate with the passed in \r
                        Language field.If LanguageName is not NULL and the string package header's LanguageName \r
                        associated with a given Language is not zero, the LanguageName being passed \r
                        in will be ignored.    \r
    String            - Points to the new null-terminated string.                                                                                     \r
    StringFontInfo    - Points to the new string's font information or NULL if the string should have the\r
                        default system font, size and style.                                                  \r
\r
  Returns:\r
    EFI_SUCCESS            - The new string was added successfully.\r
    EFI_NOT_FOUND          - The specified PackageList could not be found in database.\r
    EFI_OUT_OF_RESOURCES   - Could not add the string due to lack of resources.\r
    EFI_INVALID_PARAMETER  - String is NULL or StringId is NULL or Language is NULL.                                            \r
    \r
--*/    \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
  Routine Description:\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
  Arguments:          \r
    This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
    Language          - Points to the language for the retrieved string.\r
    PackageList       - The package list in the HII database to search for the \r
                        specified string.    \r
    StringId          - The string's id, which is unique within PackageList.    \r
    String            - Points to the new null-terminated string.            \r
    StringSize        - On entry, points to the size of the buffer pointed to by \r
                        String, in bytes. On return,\r
                        points to the length of the string, in bytes.                                                                                             \r
    StringFontInfo    - If not NULL, points to the string's font information. \r
                        It's caller's responsibility to free this buffer.\r
\r
  Returns:\r
    EFI_SUCCESS            - The string was returned successfully.\r
    EFI_NOT_FOUND          - The string specified by StringId is not available.\r
    EFI_BUFFER_TOO_SMALL   - The buffer specified by StringSize is too small to \r
                             hold the string.                                                      \r
    EFI_INVALID_PARAMETER  - The String or Language or StringSize was NULL.\r
    EFI_OUT_OF_RESOURCES   - There were insufficient resources to complete the \r
                             request.\r
    \r
--*/ \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 CONST EFI_STRING                 String,\r
  IN CONST EFI_FONT_INFO              *StringFontInfo OPTIONAL\r
  )\r
/*++\r
\r
  Routine Description:\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
  Arguments:          \r
    This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
    PackageList       - The package list containing the strings.\r
    StringId          - The string's id, which is unique within PackageList.    \r
    Language          - Points to the language for the updated string.\r
    String            - Points to the new null-terminated string.                   \r
    StringFontInfo    - Points to the string's font information or NULL if the string font information is not\r
                        changed.  \r
\r
  Returns:\r
    EFI_SUCCESS            - The string was updated successfully.\r
    EFI_NOT_FOUND          - The string specified by StringId is not in the database.    \r
    EFI_INVALID_PARAMETER  - The String or Language was NULL.\r
    EFI_OUT_OF_RESOURCES   - The system is out of resources to accomplish the task.\r
    \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
  Routine Description:\r
    This function returns the list of supported languages, in the format specified\r
    in Appendix M of UEFI 2.1 spec.\r
    \r
  Arguments:          \r
    This              - A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
    PackageList       - The package list to examine.\r
    Languages         - Points to the buffer to hold the returned string.\r
    LanguagesSize     - On entry, points to the size of the buffer pointed to by \r
                        Languages, in bytes. On \r
                        return, points to the length of Languages, in bytes.\r
                        \r
  Returns:\r
    EFI_SUCCESS            - The languages were returned successfully.    \r
    EFI_INVALID_PARAMETER  - The Languages or LanguagesSize was NULL.\r
    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
    \r
--*/\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
  Routine Description:\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
  Arguments:          \r
    This                   - A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
    PackageList            - The package list to examine.\r
    FirstLanguage          - Points to the primary language.\r
    SecondaryLanguages     - Points to the buffer to hold the returned list of \r
                             secondary languages for the specified FirstLanguage.\r
                             If there are no secondary languages, the function \r
                             returns successfully, but this is set to NULL.\r
    SecondaryLanguageSize  - On entry, points to the size of the buffer pointed to \r
                             by SecondLanguages, in bytes. On return, points to\r
                             the length of SecondLanguages in bytes.\r
                        \r
  Returns:\r
    EFI_SUCCESS            - Secondary languages were correctly returned.\r
    EFI_INVALID_PARAMETER  - FirstLanguage or SecondLanguages or SecondLanguagesSize was NULL. \r
    EFI_BUFFER_TOO_SMALL   - The buffer specified by SecondLanguagesSize is   \r
                             too small to hold the returned information.      \r
                             SecondLanguageSize is updated to hold the size of\r
                             the buffer required.                             \r
                             \r
--*/                         \r
;\r
//\r
// Interface structure for the EFI_HII_STRING_PROTOCOL\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
extern EFI_GUID gEfiHiiStringProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
2c40a813	1	/*++\r
2c40a813	2	\r
f57387d5 HT	3	Copyright (c) 2007, Intel Corporation. All rights reserved.<BR>\r
f57387d5 HT	4	This program and the accompanying materials \r
2c40a813	5	are licensed and made available under the terms and conditions of the BSD License \r
	6	which accompanies this distribution. The full text of the license may be found at \r
	7	http://opensource.org/licenses/bsd-license.php \r
	8	\r
	9	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	10	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	11	\r
	12	Module Name:\r
	13	\r
	14	HiiString.h\r
	15	\r
	16	Abstract:\r
	17	\r
	18	EFI_HII_STRING_PROTOCOL from UEFI 2.1 specification.\r
	19	\r
	20	This protocol provides interfaces to manipulate string data.\r
	21	\r
	22	Revision History\r
	23	\r
	24	--*/\r
	25	\r
	26	#ifndef __EFI_HII_STRING_PROTOCOL_H__\r
	27	#define __EFI_HII_STRING_PROTOCOL_H__\r
	28	\r
	29	#include EFI_PROTOCOL_DEFINITION (HiiFont)\r
	30	\r
	31	//\r
	32	// Global ID for the Hii String Protocol.\r
	33	//\r
	34	#define EFI_HII_STRING_PROTOCOL_GUID \\r
	35	{ \\r
7ccf38a3	36	0xfd96974, 0x23aa, 0x4cdc, {0xb9, 0xcb, 0x98, 0xd1, 0x77, 0x50, 0x32, 0x2a} \\r
2c40a813	37	}\r
	38	\r
	39	EFI_FORWARD_DECLARATION (EFI_HII_STRING_PROTOCOL);\r
	40	\r
	41	typedef\r
	42	EFI_STATUS\r
	43	(EFIAPI *EFI_HII_NEW_STRING) (\r
	44	IN CONST EFI_HII_STRING_PROTOCOL *This,\r
	45	IN EFI_HII_HANDLE PackageList,\r
	46	OUT EFI_STRING_ID *StringId,\r
	47	IN CONST CHAR8 *Language,\r
	48	IN CONST CHAR16 *LanguageName, OPTIONAL \r
	49	IN CONST EFI_STRING String,\r
	50	IN CONST EFI_FONT_INFO *StringFontInfo OPTIONAL\r
	51	)\r
	52	/*++\r
	53	\r
	54	Routine Description:\r
	55	This function adds the string String to the group of strings owned by PackageList, with the\r
	56	specified font information StringFontInfo and returns a new string id. \r
	57	\r
	58	Arguments: \r
	59	This - A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
	60	PackageList - Handle of the package list where this string will be added. \r
	61	StringId - On return, contains the new strings id, which is unique within PackageList. \r
	62	Language - Points to the language for the new string.\r
	63	LanguageName - Points to the printable language name to associate with the passed in \r
	64	Language field.If LanguageName is not NULL and the string package header's LanguageName \r
	65	associated with a given Language is not zero, the LanguageName being passed \r
	66	in will be ignored. \r
	67	String - Points to the new null-terminated string. \r
fd0d281b	68	StringFontInfo - Points to the new string's font information or NULL if the string should have the\r
2c40a813	69	default system font, size and style. \r
	70	\r
	71	Returns:\r
	72	EFI_SUCCESS - The new string was added successfully.\r
	73	EFI_NOT_FOUND - The specified PackageList could not be found in database.\r
	74	EFI_OUT_OF_RESOURCES - Could not add the string due to lack of resources.\r
	75	EFI_INVALID_PARAMETER - String is NULL or StringId is NULL or Language is NULL. \r
	76	\r
	77	--*/ \r
	78	;\r
	79	\r
	80	typedef\r
	81	EFI_STATUS\r
	82	(EFIAPI *EFI_HII_GET_STRING) (\r
	83	IN CONST EFI_HII_STRING_PROTOCOL *This,\r
	84	IN CONST CHAR8 *Language,\r
	85	IN EFI_HII_HANDLE PackageList,\r
	86	IN EFI_STRING_ID StringId,\r
	87	OUT EFI_STRING String,\r
	88	IN OUT UINTN *StringSize,\r
	89	OUT EFI_FONT_INFO **StringFontInfo OPTIONAL\r
	90	)\r
	91	/*++\r
	92	\r
	93	Routine Description:\r
	94	This function retrieves the string specified by StringId which is associated \r
	95	with the specified PackageList in the language Language and copies it into \r
	96	the buffer specified by String.\r
	97	\r
	98	Arguments: \r
	99	This - A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
	100	Language - Points to the language for the retrieved string.\r
	101	PackageList - The package list in the HII database to search for the \r
	102	specified string. \r
	103	StringId - The string's id, which is unique within PackageList. \r
	104	String - Points to the new null-terminated string. \r
	105	StringSize - On entry, points to the size of the buffer pointed to by \r
	106	String, in bytes. On return,\r
	107	points to the length of the string, in bytes. \r
fd0d281b	108	StringFontInfo - If not NULL, points to the string's font information. \r
2c40a813	109	It's caller's responsibility to free this buffer.\r
	110	\r
	111	Returns:\r
	112	EFI_SUCCESS - The string was returned successfully.\r
	113	EFI_NOT_FOUND - The string specified by StringId is not available.\r
	114	EFI_BUFFER_TOO_SMALL - The buffer specified by StringSize is too small to \r
	115	hold the string. \r
	116	EFI_INVALID_PARAMETER - The String or Language or StringSize was NULL.\r
	117	EFI_OUT_OF_RESOURCES - There were insufficient resources to complete the \r
	118	request.\r
	119	\r
	120	--*/ \r
	121	;\r
	122	\r
	123	typedef\r
	124	EFI_STATUS\r
	125	(EFIAPI *EFI_HII_SET_STRING) (\r
	126	IN CONST EFI_HII_STRING_PROTOCOL *This,\r
	127	IN EFI_HII_HANDLE PackageList,\r
	128	IN EFI_STRING_ID StringId,\r
	129	IN CONST CHAR8 *Language,\r
	130	IN CONST EFI_STRING String,\r
	131	IN CONST EFI_FONT_INFO *StringFontInfo OPTIONAL\r
	132	)\r
	133	/*++\r
	134	\r
	135	Routine Description:\r
	136	This function updates the string specified by StringId in the specified PackageList to the text \r
	137	specified by String and, optionally, the font information specified by StringFontInfo. \r
	138	\r
	139	Arguments: \r
	140	This - A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
	141	PackageList - The package list containing the strings.\r
fd0d281b	142	StringId - The string's id, which is unique within PackageList. \r
2c40a813	143	Language - Points to the language for the updated string.\r
2c40a813	144	String - Points to the new null-terminated string. \r
fd0d281b	145	StringFontInfo - Points to the string's font information or NULL if the string font information is not\r
2c40a813	146	changed. \r
	147	\r
	148	Returns:\r
	149	EFI_SUCCESS - The string was updated successfully.\r
	150	EFI_NOT_FOUND - The string specified by StringId is not in the database. \r
	151	EFI_INVALID_PARAMETER - The String or Language was NULL.\r
	152	EFI_OUT_OF_RESOURCES - The system is out of resources to accomplish the task.\r
	153	\r
	154	--*/ \r
	155	;\r
	156	\r
	157	typedef\r
	158	EFI_STATUS\r
	159	(EFIAPI *EFI_HII_GET_LANGUAGES) (\r
	160	IN CONST EFI_HII_STRING_PROTOCOL *This,\r
	161	IN EFI_HII_HANDLE PackageList,\r
	162	IN OUT CHAR8 *Languages,\r
	163	IN OUT UINTN *LanguagesSize\r
	164	)\r
	165	/*++\r
	166	\r
	167	Routine Description:\r
	168	This function returns the list of supported languages, in the format specified\r
	169	in Appendix M of UEFI 2.1 spec.\r
	170	\r
	171	Arguments: \r
	172	This - A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
	173	PackageList - The package list to examine.\r
	174	Languages - Points to the buffer to hold the returned string.\r
	175	LanguagesSize - On entry, points to the size of the buffer pointed to by \r
	176	Languages, in bytes. On \r
	177	return, points to the length of Languages, in bytes.\r
	178	\r
	179	Returns:\r
	180	EFI_SUCCESS - The languages were returned successfully. \r
	181	EFI_INVALID_PARAMETER - The Languages or LanguagesSize was NULL.\r
	182	EFI_BUFFER_TOO_SMALL - The LanguagesSize is too small to hold the list of \r
	183	supported languages. LanguageSize is updated to\r
	184	contain the required size.\r
	185	\r
	186	--*/\r
	187	;\r
	188	\r
	189	typedef\r
	190	EFI_STATUS\r
	191	(EFIAPI *EFI_HII_GET_2ND_LANGUAGES) (\r
	192	IN CONST EFI_HII_STRING_PROTOCOL *This,\r
	193	IN EFI_HII_HANDLE PackageList,\r
	194	IN CONST CHAR8 *FirstLanguage,\r
	195	IN OUT CHAR8 *SecondLanguages,\r
	196	IN OUT UINTN *SecondLanguagesSize\r
	197	)\r
	198	/*++\r
	199	\r
	200	Routine Description:\r
	201	Each string package has associated with it a single primary language and zero\r
	202	or more secondary languages. This routine returns the secondary languages\r
	203	associated with a package list.\r
	204	\r
	205	Arguments: \r
	206	This - A pointer to the EFI_HII_STRING_PROTOCOL instance.\r
	207	PackageList - The package list to examine.\r
	208	FirstLanguage - Points to the primary language.\r
	209	SecondaryLanguages - Points to the buffer to hold the returned list of \r
210	secondary languages for the specified FirstLanguage.\r
211	If there are no secondary languages, the function \r
212	returns successfully, but this is set to NULL.\r
213	SecondaryLanguageSize - On entry, points to the size of the buffer pointed to \r
214	by SecondLanguages, in bytes. On return, points to\r
215	the length of SecondLanguages in bytes.\r
216	\r
217	Returns:\r
218	EFI_SUCCESS - Secondary languages were correctly returned.\r
219	EFI_INVALID_PARAMETER - FirstLanguage or SecondLanguages or SecondLanguagesSize was NULL. \r
220	EFI_BUFFER_TOO_SMALL - The buffer specified by SecondLanguagesSize is \r
221	too small to hold the returned information. \r
222	SecondLanguageSize is updated to hold the size of\r
223	the buffer required. \r
224	\r
225	--*/ \r
226	;\r
227	//\r
228	// Interface structure for the EFI_HII_STRING_PROTOCOL\r
229	//\r
e5bce275	230	struct _EFI_HII_STRING_PROTOCOL {\r
2c40a813	231	EFI_HII_NEW_STRING NewString;\r
	232	EFI_HII_GET_STRING GetString;\r
	233	EFI_HII_SET_STRING SetString;\r
	234	EFI_HII_GET_LANGUAGES GetLanguages;\r
	235	EFI_HII_GET_2ND_LANGUAGES GetSecondaryLanguages;\r
e5bce275	236	};\r
2c40a813	237	\r
	238	extern EFI_GUID gEfiHiiStringProtocolGuid;\r
	239	\r
	240	#endif\r