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

/** @file\r
  The file provides services to manage the movement of\r
  configuration data from drivers to configuration applications.\r
  It then serves as the single point to receive configuration\r
  information from configuration applications, routing the\r
  results to the appropriate drivers.\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_CONFIG_ROUTING_H__\r
#define __HII_CONFIG_ROUTING_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_CONFIG_ROUTING_PROTOCOL_GUID \\r
  { 0x587e72d7, 0xcc50, 0x4f79, { 0x82, 0x09, 0xca, 0x29, 0x1f, 0xc1, 0xa1, 0x0f } }\r
\r
\r
typedef struct _EFI_HII_CONFIG_ROUTING_PROTOCOL EFI_HII_CONFIG_ROUTING_PROTOCOL;\r
\r
\r
/**\r
   \r
  This function allows the caller to request the current\r
  configuration for one or more named elements from one or more\r
  drivers. The resulting string is in the standard HII\r
  configuration string format. If Successful Results contains an\r
  equivalent string with "=" and the values associated with all\r
  names added in. The expected implementation is for each\r
  <ConfigRequest> substring in the Request, call the HII\r
  Configuration Routing Protocol ExtractProtocol function for the\r
  driver corresponding to the <ConfigHdr> at the start of the\r
  <ConfigRequest> substring. The request fails if no driver\r
  matches the <ConfigRequest> substring. Note: Alternative\r
  configuration strings may also be appended to the end of the\r
  current configuration string. If they are, they must appear\r
  after the current configuration. They must contain the same\r
  routing (GUID, NAME, PATH) as the current configuration string.\r
  They must have an additional description indicating the type of\r
  alternative configuration the string represents,\r
  "ALTCFG=<StringToken>". That <StringToken> (when converted from\r
  Hex UNICODE to binary) is a reference to a string in the\r
  associated string pack. As an example, assume that the Request\r
  string is:\r
  GUID=...&NAME=00480050&PATH=...&Fred&George&Ron&Neville A result\r
  might be:\r
  GUID=...&NAME=00480050&PATH=...&Fred=16&George=16&Ron=12&Neville=11&\r
  GUID=...&NAME=00480050&PATH=...&ALTCFG=0037&Fred=12&Neville=7\r
\r
  @param This   Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL\r
                instance.\r
\r
  @param Request  A null-terminated Unicode string in\r
                  <MultiConfigRequest> format.\r
\r
  @param Progress   On return, points to a character in the\r
                    Request string. Points to the string's null\r
                    terminator if request was successful. Points\r
                    to the most recent '&' before the first\r
                    failing name / value pair (or the beginning\r
                    of the string if the failure is in the first\r
                    name / value pair) if the request was not\r
                    successful\r
\r
  @param Results    Null-terminated Unicode string in\r
                    <MultiConfigAltResp> format which has all\r
                    values filled in for the names in the\r
                    Request string. String to be allocated by\r
                    the called function.\r
\r
  @retval EFI_SUCCESS   The Results string is filled with the\r
                        values corresponding to all requested\r
                        names.\r
\r
  @retval EFI_OUT_OF_MEMORY   Not enough memory to store the\r
                              parts of the results that must be\r
                              stored awaiting possible future\r
                              protocols.\r
\r
  @retval EFI_INVALID_PARAMETER   For example, passing in a NULL\r
                                  for the Request parameter\r
                                  would result in this type of\r
                                  error. The Progress parameter\r
                                  is set to NULL. EFI_NOT_FOUND\r
                                  Routing data doesn't match any\r
                                  known driver. Progress set to\r
                                  the "G" in "GUID" of the\r
                                  routing header that doesn't\r
                                  match. Note: There is no\r
                                  requirement that all routing\r
                                  data be validated before any\r
                                  configuration extraction.\r
\r
  @retval EFI_INVALID_PARAMETER   Illegal syntax. Progress set\r
                                  to most recent & before the\r
                                  error or the beginning of the\r
                                  string.\r
  @retval EFI_INVALID_PARAMETER   Unknown name.\r
\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_HII_ROUTING_EXTRACT_CONFIG ) (\r
  IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
  IN CONST  EFI_STRING                      *Request,\r
  OUT       EFI_STRING                      *Progress,\r
  OUT       EFI_STRING                      *Results\r
);\r
\r
/**\r
   \r
  This function allows the caller to request the current\r
  configuration for all of the current HII database. The results\r
  include both the current and alternate configurations as\r
  described in ExtractConfig() above. Implementation note: This\r
  call has deceptively few inputs but the implementation is likely\r
  to be somewhat complex. The requirement is to scan all IFR in\r
  the HII database to determine the list of names and then request\r
  the configuration using the corresponding drivers??\r
  EFI_HII_CONFIG_ACCESS_PROTOCOL.ExtractConfig() interfaces below.\r
  \r
  @param This   Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL\r
                instance.\r
  \r
  @param Results  A null-terminated Unicode string in\r
                  <MultiConfigAltResp> format which has all\r
                  values filled in for the names in the Request\r
                  string. String to be allocated by this\r
                  function. De-allocation is up to the caller.\r
  \r
  @retval EFI_SUCCESS   The Results string is filled with the\r
                        values corresponding to all requested\r
                        names.\r
  \r
  @retval EFI_OUT_OF_MEMORY   Not enough memory to store the\r
                              parts of the results that must be\r
                              stored awaiting possible future\r
                              protocols.\r
  \r
  @retval EFI_INVALID_PARAMETERS  For example, passing in a NULL\r
                                  for the Results parameter\r
                                  would result in this type of\r
                                  error.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_HII_ROUTING_EXPORT_CONFIG ) (\r
  IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
  OUT       EFI_STRING                      *Results\r
);\r
\r
/**\r
   \r
  This function routes the results of processing forms to the\r
  appropriate targets. It scans for <ConfigHdr> within the string\r
  and passes the header and subsequent body to the driver whose\r
  location is described in the <ConfigHdr>. Many <ConfigHdr>s may\r
  appear as a single request. The expected implementation is to\r
  hand off the various <ConfigResp> substrings to the\r
  Configuration Access Protocol RouteConfig routine corresponding\r
  to the driver whose routing information is defined by the\r
  <ConfigHdr> in turn.\r
\r
  @param This   Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL\r
                instance.\r
\r
  @param Configuration  A null-terminated Unicode string in\r
                        <MulltiConfigResp> format.\r
\r
  @param Progress   A pointer to a string filled in with the\r
                    offset of the most recent '&' before the\r
                    first failing name / value pair (or the\r
                    beginning of the string if the failure is in\r
                    the first name / value pair) or the\r
                    terminating NULL if all was successful.\r
\r
  @retval EFI_SUCCESS   The results have been distributed or are\r
                        awaiting distribution.\r
  \r
  @retval EFI_OUT_OF_MEMORY   Not enough memory to store the\r
                              parts of the results that must be\r
                              stored awaiting possible future\r
                              protocols.\r
  \r
  @retval EFI_INVALID_PARAMETERS  Passing in a NULL for the\r
                                  Results parameter would result\r
                                  in this type of error.\r
  \r
  @retval EFI_NOT_FOUND   Target for the specified routing data\r
                          was not found\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_HII_ROUTING_ROUTE_CONFIG ) (\r
  IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
  IN CONST  EFI_STRING                      Configuration,\r
  OUT       EFI_STRING                      *Progress\r
);\r
\r
\r
/**\r
   \r
  This function extracts the current configuration from a block of\r
  bytes. To do so, it requires that the ConfigRequest string\r
  consists of a list of <BlockName> formatted names. It uses the\r
  offset in the name to determine the index into the Block to\r
  start the extraction and the width of each name to determine the\r
  number of bytes to extract. These are mapped to a UNICODE value\r
  using the equivalent of the C "%x" format (with optional leading\r
  spaces). The call fails if, for any (offset, width) pair in\r
  ConfigRequest, offset+value >= BlockSize.\r
\r
  @param This   Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL\r
                instance.\r
\r
  @param ConfigRequest  A null-terminated Unicode string in\r
                        <ConfigRequest> format.\r
\r
  @param Block  Array of bytes defining the block's\r
                configuration.\r
\r
  @param BlockSize  Length in bytes of Block.\r
\r
  @param Config   Filled-in configuration string. String\r
                  allocated by the function. Returned only if\r
                  call is successful.\r
\r
  @param Progress   A pointer to a string filled in with the\r
                    offset of the most recent '&' before the\r
                    first failing name / value pair (or the\r
                    beginning of the string if the failure is in\r
                    the first name / value pair) or the\r
                    terminating NULL if all was successful.\r
\r
  @retval EFI_SUCCESS   The request succeeded. Progress points\r
                        to the null terminator at the end of the\r
                        ConfigRequest string.\r
  @retval EFI_OUT_OF_MEMORY   Not enough memory to allocate\r
                              Config. Progress points to the\r
                              first character of ConfigRequest.\r
\r
  @retval EFI_INVALID_PARAMETERS  Passing in a NULL for the\r
                                  ConfigRequest or Block\r
                                  parameter would result in this\r
                                  type of error. Progress points\r
                                  to the first character of\r
                                  ConfigRequest.\r
\r
  @retval EFI_NOT_FOUND   Target for the specified routing data\r
                          was not found. Progress points to the\r
                          'G' in "GUID" of the errant routing\r
                          data. EFI_DEVICE_ERROR Block not large\r
                          enough. Progress undefined.\r
\r
  @retval EFI_INVALID_PARAMETER   Encountered non <BlockName>\r
                                  formatted string. Block is\r
                                  left updated and Progress\r
                                  points at the '&' preceding\r
                                  the first non-<BlockName>.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_HII_ROUTING_BLOCK_TO_CONFIG ) (\r
  IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
  IN CONST  EFI_STRING                      ConfigRequest,\r
  IN CONST  UINT8                           *Block,\r
  IN CONST  UINTN                           BlockSize,\r
  OUT       EFI_STRING                      **Config,\r
  OUT       EFI_STRING                      *Progress\r
);\r
\r
\r
\r
/**\r
   \r
  This function maps a configuration containing a series of\r
  <BlockConfig> formatted name value pairs in ConfigResp into a\r
  Block so it may be stored in a linear mapped storage such as a\r
  UEFI Variable. If present, the function skips GUID, NAME, and\r
  PATH in <ConfigResp>. It stops when it finds a non-<BlockConfig>\r
  name / value pair (after skipping the routing header) or when it\r
  reaches the end of the string.\r
  Example Assume an existing block containing: 00 01 02 03 04 05\r
  And the ConfigResp string is:\r
  OFFSET=4&WIDTH=1&VALUE=7&OFFSET=0&WIDTH=2&VALUE=AA55\r
  The results are\r
  55 AA 02 07 04 05\r
\r
  @param This   Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL\r
                instance.\r
\r
  @param ConfigResp   A  null-terminated Unicode string in\r
                      <ConfigResp> format.\r
\r
  @param CurrentBlock   A possibly null array of bytes\r
                        representing the current block. Only\r
                        bytes referenced in the ConfigResp\r
                        string in the block are modified. If\r
                        this parameter is null or if the\r
                        BlockLength parameter is (on input)\r
                        shorter than required by the\r
                        Configuration string, only the BlockSize\r
                        parameter is updated and an appropriate\r
                        status (see below) is returned.\r
\r
  @param BlockSize  The length of the Block in units of UINT8.\r
                    On input, this is the size of the Block. On\r
                    output, if successful, contains the index of\r
                    the last modified byte in the Block.\r
\r
  @param Progress   On return, points to an element of the\r
                    ConfigResp string filled in with the offset\r
                    of the most recent "&" before the first\r
                    failing name / value pair (or the beginning\r
                    of the string if the failure is in the first\r
                    name / value pair) or the terminating NULL\r
                    if all was successful.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI * EFI_HII_ROUTING_CONFIG_TO_BLOCK ) (\r
  IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
  IN CONST  EFI_STRING                      *ConfigResp,\r
  IN CONST  UINT8                           *Block,\r
  IN OUT    UINTN                           *BlockSize,\r
  OUT       EFI_STRING                      *Progress\r
);\r
\r
\r
/**\r
   \r
  This protocol defines the configuration routing interfaces\r
  between external applications and the HII. There may only be one\r
  instance of this protocol in the system.\r
\r
**/\r
struct _EFI_HII_CONFIG_ROUTING_PROTOCOL {\r
  EFI_HII_ROUTING_EXTRACT_CONFIG  ExtractConfig;\r
  EFI_HII_ROUTING_EXPORT_CONFIG   ExportConfig;\r
  EFI_HII_ROUTING_ROUTE_CONFIG    RouteConfig;\r
  EFI_HII_ROUTING_BLOCK_TO_CONFIG BlockToConfig;\r
  EFI_HII_ROUTING_CONFIG_TO_BLOCK ConfigToBlock;\r
};\r
\r
extern EFI_GUID gEfiHiiConfigRoutingProtocolGuid;\r
\r
\r
#endif\r
\r
Commit	Line	Data
d1f95000	1	/** @file\r
	2	The file provides services to manage the movement of\r
	3	configuration data from drivers to configuration applications.\r
	4	It then serves as the single point to receive configuration\r
	5	information from configuration applications, routing the\r
	6	results to the appropriate drivers.\r
	7	\r
	8	Copyright (c) 2006 - 2007, Intel Corporation\r
	9	All rights reserved. This program and the accompanying materials \r
	10	are licensed and made available under the terms and conditions of the BSD License \r
	11	which accompanies this distribution. The full text of the license may be found at \r
	12	http://opensource.org/licenses/bsd-license.php \r
	13	\r
	14	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	15	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	16	\r
d1f95000	17	**/\r
	18	\r
	19	#ifndef __HII_CONFIG_ROUTING_H__\r
	20	#define __HII_CONFIG_ROUTING_H__\r
	21	\r
1528fae8	22	#error "UEFI 2.1 HII is not fully implemented for now, Please don't include this file now."\r
1528fae8	23	\r
d1f95000	24	#define EFI_HII_CONFIG_ROUTING_PROTOCOL_GUID \\r
	25	{ 0x587e72d7, 0xcc50, 0x4f79, { 0x82, 0x09, 0xca, 0x29, 0x1f, 0xc1, 0xa1, 0x0f } }\r
	26	\r
	27	\r
	28	typedef struct _EFI_HII_CONFIG_ROUTING_PROTOCOL EFI_HII_CONFIG_ROUTING_PROTOCOL;\r
	29	\r
	30	\r
	31	/**\r
	32	\r
	33	This function allows the caller to request the current\r
	34	configuration for one or more named elements from one or more\r
	35	drivers. The resulting string is in the standard HII\r
	36	configuration string format. If Successful Results contains an\r
	37	equivalent string with "=" and the values associated with all\r
	38	names added in. The expected implementation is for each\r
	39	<ConfigRequest> substring in the Request, call the HII\r
	40	Configuration Routing Protocol ExtractProtocol function for the\r
	41	driver corresponding to the <ConfigHdr> at the start of the\r
	42	<ConfigRequest> substring. The request fails if no driver\r
	43	matches the <ConfigRequest> substring. Note: Alternative\r
	44	configuration strings may also be appended to the end of the\r
	45	current configuration string. If they are, they must appear\r
	46	after the current configuration. They must contain the same\r
	47	routing (GUID, NAME, PATH) as the current configuration string.\r
	48	They must have an additional description indicating the type of\r
	49	alternative configuration the string represents,\r
	50	"ALTCFG=<StringToken>". That <StringToken> (when converted from\r
	51	Hex UNICODE to binary) is a reference to a string in the\r
	52	associated string pack. As an example, assume that the Request\r
	53	string is:\r
	54	GUID=...&NAME=00480050&PATH=...&Fred&George&Ron&Neville A result\r
	55	might be:\r
	56	GUID=...&NAME=00480050&PATH=...&Fred=16&George=16&Ron=12&Neville=11&\r
	57	GUID=...&NAME=00480050&PATH=...&ALTCFG=0037&Fred=12&Neville=7\r
	58	\r
	59	@param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL\r
	60	instance.\r
	61	\r
	62	@param Request A null-terminated Unicode string in\r
	63	<MultiConfigRequest> format.\r
	64	\r
	65	@param Progress On return, points to a character in the\r
	66	Request string. Points to the string's null\r
	67	terminator if request was successful. Points\r
	68	to the most recent '&' before the first\r
	69	failing name / value pair (or the beginning\r
	70	of the string if the failure is in the first\r
	71	name / value pair) if the request was not\r
	72	successful\r
	73	\r
	74	@param Results Null-terminated Unicode string in\r
	75	<MultiConfigAltResp> format which has all\r
	76	values filled in for the names in the\r
	77	Request string. String to be allocated by\r
	78	the called function.\r
	79	\r
	80	@retval EFI_SUCCESS The Results string is filled with the\r
	81	values corresponding to all requested\r
	82	names.\r
	83	\r
	84	@retval EFI_OUT_OF_MEMORY Not enough memory to store the\r
	85	parts of the results that must be\r
	86	stored awaiting possible future\r
	87	protocols.\r
88	\r
89	@retval EFI_INVALID_PARAMETER For example, passing in a NULL\r
90	for the Request parameter\r
91	would result in this type of\r
92	error. The Progress parameter\r
93	is set to NULL. EFI_NOT_FOUND\r
94	Routing data doesn't match any\r
95	known driver. Progress set to\r
96	the "G" in "GUID" of the\r
97	routing header that doesn't\r
98	match. Note: There is no\r
99	requirement that all routing\r
100	data be validated before any\r
101	configuration extraction.\r
102	\r
103	@retval EFI_INVALID_PARAMETER Illegal syntax. Progress set\r
104	to most recent & before the\r
105	error or the beginning of the\r
106	string.\r
107	@retval EFI_INVALID_PARAMETER Unknown name.\r
108	\r
109	\r
110	**/\r
111	typedef\r
112	EFI_STATUS\r
113	(EFIAPI * EFI_HII_ROUTING_EXTRACT_CONFIG ) (\r
114	IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
115	IN CONST EFI_STRING *Request,\r
116	OUT EFI_STRING *Progress,\r
117	OUT EFI_STRING *Results\r
118	);\r
119	\r
120	/**\r
121	\r
122	This function allows the caller to request the current\r
123	configuration for all of the current HII database. The results\r
124	include both the current and alternate configurations as\r
125	described in ExtractConfig() above. Implementation note: This\r
126	call has deceptively few inputs but the implementation is likely\r
127	to be somewhat complex. The requirement is to scan all IFR in\r
128	the HII database to determine the list of names and then request\r
129	the configuration using the corresponding drivers??\r
130	EFI_HII_CONFIG_ACCESS_PROTOCOL.ExtractConfig() interfaces below.\r
131	\r
132	@param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL\r
133	instance.\r
134	\r
135	@param Results A null-terminated Unicode string in\r
136	<MultiConfigAltResp> format which has all\r
137	values filled in for the names in the Request\r
138	string. String to be allocated by this\r
139	function. De-allocation is up to the caller.\r
140	\r
141	@retval EFI_SUCCESS The Results string is filled with the\r
142	values corresponding to all requested\r
143	names.\r
144	\r
145	@retval EFI_OUT_OF_MEMORY Not enough memory to store the\r
146	parts of the results that must be\r
147	stored awaiting possible future\r
148	protocols.\r
149	\r
150	@retval EFI_INVALID_PARAMETERS For example, passing in a NULL\r
151	for the Results parameter\r
152	would result in this type of\r
153	error.\r
154	\r
155	**/\r
156	typedef\r
157	EFI_STATUS\r
158	(EFIAPI * EFI_HII_ROUTING_EXPORT_CONFIG ) (\r
159	IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
160	OUT EFI_STRING *Results\r
161	);\r
162	\r
163	/**\r
164	\r
165	This function routes the results of processing forms to the\r
166	appropriate targets. It scans for <ConfigHdr> within the string\r
167	and passes the header and subsequent body to the driver whose\r
168	location is described in the <ConfigHdr>. Many <ConfigHdr>s may\r
169	appear as a single request. The expected implementation is to\r
170	hand off the various <ConfigResp> substrings to the\r
171	Configuration Access Protocol RouteConfig routine corresponding\r
172	to the driver whose routing information is defined by the\r
173	<ConfigHdr> in turn.\r
174	\r
175	@param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL\r
176	instance.\r
177	\r
178	@param Configuration A null-terminated Unicode string in\r
179	<MulltiConfigResp> format.\r
180	\r
181	@param Progress A pointer to a string filled in with the\r
182	offset of the most recent '&' before the\r
183	first failing name / value pair (or the\r
184	beginning of the string if the failure is in\r
185	the first name / value pair) or the\r
186	terminating NULL if all was successful.\r
187	\r
188	@retval EFI_SUCCESS The results have been distributed or are\r
189	awaiting distribution.\r
190	\r
191	@retval EFI_OUT_OF_MEMORY Not enough memory to store the\r
192	parts of the results that must be\r
193	stored awaiting possible future\r
194	protocols.\r
195	\r
196	@retval EFI_INVALID_PARAMETERS Passing in a NULL for the\r
197	Results parameter would result\r
198	in this type of error.\r
199	\r
200	@retval EFI_NOT_FOUND Target for the specified routing data\r
201	was not found\r
202	\r
203	**/\r
204	typedef\r
205	EFI_STATUS\r
206	(EFIAPI * EFI_HII_ROUTING_ROUTE_CONFIG ) (\r
207	IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
208	IN CONST EFI_STRING Configuration,\r
209	OUT EFI_STRING *Progress\r
210	);\r
211	\r
212	\r
213	/**\r
214	\r
215	This function extracts the current configuration from a block of\r
216	bytes. To do so, it requires that the ConfigRequest string\r
217	consists of a list of <BlockName> formatted names. It uses the\r
218	offset in the name to determine the index into the Block to\r
219	start the extraction and the width of each name to determine the\r
220	number of bytes to extract. These are mapped to a UNICODE value\r
221	using the equivalent of the C "%x" format (with optional leading\r
222	spaces). The call fails if, for any (offset, width) pair in\r
223	ConfigRequest, offset+value >= BlockSize.\r
224	\r
225	@param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL\r
226	instance.\r
227	\r
228	@param ConfigRequest A null-terminated Unicode string in\r
229	<ConfigRequest> format.\r
230	\r
231	@param Block Array of bytes defining the block's\r
232	configuration.\r
233	\r
234	@param BlockSize Length in bytes of Block.\r
235	\r
236	@param Config Filled-in configuration string. String\r
237	allocated by the function. Returned only if\r
238	call is successful.\r
239	\r
240	@param Progress A pointer to a string filled in with the\r
241	offset of the most recent '&' before the\r
242	first failing name / value pair (or the\r
243	beginning of the string if the failure is in\r
244	the first name / value pair) or the\r
245	terminating NULL if all was successful.\r
246	\r
247	@retval EFI_SUCCESS The request succeeded. Progress points\r
248	to the null terminator at the end of the\r
249	ConfigRequest string.\r
250	@retval EFI_OUT_OF_MEMORY Not enough memory to allocate\r
251	Config. Progress points to the\r
252	first character of ConfigRequest.\r
253	\r
254	@retval EFI_INVALID_PARAMETERS Passing in a NULL for the\r
255	ConfigRequest or Block\r
256	parameter would result in this\r
257	type of error. Progress points\r
258	to the first character of\r
259	ConfigRequest.\r
260	\r
261	@retval EFI_NOT_FOUND Target for the specified routing data\r
262	was not found. Progress points to the\r
263	'G' in "GUID" of the errant routing\r
264	data. EFI_DEVICE_ERROR Block not large\r
265	enough. Progress undefined.\r
266	\r
267	@retval EFI_INVALID_PARAMETER Encountered non <BlockName>\r
268	formatted string. Block is\r
269	left updated and Progress\r
270	points at the '&' preceding\r
271	the first non-<BlockName>.\r
272	\r
273	**/\r
274	typedef\r
275	EFI_STATUS\r
276	(EFIAPI * EFI_HII_ROUTING_BLOCK_TO_CONFIG ) (\r
277	IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
278	IN CONST EFI_STRING ConfigRequest,\r
279	IN CONST UINT8 *Block,\r
280	IN CONST UINTN BlockSize,\r
281	OUT EFI_STRING **Config,\r
282	OUT EFI_STRING *Progress\r
283	);\r
284	\r
285	\r
286	\r
287	/**\r
288	\r
289	This function maps a configuration containing a series of\r
290	<BlockConfig> formatted name value pairs in ConfigResp into a\r
291	Block so it may be stored in a linear mapped storage such as a\r
292	UEFI Variable. If present, the function skips GUID, NAME, and\r
293	PATH in <ConfigResp>. It stops when it finds a non-<BlockConfig>\r
294	name / value pair (after skipping the routing header) or when it\r
295	reaches the end of the string.\r
296	Example Assume an existing block containing: 00 01 02 03 04 05\r
297	And the ConfigResp string is:\r
298	OFFSET=4&WIDTH=1&VALUE=7&OFFSET=0&WIDTH=2&VALUE=AA55\r
299	The results are\r
300	55 AA 02 07 04 05\r
301	\r
302	@param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL\r
303	instance.\r
304	\r
305	@param ConfigResp A null-terminated Unicode string in\r
306	<ConfigResp> format.\r
307	\r
308	@param CurrentBlock A possibly null array of bytes\r
309	representing the current block. Only\r
310	bytes referenced in the ConfigResp\r
311	string in the block are modified. If\r
312	this parameter is null or if the\r
313	BlockLength parameter is (on input)\r
314	shorter than required by the\r
315	Configuration string, only the BlockSize\r
316	parameter is updated and an appropriate\r
317	status (see below) is returned.\r
318	\r
319	@param BlockSize The length of the Block in units of UINT8.\r
320	On input, this is the size of the Block. On\r
321	output, if successful, contains the index of\r
322	the last modified byte in the Block.\r
323	\r
324	@param Progress On return, points to an element of the\r
325	ConfigResp string filled in with the offset\r
326	of the most recent "&" before the first\r
327	failing name / value pair (or the beginning\r
328	of the string if the failure is in the first\r
329	name / value pair) or the terminating NULL\r
330	if all was successful.\r
331	\r
332	**/\r
333	typedef\r
334	EFI_STATUS\r
335	(EFIAPI * EFI_HII_ROUTING_CONFIG_TO_BLOCK ) (\r
336	IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
337	IN CONST EFI_STRING *ConfigResp,\r
338	IN CONST UINT8 *Block,\r
339	IN OUT UINTN *BlockSize,\r
340	OUT EFI_STRING *Progress\r
341	);\r
342	\r
343	\r
344	/**\r
345	\r
346	This protocol defines the configuration routing interfaces\r
347	between external applications and the HII. There may only be one\r
348	instance of this protocol in the system.\r
349	\r
350	**/\r
351	struct _EFI_HII_CONFIG_ROUTING_PROTOCOL {\r
352	EFI_HII_ROUTING_EXTRACT_CONFIG ExtractConfig;\r
353	EFI_HII_ROUTING_EXPORT_CONFIG ExportConfig;\r
354	EFI_HII_ROUTING_ROUTE_CONFIG RouteConfig;\r
355	EFI_HII_ROUTING_BLOCK_TO_CONFIG BlockToConfig;\r
356	EFI_HII_ROUTING_CONFIG_TO_BLOCK ConfigToBlock;\r
357	};\r
358	\r
359	extern EFI_GUID gEfiHiiConfigRoutingProtocolGuid;\r
360	\r
361	\r
362	#endif\r
363	\r