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