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