[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
                      where the browser window will begin from\r
                      the left-hand side of the screen\r
                      \r
  @param RightColumn  Value that designates the text\r
                      column where the browser window will end\r
                      on the right-hand side of the screen.\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
  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. Type\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
   \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
  @par Protocol Description: \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
d1f95000	1	/** @file\r
4ca9b6c4 LG	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
d1f95000	6	\r
4ca9b6c4	7	Copyright (c) 2006 - 2008, Intel Corporation\r
d1f95000	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
d1f95000	16	**/\r
d1f95000	17	\r
4ca9b6c4 LG	18	#ifndef __EFI_FORM_BROWSER2_H__\r
4ca9b6c4 LG	19	#define __EFI_FORM_BROWSER2_H__\r
d1f95000	20	\r
5a1fc221	21	#define EFI_FORM_BROWSER2_PROTOCOL_GUID \\r
7d582d6b	22	{0xb9d4c360, 0xbcfb, 0x4f9b, {0x92, 0x98, 0x53, 0xc1, 0x36, 0x98, 0x22, 0x58 }}\r
d1f95000	23	\r
d1f95000	24	\r
5a1fc221	25	typedef struct _EFI_FORM_BROWSER2_PROTOCOL EFI_FORM_BROWSER2_PROTOCOL;\r
d1f95000	26	\r
	27	\r
	28	\r
	29	/**\r
	30	\r
	31	@param LeftColumn Value that designates the text column\r
	32	where the browser window will begin from\r
	33	the left-hand side of the screen\r
4ca9b6c4 LG	34	\r
4ca9b6c4 LG	35	@param RightColumn Value that designates the text\r
d1f95000	36	column where the browser window will end\r
	37	on the right-hand side of the screen.\r
	38	\r
4ca9b6c4 LG	39	@param TopRow Value that designates the text row from the\r
	40	top of the screen where the browser window\r
	41	will start.\r
d1f95000	42	\r
4ca9b6c4 LG	43	@param BottomRow Value that designates the text row from the\r
	44	bottom of the screen where the browser\r
	45	window will end. \r
d1f95000	46	**/\r
	47	typedef struct {\r
	48	UINTN LeftColumn;\r
	49	UINTN RightColumn;\r
	50	UINTN TopRow;\r
	51	UINTN BottomRow;\r
	52	} EFI_SCREEN_DESCRIPTOR;\r
	53	\r
5a1fc221	54	typedef UINTN EFI_BROWSER_ACTION_REQUEST;\r
5a1fc221	55	\r
7d582d6b	56	#define EFI_BROWSER_ACTION_REQUEST_NONE 0\r
	57	#define EFI_BROWSER_ACTION_REQUEST_RESET 1\r
	58	#define EFI_BROWSER_ACTION_REQUEST_SUBMIT 2\r
	59	#define EFI_BROWSER_ACTION_REQUEST_EXIT 3\r
5a1fc221	60	\r
5a1fc221	61	\r
d1f95000	62	/**\r
4ca9b6c4 LG	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. Type\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
d1f95000	90	\r
4ca9b6c4	91	@retval EFI_NOT_FOUND The variable was not found.\r
d1f95000	92	\r
4ca9b6c4 LG	93	@retval EFI_INVALID_PARAMETER One of the parameters has an\r
4ca9b6c4 LG	94	invalid value. \r
d1f95000	95	**/\r
	96	typedef\r
	97	EFI_STATUS\r
8b13229b	98	(EFIAPI *EFI_SEND_FORM2)(\r
7d582d6b	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
5a1fc221	104	IN CONST EFI_SCREEN_DESCRIPTOR *ScreenDimensions, OPTIONAL\r
5a1fc221	105	OUT EFI_BROWSER_ACTION_REQUEST *ActionRequest OPTIONAL\r
d1f95000	106	);\r
	107	\r
	108	\r
	109	/**\r
	110	\r
	111	This routine is called by a routine which was called by the\r
	112	browser. This routine called this service in the browser to\r
	113	retrieve or set certain uncommitted state information.\r
	114	\r
4ca9b6c4	115	@param This A pointer to the EFI_FORM_BROWSER2_PROTOCOL instance.\r
d1f95000	116	\r
d1f95000	117	@param ResultsDataSize A pointer to the size of the buffer\r
4ca9b6c4 LG	118	associated with ResultsData. On input, the size in\r
4ca9b6c4 LG	119	bytes of ResultsData. On output, the size of data returned in ResultsData.\r
d1f95000	120	\r
4ca9b6c4 LG	121	@param ResultsData A string returned from an IFR browser or\r
	122	equivalent. The results string will have\r
	123	no routing information in them.\r
d1f95000	124	\r
	125	@param RetrieveData A BOOLEAN field which allows an agent to\r
	126	retrieve (if RetrieveData = TRUE) data\r
	127	from the uncommitted browser state\r
	128	information or set (if RetrieveData =\r
	129	FALSE) data in the uncommitted browser\r
	130	state information.\r
	131	\r
	132	@param VariableGuid An optional field to indicate the target\r
	133	variable GUID name to use.\r
	134	\r
	135	@param VariableName An optional field to indicate the target\r
	136	human-readable variable name.\r
	137	\r
4ca9b6c4 LG	138	@retval EFI_SUCCESS The results have been distributed or are\r
4ca9b6c4 LG	139	awaiting distribution.\r
d1f95000	140	\r
	141	@retval EFI_OUT_OF_RESOURCES The ResultsDataSize specified\r
	142	was too small to contain the\r
	143	results data.\r
	144	\r
	145	**/\r
	146	typedef\r
	147	EFI_STATUS\r
8b13229b	148	(EFIAPI *EFI_BROWSER_CALLBACK2)(\r
7d582d6b	149	IN CONST EFI_FORM_BROWSER2_PROTOCOL *This,\r
d1f95000	150	IN OUT UINTN *ResultsDataSize,\r
	151	IN OUT EFI_STRING ResultsData,\r
	152	IN CONST BOOLEAN RetrieveData,\r
	153	IN CONST EFI_GUID *VariableGuid, OPTIONAL\r
	154	IN CONST CHAR16 *VariableName OPTIONAL\r
	155	);\r
	156	\r
	157	/**\r
4ca9b6c4 LG	158	@par Protocol Description: \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
d1f95000	161	**/\r
5a1fc221	162	struct _EFI_FORM_BROWSER2_PROTOCOL {\r
	163	EFI_SEND_FORM2 SendForm;\r
	164	EFI_BROWSER_CALLBACK2 BrowserCallback;\r
d1f95000	165	} ;\r
d1f95000	166	\r
5a1fc221	167	extern EFI_GUID gEfiFormBrowser2ProtocolGuid;\r
d1f95000	168	\r
	169	#endif\r
	170	\r