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

/** @file\r
  This protocol is defined in UEFI spec.\r
  \r
  The EFI_FORM_BROWSER2_PROTOCOL is the interface to call for drivers to \r
  leverage the EFI configuration driver interface.\r
  \r
  Copyright (c) 2006 - 2008, 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 __EFI_FORM_BROWSER2_H__\r
#define __EFI_FORM_BROWSER2_H__\r
\r
#define EFI_FORM_BROWSER2_PROTOCOL_GUID \\r
  {0xb9d4c360, 0xbcfb, 0x4f9b, {0x92, 0x98, 0x53, 0xc1, 0x36, 0x98, 0x22, 0x58 }}\r
\r
\r
typedef struct _EFI_FORM_BROWSER2_PROTOCOL   EFI_FORM_BROWSER2_PROTOCOL;\r
\r
\r
\r
/**\r
   \r
  @param LeftColumn   Value that designates the text column\r
                      at which the browser window will begin (left-most column). \r
                      \r
  @param RightColumn  Value that designates the text\r
                      column at which the browser window will end (right-most column).\r
\r
  @param TopRow       Value that designates the text row from the\r
                      top of the screen where the browser window\r
                      will start.\r
\r
  @param BottomRow    Value that designates the text row from the\r
                      bottom of the screen where the browser\r
                      window will end. \r
**/\r
typedef struct {\r
  UINTN   LeftColumn;\r
  UINTN   RightColumn;\r
  UINTN   TopRow;\r
  UINTN   BottomRow;\r
} EFI_SCREEN_DESCRIPTOR;\r
\r
typedef UINTN EFI_BROWSER_ACTION_REQUEST;\r
\r
#define EFI_BROWSER_ACTION_REQUEST_NONE   0\r
#define EFI_BROWSER_ACTION_REQUEST_RESET  1\r
#define EFI_BROWSER_ACTION_REQUEST_SUBMIT 2\r
#define EFI_BROWSER_ACTION_REQUEST_EXIT   3\r
\r
\r
/**\r
  Initialize the browser to display the specified configuration forms.\r
\r
  This function is the primary interface to the internal forms-based browser. \r
  The forms browser will display forms associated with the specified Handles. \r
  The browser will select all forms in packages which have the specified Type \r
  and (for EFI_HII_PACKAGE_TYPE_GUID) the specified PackageGuid.\r
\r
  @param This            A pointer to the EFI_FORM_BROWSER2_PROTOCOL instance\r
\r
  @param Handles         A pointer to an array of Handles. This value should correspond \r
                         to the value of the HII form package that is required to be displayed.\r
\r
  @param HandleCount     The number of Handles specified in Handle.\r
\r
  @param FormSetGuid     This field points to the EFI_GUID which must match the Guid\r
                         field in the EFI_IFR_FORM_SET op-code for the specified\r
                         forms-based package. If FormSetGuid is NULL, then this\r
                         function will display the first found forms package.\r
\r
  @param FormId          This field specifies which EFI_IFR_FORM to render as the first\r
                         displayable page. If this field has a value of 0x0000, then\r
                         the forms browser will render the specified forms in their encoded order.\r
\r
  @param ScreenDimensions Points to recommended form dimensions, including any non-content area, in \r
                          characters.\r
\r
  @param ActionRequest   Points to the action recommended by the form.\r
\r
  @retval EFI_SUCCESS           The function completed successfully\r
  \r
  @retval EFI_NOT_FOUND         The variable was not found.\r
  \r
  @retval EFI_INVALID_PARAMETER One of the parameters has an\r
                                invalid value.  \r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SEND_FORM2)(\r
  IN CONST  EFI_FORM_BROWSER2_PROTOCOL  *This,\r
  IN        EFI_HII_HANDLE              *Handle,\r
  IN        UINTN                      HandleCount,\r
  IN        EFI_GUID                   *FormSetGuid, OPTIONAL\r
  IN        EFI_FORM_ID                FormId, OPTIONAL\r
  IN CONST  EFI_SCREEN_DESCRIPTOR      *ScreenDimensions, OPTIONAL\r
  OUT       EFI_BROWSER_ACTION_REQUEST *ActionRequest  OPTIONAL\r
);\r
\r
\r
/**\r
  This function is called by a callback handler to retrieve uncommitted state data from the browser.\r
\r
  This routine is called by a routine which was called by the\r
  browser. This routine called this service in the browser to\r
  retrieve or set certain uncommitted state information.\r
\r
  @param This           A pointer to the EFI_FORM_BROWSER2_PROTOCOL instance.\r
\r
  @param ResultsDataSize  A pointer to the size of the buffer\r
                          associated with ResultsData. On input, the size in\r
                          bytes of ResultsData. On output, the size of data returned in ResultsData.\r
\r
  @param ResultsData    A string returned from an IFR browser or\r
                        equivalent. The results string will have\r
                        no routing information in them.\r
\r
  @param RetrieveData   A BOOLEAN field which allows an agent to\r
                        retrieve (if RetrieveData = TRUE) data\r
                        from the uncommitted browser state\r
                        information or set (if RetrieveData =\r
                        FALSE) data in the uncommitted browser\r
                        state information.\r
\r
  @param VariableGuid   An optional field to indicate the target\r
                        variable GUID name to use.\r
\r
  @param VariableName   An optional field to indicate the target\r
                        human-readable variable name.\r
\r
  @retval EFI_SUCCESS           The results have been distributed or are\r
                                awaiting distribution.\r
  \r
  @retval EFI_OUT_OF_RESOURCES  The ResultsDataSize specified\r
                                was too small to contain the\r
                                results data.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_BROWSER_CALLBACK2)(\r
  IN CONST  EFI_FORM_BROWSER2_PROTOCOL *This,\r
  IN OUT    UINTN                     *ResultsDataSize,\r
  IN OUT    EFI_STRING                ResultsData,\r
  IN CONST  BOOLEAN                   RetrieveData,\r
  IN CONST  EFI_GUID                  *VariableGuid, OPTIONAL\r
  IN CONST  CHAR16                    *VariableName OPTIONAL\r
);\r
\r
///\r
/// This interface will allow the caller to direct the configuration \r
/// driver to use either the HII database or use the passed-in packet of data.\r
///\r
struct _EFI_FORM_BROWSER2_PROTOCOL {\r
  EFI_SEND_FORM2         SendForm;\r
  EFI_BROWSER_CALLBACK2  BrowserCallback;\r
} ;\r
\r
extern EFI_GUID gEfiFormBrowser2ProtocolGuid;\r
\r
#endif\r
\r
Commit	Line	Data
	1	/** @file\r
	2	This protocol is defined in UEFI spec.\r
	3	\r
	4	The EFI_FORM_BROWSER2_PROTOCOL is the interface to call for drivers to \r
	5	leverage the EFI configuration driver interface.\r
	6	\r
	7	Copyright (c) 2006 - 2008, Intel Corporation\r
	8	All rights reserved. This program and the accompanying materials \r
	9	are licensed and made available under the terms and conditions of the BSD License \r
	10	which accompanies this distribution. The full text of the license may be found at \r
	11	http://opensource.org/licenses/bsd-license.php \r
	12	\r
	13	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	14	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	15	\r
	16	**/\r
	17	\r
	18	#ifndef __EFI_FORM_BROWSER2_H__\r
	19	#define __EFI_FORM_BROWSER2_H__\r
	20	\r
	21	#define EFI_FORM_BROWSER2_PROTOCOL_GUID \\r
	22	{0xb9d4c360, 0xbcfb, 0x4f9b, {0x92, 0x98, 0x53, 0xc1, 0x36, 0x98, 0x22, 0x58 }}\r
	23	\r
	24	\r
	25	typedef struct _EFI_FORM_BROWSER2_PROTOCOL EFI_FORM_BROWSER2_PROTOCOL;\r
	26	\r
	27	\r
	28	\r
	29	/**\r
	30	\r
	31	@param LeftColumn Value that designates the text column\r
	32	at which the browser window will begin (left-most column). \r
	33	\r
	34	@param RightColumn Value that designates the text\r
	35	column at which the browser window will end (right-most column).\r
	36	\r
	37	@param TopRow Value that designates the text row from the\r
	38	top of the screen where the browser window\r
	39	will start.\r
	40	\r
	41	@param BottomRow Value that designates the text row from the\r
	42	bottom of the screen where the browser\r
	43	window will end. \r
	44	**/\r
	45	typedef struct {\r
	46	UINTN LeftColumn;\r
	47	UINTN RightColumn;\r
	48	UINTN TopRow;\r
	49	UINTN BottomRow;\r
	50	} EFI_SCREEN_DESCRIPTOR;\r
	51	\r
	52	typedef UINTN EFI_BROWSER_ACTION_REQUEST;\r
	53	\r
	54	#define EFI_BROWSER_ACTION_REQUEST_NONE 0\r
	55	#define EFI_BROWSER_ACTION_REQUEST_RESET 1\r
	56	#define EFI_BROWSER_ACTION_REQUEST_SUBMIT 2\r
	57	#define EFI_BROWSER_ACTION_REQUEST_EXIT 3\r
	58	\r
	59	\r
	60	/**\r
	61	Initialize the browser to display the specified configuration forms.\r
	62	\r
	63	This function is the primary interface to the internal forms-based browser. \r
	64	The forms browser will display forms associated with the specified Handles. \r
	65	The browser will select all forms in packages which have the specified Type \r
	66	and (for EFI_HII_PACKAGE_TYPE_GUID) the specified PackageGuid.\r
	67	\r
	68	@param This A pointer to the EFI_FORM_BROWSER2_PROTOCOL instance\r
	69	\r
	70	@param Handles A pointer to an array of Handles. This value should correspond \r
	71	to the value of the HII form package that is required to be displayed.\r
	72	\r
	73	@param HandleCount The number of Handles specified in Handle.\r
	74	\r
	75	@param FormSetGuid This field points to the EFI_GUID which must match the Guid\r
	76	field in the EFI_IFR_FORM_SET op-code for the specified\r
	77	forms-based package. If FormSetGuid is NULL, then this\r
	78	function will display the first found forms package.\r
	79	\r
	80	@param FormId This field specifies which EFI_IFR_FORM to render as the first\r
	81	displayable page. If this field has a value of 0x0000, then\r
	82	the forms browser will render the specified forms in their encoded order.\r
	83	\r
	84	@param ScreenDimensions Points to recommended form dimensions, including any non-content area, in \r
	85	characters.\r
	86	\r
	87	@param ActionRequest Points to the action recommended by the form.\r
	88	\r
	89	@retval EFI_SUCCESS The function completed successfully\r
	90	\r
	91	@retval EFI_NOT_FOUND The variable was not found.\r
	92	\r
	93	@retval EFI_INVALID_PARAMETER One of the parameters has an\r
	94	invalid value. \r
	95	**/\r
	96	typedef\r
	97	EFI_STATUS\r
	98	(EFIAPI *EFI_SEND_FORM2)(\r
	99	IN CONST EFI_FORM_BROWSER2_PROTOCOL *This,\r
	100	IN EFI_HII_HANDLE *Handle,\r
	101	IN UINTN HandleCount,\r
	102	IN EFI_GUID *FormSetGuid, OPTIONAL\r
	103	IN EFI_FORM_ID FormId, OPTIONAL\r
	104	IN CONST EFI_SCREEN_DESCRIPTOR *ScreenDimensions, OPTIONAL\r
	105	OUT EFI_BROWSER_ACTION_REQUEST *ActionRequest OPTIONAL\r
	106	);\r
	107	\r
	108	\r
	109	/**\r
	110	This function is called by a callback handler to retrieve uncommitted state data from the browser.\r
	111	\r
	112	This routine is called by a routine which was called by the\r
	113	browser. This routine called this service in the browser to\r
	114	retrieve or set certain uncommitted state information.\r
	115	\r
	116	@param This A pointer to the EFI_FORM_BROWSER2_PROTOCOL instance.\r
	117	\r
	118	@param ResultsDataSize A pointer to the size of the buffer\r
	119	associated with ResultsData. On input, the size in\r
	120	bytes of ResultsData. On output, the size of data returned in ResultsData.\r
	121	\r
	122	@param ResultsData A string returned from an IFR browser or\r
	123	equivalent. The results string will have\r
	124	no routing information in them.\r
	125	\r
	126	@param RetrieveData A BOOLEAN field which allows an agent to\r
	127	retrieve (if RetrieveData = TRUE) data\r
	128	from the uncommitted browser state\r
	129	information or set (if RetrieveData =\r
	130	FALSE) data in the uncommitted browser\r
	131	state information.\r
	132	\r
	133	@param VariableGuid An optional field to indicate the target\r
	134	variable GUID name to use.\r
	135	\r
	136	@param VariableName An optional field to indicate the target\r
	137	human-readable variable name.\r
	138	\r
	139	@retval EFI_SUCCESS The results have been distributed or are\r
	140	awaiting distribution.\r
	141	\r
	142	@retval EFI_OUT_OF_RESOURCES The ResultsDataSize specified\r
	143	was too small to contain the\r
	144	results data.\r
	145	\r
	146	**/\r
	147	typedef\r
	148	EFI_STATUS\r
	149	(EFIAPI *EFI_BROWSER_CALLBACK2)(\r
	150	IN CONST EFI_FORM_BROWSER2_PROTOCOL *This,\r
	151	IN OUT UINTN *ResultsDataSize,\r
	152	IN OUT EFI_STRING ResultsData,\r
	153	IN CONST BOOLEAN RetrieveData,\r
	154	IN CONST EFI_GUID *VariableGuid, OPTIONAL\r
	155	IN CONST CHAR16 *VariableName OPTIONAL\r
	156	);\r
	157	\r
	158	///\r
	159	/// This interface will allow the caller to direct the configuration \r
	160	/// driver to use either the HII database or use the passed-in packet of data.\r
	161	///\r
	162	struct _EFI_FORM_BROWSER2_PROTOCOL {\r
	163	EFI_SEND_FORM2 SendForm;\r
	164	EFI_BROWSER_CALLBACK2 BrowserCallback;\r
	165	} ;\r
	166	\r
	167	extern EFI_GUID gEfiFormBrowser2ProtocolGuid;\r
	168	\r
	169	#endif\r
	170	\r