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

/** @file\r
  The file provides the mechanism to set and get the values \r
  associated with a keyword exposed through a x-UEFI- prefixed \r
  configuration language namespace.\r
  \r
Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials are licensed and made available under \r
the terms and conditions of the BSD License that accompanies this distribution.  \r
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 __EFI_CONFIG_KEYWORD_HANDLER_H__\r
#define __EFI_CONFIG_KEYWORD_HANDLER_H__\r
\r
#define EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL_GUID \\r
{ \\r
  0x0a8badd5, 0x03b8, 0x4d19, {0xb1, 0x28, 0x7b, 0x8f, 0x0e, 0xda, 0xa5, 0x96 } \\r
}\r
\r
//***********************************************************\r
// Progress Errors\r
//***********************************************************\r
#define KEYWORD_HANDLER_NO_ERROR                       0x00000000\r
#define KEYWORD_HANDLER_NAMESPACE_ID_NOT_FOUND         0x00000001\r
#define KEYWORD_HANDLER_MALFORMED_STRING               0x00000002\r
#define KEYWORD_HANDLER_KEYWORD_NOT_FOUND              0x00000004\r
#define KEYWORD_HANDLER_INCOMPATIBLE_VALUE_DETECTED    0x00000008\r
#define KEYWORD_HANDLER_ACCESS_NOT_PERMITTED           0x00000010\r
#define KEYWORD_HANDLER_UNDEFINED_PROCESSING_ERROR     0x80000000\r
\r
typedef struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL;\r
\r
/**\r
\r
  This function accepts a <MultiKeywordResp> formatted string, finds the associated\r
  keyword owners, creates a <MultiConfigResp> string from it and forwards it to the\r
  EFI_HII_ROUTING_PROTOCOL.RouteConfig function.\r
  \r
  If there is an issue in resolving the contents of the KeywordString, then the \r
  function returns an error and also sets the Progress and ProgressErr with the \r
  appropriate information about where the issue occurred and additional data about\r
  the nature of the issue. \r
  \r
  In the case when KeywordString containing multiple keywords, when an EFI_NOT_FOUND\r
  error is generated during processing the second or later keyword element, the system\r
  storage associated with earlier keywords is not modified. All elements of the \r
  KeywordString must successfully pass all tests for format and access prior to making\r
  any modifications to storage.\r
  \r
  In the case when EFI_DEVICE_ERROR is returned from the processing of a KeywordString\r
  containing multiple keywords, the state of storage associated with earlier keywords\r
  is undefined.\r
\r
\r
  @param This             Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance.\r
\r
  @param KeywordString    A null-terminated string in <MultiKeywordResp> format. \r
\r
  @param Progress         On return, points to a character in the KeywordString. \r
                          Points to the string's NULL terminator if the request \r
                          was successful. Points to the most recent '&' before \r
                          the first failing name / value pair (or the beginning\r
                          of the string if the failure is in the first name / value\r
                          pair) if the request was not successful.\r
\r
  @param ProgressErr      If during the processing of the KeywordString there was\r
                          a failure, this parameter gives additional information \r
                          about the possible source of the problem. The various \r
                          errors are defined in "Related Definitions" below.\r
\r
\r
  @retval EFI_SUCCESS             The specified action was completed successfully.\r
\r
  @retval EFI_INVALID_PARAMETER   One or more of the following are TRUE:\r
                                  1. KeywordString is NULL.\r
                                  2. Parsing of the KeywordString resulted in an \r
                                     error. See Progress and ProgressErr for more data.\r
\r
  @retval EFI_NOT_FOUND           An element of the KeywordString was not found. \r
                                  See ProgressErr for more data.\r
\r
  @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.  \r
                                  See ProgressErr for more data.\r
                                  \r
  @retval EFI_ACCESS_DENIED       The action violated system policy. See ProgressErr \r
                                  for more data.\r
\r
  @retval EFI_DEVICE_ERROR        An unexpected system error occurred. See ProgressErr\r
                                  for more data.\r
\r
**/\r
typedef \r
EFI_STATUS\r
(EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_SET_DATA) (\r
  IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL *This,\r
  IN CONST EFI_STRING                    KeywordString,\r
  OUT EFI_STRING                         *Progress,\r
  OUT UINT32                             *ProgressErr\r
  );\r
\r
\r
/**\r
\r
  This function accepts a <MultiKeywordRequest> formatted string, finds the underlying \r
  keyword owners, creates a <MultiConfigRequest> string from it and forwards it to the\r
  EFI_HII_ROUTING_PROTOCOL.ExtractConfig function.\r
  \r
  If there is an issue in resolving the contents of the KeywordString, then the function\r
  returns an EFI_INVALID_PARAMETER and also set the Progress and ProgressErr with the\r
  appropriate information about where the issue occurred and additional data about the\r
  nature of the issue.\r
  \r
  In the case when KeywordString is NULL, or contains multiple keywords, or when\r
  EFI_NOT_FOUND is generated while processing the keyword elements, the Results string\r
  contains values returned for all keywords processed prior to the keyword generating the \r
  error but no values for the keyword with error or any following keywords.\r
\r
  \r
  @param This           Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance.\r
  \r
  @param NameSpaceId    A null-terminated string containing the platform configuration\r
                        language to search through in the system. If a NULL is passed\r
                        in, then it is assumed that any platform configuration language\r
                        with the prefix of "x-UEFI-" are searched.\r
                        \r
  @param KeywordString  A null-terminated string in <MultiKeywordRequest> format. If a\r
                        NULL is passed in the KeywordString field, all of the known \r
                        keywords in the system for the NameSpaceId specified are \r
                        returned in the Results field.\r
  \r
  @param Progress       On return, points to a character in the KeywordString. Points\r
                        to the string's NULL terminator if the request was successful. \r
                        Points to the most recent '&' before the first failing name / value\r
                        pair (or the beginning of the string if the failure is in the first\r
                        name / value pair) if the request was not successful.\r
                        \r
  @param ProgressErr    If during the processing of the KeywordString there was a\r
                        failure, this parameter gives additional information about the \r
                        possible source of the problem. See the definitions in SetData()\r
                        for valid value definitions.\r
  \r
  @param Results        A null-terminated string in <MultiKeywordResp> format is returned\r
                        which has all the values filled in for the keywords in the \r
                        KeywordString. This is a callee-allocated field, and must be freed\r
                        by the caller after being used. \r
\r
  @retval EFI_SUCCESS             The specified action was completed successfully.\r
  \r
  @retval EFI_INVALID_PARAMETER   One or more of the following are TRUE:\r
                                  1.Progress, ProgressErr, or Resuts is NULL.\r
                                  2.Parsing of the KeywordString resulted in an error. See\r
                                    Progress and ProgressErr for more data.\r
  \r
\r
  @retval EFI_NOT_FOUND           An element of the KeywordString was not found. See\r
                                  ProgressErr for more data.\r
\r
  @retval EFI_NOT_FOUND           The NamespaceId specified was not found.  See ProgressErr\r
                                  for more data.\r
\r
  @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.  See\r
                                  ProgressErr for more data.\r
                                  \r
  @retval EFI_ACCESS_DENIED       The action violated system policy.  See ProgressErr for\r
                                  more data.\r
\r
  @retval EFI_DEVICE_ERROR        An unexpected system error occurred.  See ProgressErr\r
                                  for more data.\r
\r
**/\r
typedef \r
EFI_STATUS\r
(EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_GET_DATA) (\r
  IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL  *This,\r
  IN CONST EFI_STRING                     NameSpaceId, OPTIONAL\r
  IN CONST EFI_STRING                     KeywordString, OPTIONAL\r
  OUT EFI_STRING                          *Progress, \r
  OUT UINT32                              *ProgressErr,\r
  OUT EFI_STRING                          *Results\r
  );\r
\r
///\r
/// The EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL provides the mechanism \r
/// to set and get the values associated with a keyword exposed \r
/// through a x-UEFI- prefixed configuration language namespace\r
///\r
\r
struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL {\r
  EFI_CONFIG_KEYWORD_HANDLER_SET_DATA  SetData;\r
  EFI_CONFIG_KEYWORD_HANDLER_GET_DATA  GetData;\r
};\r
\r
extern EFI_GUID gEfiConfigKeywordHandlerProtocolGuid;\r
\r
#endif\r
\r
Commit	Line	Data
5ca4bb9f ED	1	/** @file\r
	2	The file provides the mechanism to set and get the values \r
	3	associated with a keyword exposed through a x-UEFI- prefixed \r
	4	configuration language namespace.\r
	5	\r
38baa5b6	6	Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR>\r
5ca4bb9f ED	7	This program and the accompanying materials are licensed and made available under \r
	8	the terms and conditions of the BSD License that accompanies this distribution. \r
	9	The full text of the license may be found at\r
	10	http://opensource.org/licenses/bsd-license.php. \r
	11	\r
	12	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	13	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	14	\r
	15	**/\r
	16	\r
	17	#ifndef __EFI_CONFIG_KEYWORD_HANDLER_H__\r
	18	#define __EFI_CONFIG_KEYWORD_HANDLER_H__\r
	19	\r
	20	#define EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL_GUID \\r
	21	{ \\r
	22	0x0a8badd5, 0x03b8, 0x4d19, {0xb1, 0x28, 0x7b, 0x8f, 0x0e, 0xda, 0xa5, 0x96 } \\r
	23	}\r
	24	\r
	25	//***********************************************************\r
	26	// Progress Errors\r
	27	//***********************************************************\r
	28	#define KEYWORD_HANDLER_NO_ERROR 0x00000000\r
	29	#define KEYWORD_HANDLER_NAMESPACE_ID_NOT_FOUND 0x00000001\r
	30	#define KEYWORD_HANDLER_MALFORMED_STRING 0x00000002\r
	31	#define KEYWORD_HANDLER_KEYWORD_NOT_FOUND 0x00000004\r
	32	#define KEYWORD_HANDLER_INCOMPATIBLE_VALUE_DETECTED 0x00000008\r
	33	#define KEYWORD_HANDLER_ACCESS_NOT_PERMITTED 0x00000010\r
	34	#define KEYWORD_HANDLER_UNDEFINED_PROCESSING_ERROR 0x80000000\r
	35	\r
	36	typedef struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL;\r
	37	\r
	38	/**\r
	39	\r
	40	This function accepts a <MultiKeywordResp> formatted string, finds the associated\r
	41	keyword owners, creates a <MultiConfigResp> string from it and forwards it to the\r
	42	EFI_HII_ROUTING_PROTOCOL.RouteConfig function.\r
	43	\r
	44	If there is an issue in resolving the contents of the KeywordString, then the \r
	45	function returns an error and also sets the Progress and ProgressErr with the \r
	46	appropriate information about where the issue occurred and additional data about\r
	47	the nature of the issue. \r
	48	\r
	49	In the case when KeywordString containing multiple keywords, when an EFI_NOT_FOUND\r
	50	error is generated during processing the second or later keyword element, the system\r
	51	storage associated with earlier keywords is not modified. All elements of the \r
	52	KeywordString must successfully pass all tests for format and access prior to making\r
	53	any modifications to storage.\r
	54	\r
	55	In the case when EFI_DEVICE_ERROR is returned from the processing of a KeywordString\r
	56	containing multiple keywords, the state of storage associated with earlier keywords\r
	57	is undefined.\r
	58	\r
	59	\r
	60	@param This Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance.\r
	61	\r
	62	@param KeywordString A null-terminated string in <MultiKeywordResp> format. \r
	63	\r
	64	@param Progress On return, points to a character in the KeywordString. \r
	65	Points to the string's NULL terminator if the request \r
	66	was successful. Points to the most recent '&' before \r
38baa5b6 DB	67	the first failing name / value pair (or the beginning\r
	68	of the string if the failure is in the first name / value\r
	69	pair) if the request was not successful.\r
5ca4bb9f ED	70	\r
	71	@param ProgressErr If during the processing of the KeywordString there was\r
	72	a failure, this parameter gives additional information \r
	73	about the possible source of the problem. The various \r
	74	errors are defined in "Related Definitions" below.\r
	75	\r
	76	\r
	77	@retval EFI_SUCCESS The specified action was completed successfully.\r
	78	\r
	79	@retval EFI_INVALID_PARAMETER One or more of the following are TRUE:\r
	80	1. KeywordString is NULL.\r
	81	2. Parsing of the KeywordString resulted in an \r
	82	error. See Progress and ProgressErr for more data.\r
	83	\r
	84	@retval EFI_NOT_FOUND An element of the KeywordString was not found. \r
	85	See ProgressErr for more data.\r
	86	\r
	87	@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. \r
	88	See ProgressErr for more data.\r
	89	\r
	90	@retval EFI_ACCESS_DENIED The action violated system policy. See ProgressErr \r
	91	for more data.\r
	92	\r
	93	@retval EFI_DEVICE_ERROR An unexpected system error occurred. See ProgressErr\r
	94	for more data.\r
	95	\r
	96	**/\r
	97	typedef \r
	98	EFI_STATUS\r
	99	(EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_SET_DATA) (\r
	100	IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL *This,\r
	101	IN CONST EFI_STRING KeywordString,\r
	102	OUT EFI_STRING *Progress,\r
	103	OUT UINT32 *ProgressErr\r
	104	);\r
	105	\r
	106	\r
	107	/**\r
	108	\r
	109	This function accepts a <MultiKeywordRequest> formatted string, finds the underlying \r
	110	keyword owners, creates a <MultiConfigRequest> string from it and forwards it to the\r
	111	EFI_HII_ROUTING_PROTOCOL.ExtractConfig function.\r
	112	\r
	113	If there is an issue in resolving the contents of the KeywordString, then the function\r
	114	returns an EFI_INVALID_PARAMETER and also set the Progress and ProgressErr with the\r
	115	appropriate information about where the issue occurred and additional data about the\r
	116	nature of the issue.\r
	117	\r
	118	In the case when KeywordString is NULL, or contains multiple keywords, or when\r
	119	EFI_NOT_FOUND is generated while processing the keyword elements, the Results string\r
	120	contains values returned for all keywords processed prior to the keyword generating the \r
	121	error but no values for the keyword with error or any following keywords.\r
	122	\r
	123	\r
	124	@param This Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance.\r
	125	\r
	126	@param NameSpaceId A null-terminated string containing the platform configuration\r
	127	language to search through in the system. If a NULL is passed\r
	128	in, then it is assumed that any platform configuration language\r
	129	with the prefix of "x-UEFI-" are searched.\r
	130	\r
	131	@param KeywordString A null-terminated string in <MultiKeywordRequest> format. If a\r
	132	NULL is passed in the KeywordString field, all of the known \r
	133	keywords in the system for the NameSpaceId specified are \r
134	returned in the Results field.\r
135	\r
136	@param Progress On return, points to a character in the KeywordString. Points\r
137	to the string's NULL terminator if the request was successful. \r
38baa5b6 DB	138	Points to the most recent '&' before the first failing name / value\r
	139	pair (or the beginning of the string if the failure is in the first\r
	140	name / value pair) if the request was not successful.\r
5ca4bb9f ED	141	\r
	142	@param ProgressErr If during the processing of the KeywordString there was a\r
	143	failure, this parameter gives additional information about the \r
	144	possible source of the problem. See the definitions in SetData()\r
	145	for valid value definitions.\r
	146	\r
	147	@param Results A null-terminated string in <MultiKeywordResp> format is returned\r
	148	which has all the values filled in for the keywords in the \r
	149	KeywordString. This is a callee-allocated field, and must be freed\r
	150	by the caller after being used. \r
	151	\r
	152	@retval EFI_SUCCESS The specified action was completed successfully.\r
	153	\r
	154	@retval EFI_INVALID_PARAMETER One or more of the following are TRUE:\r
	155	1.Progress, ProgressErr, or Resuts is NULL.\r
	156	2.Parsing of the KeywordString resulted in an error. See\r
	157	Progress and ProgressErr for more data.\r
	158	\r
	159	\r
	160	@retval EFI_NOT_FOUND An element of the KeywordString was not found. See\r
	161	ProgressErr for more data.\r
	162	\r
	163	@retval EFI_NOT_FOUND The NamespaceId specified was not found. See ProgressErr\r
	164	for more data.\r
	165	\r
	166	@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. See\r
	167	ProgressErr for more data.\r
	168	\r
	169	@retval EFI_ACCESS_DENIED The action violated system policy. See ProgressErr for\r
	170	more data.\r
	171	\r
	172	@retval EFI_DEVICE_ERROR An unexpected system error occurred. See ProgressErr\r
	173	for more data.\r
	174	\r
	175	**/\r
	176	typedef \r
	177	EFI_STATUS\r
	178	(EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_GET_DATA) (\r
	179	IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL *This,\r
	180	IN CONST EFI_STRING NameSpaceId, OPTIONAL\r
	181	IN CONST EFI_STRING KeywordString, OPTIONAL\r
	182	OUT EFI_STRING *Progress, \r
	183	OUT UINT32 *ProgressErr,\r
	184	OUT EFI_STRING *Results\r
	185	);\r
	186	\r
	187	///\r
	188	/// The EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL provides the mechanism \r
	189	/// to set and get the values associated with a keyword exposed \r
	190	/// through a x-UEFI- prefixed configuration language namespace\r
	191	///\r
	192	\r
	193	struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL {\r
	194	EFI_CONFIG_KEYWORD_HANDLER_SET_DATA SetData;\r
	195	EFI_CONFIG_KEYWORD_HANDLER_GET_DATA GetData;\r
	196	};\r
	197	\r
	198	extern EFI_GUID gEfiConfigKeywordHandlerProtocolGuid;\r
	199	\r
	200	#endif\r
	201	\r