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

/** @file\r
\r
  The file provides services to call for drivers to leverage the\r
  EFI configuration driver interface.\r
  \r
  Copyright (c) 2006 - 2007, Intel Corporation\r
  All rights reserved. This program and the accompanying materials                          \r
  are licensed and made available under the terms and conditions of the BSD License         \r
  which accompanies this distribution.  The full text of the license may be found at        \r
  http://opensource.org/licenses/bsd-license.php                                            \r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,                     \r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.             \r
\r
**/\r
\r
#ifndef __EFI_FORM_BROWSER_H__\r
#define __EFI_FORM_BROWSER_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
                      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
   \r
  This function is the primary interface to the internal\r
  forms-based browser. By calling this routine, one is directing\r
  the browser to use a variety of passed-in information or\r
  primarily use the HII database as the source of information.\r
\r
  @param This   A pointer to the EFI_FORM_BROWSER2_PROTOCOL\r
                instance.\r
\r
  @param Handle   A pointer to an array of HII handles to\r
                  display. This value should correspond to the\r
                  value of the HII form package that is required\r
                  to be displayed.\r
\r
  @param HandleCount  The number of handles in the array\r
                      specified by Handle.\r
\r
  @param SingleUse  If FALSE, the browser operates as a standard\r
                    forms processor and exits only when\r
                    explicitly requested by the user. If TRUE,\r
                    the browser will return immediately after\r
                    processing the first user-generated\r
                    selection.\r
\r
  @param ScreenDimensions   Allows the browser to be called so\r
                            that it occupies a portion of the\r
                            physical screen instead of\r
                            dynamically determining the screen\r
                            dimensions. If the input values\r
                            violate the platform policy then the\r
                            dimensions will be dynamically\r
                            adjusted to comply.\r
\r
  @param ResetRequired  This BOOLEAN value will tell the caller\r
                        if a reset is required based on the data\r
                        that might have been changed. The\r
                        ResetRequired parameter is primarily\r
                        applicable for configuration\r
                        applications, and is an optional\r
                        parameter.\r
\r
  @retval EFI_SUCCESS   The function completed successfully\r
  \r
  @retval EFI_NOT_FOUND   The variable was not found.\r
  \r
  @retval EFI_BUFFER_TOO_SMALL  The DataSize is too small for\r
                                the result. DataSize has been\r
                                updated with the size needed to\r
                                complete the request.\r
  \r
  @retval EFI_INVALID_PARAMETER   One of the parameters has an\r
                                  invalid value.\r
  \r
  @retval EFI_DEVICE_ERROR  The variable could not be saved due\r
                            to a hardware failure.\r
  \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\r
                instance.\r
\r
  @param ResultsDataSize  A pointer to the size of the buffer\r
                          associated with 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
\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
   \r
  This protocol is the interface to call for drivers to leverage\r
  the EFI configuration driver interface.\r
\r
  @param SendForm   Provides direction to the configuration\r
                    driver whether to use the HII database or to\r
                    use a passed-in set of data. This functions\r
                    also establishes a pointer to the calling\r
                    driver's callback interface. See the\r
                    SendForm() function description.\r
\r
  @param BrowserCallback  Routine used to expose internal\r
                          configuration state of the browser.\r
                          This is primarily used by callback\r
                          handler routines which were called by\r
                          the browser and in-turn need to get\r
                          additional information from the\r
                          browser itself. See the\r
                          BrowserCallback() function\r
                          description.\r
\r
**/\r
struct _EFI_FORM_BROWSER2_PROTOCOL {\r
  EFI_SEND_FORM2         SendForm;\r
  EFI_BROWSER_CALLBACK2  BrowserCallback;\r
} ;\r
\r
\r
extern EFI_GUID gEfiFormBrowser2ProtocolGuid;\r
\r
#endif\r
\r
Commit	Line	Data
d1f95000	1	/** @file\r
	2	\r
	3	The file provides services to call for drivers to leverage the\r
	4	EFI configuration driver interface.\r
	5	\r
	6	Copyright (c) 2006 - 2007, Intel Corporation\r
	7	All rights reserved. This program and the accompanying materials \r
	8	are licensed and made available under the terms and conditions of the BSD License \r
	9	which accompanies this distribution. The full text of the license may be found at \r
	10	http://opensource.org/licenses/bsd-license.php \r
	11	\r
	12	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	13	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	14	\r
d1f95000	15	**/\r
	16	\r
	17	#ifndef __EFI_FORM_BROWSER_H__\r
	18	#define __EFI_FORM_BROWSER_H__\r
	19	\r
5a1fc221	20	#define EFI_FORM_BROWSER2_PROTOCOL_GUID \\r
7d582d6b	21	{0xb9d4c360, 0xbcfb, 0x4f9b, {0x92, 0x98, 0x53, 0xc1, 0x36, 0x98, 0x22, 0x58 }}\r
d1f95000	22	\r
d1f95000	23	\r
5a1fc221	24	typedef struct _EFI_FORM_BROWSER2_PROTOCOL EFI_FORM_BROWSER2_PROTOCOL;\r
d1f95000	25	\r
	26	\r
	27	\r
	28	/**\r
	29	\r
	30	@param LeftColumn Value that designates the text column\r
	31	where the browser window will begin from\r
	32	the left-hand side of the screen\r
	33	RightColumn Value that designates the text\r
	34	column where the browser window will end\r
	35	on the right-hand side of the screen.\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
5a1fc221	52	typedef UINTN EFI_BROWSER_ACTION_REQUEST;\r
5a1fc221	53	\r
7d582d6b	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
5a1fc221	58	\r
5a1fc221	59	\r
d1f95000	60	/**\r
	61	\r
	62	This function is the primary interface to the internal\r
	63	forms-based browser. By calling this routine, one is directing\r
	64	the browser to use a variety of passed-in information or\r
	65	primarily use the HII database as the source of information.\r
	66	\r
7d582d6b	67	@param This A pointer to the EFI_FORM_BROWSER2_PROTOCOL\r
d1f95000	68	instance.\r
	69	\r
	70	@param Handle A pointer to an array of HII handles to\r
	71	display. This value should correspond to the\r
	72	value of the HII form package that is required\r
	73	to be displayed.\r
	74	\r
	75	@param HandleCount The number of handles in the array\r
	76	specified by Handle.\r
	77	\r
	78	@param SingleUse If FALSE, the browser operates as a standard\r
	79	forms processor and exits only when\r
	80	explicitly requested by the user. If TRUE,\r
	81	the browser will return immediately after\r
	82	processing the first user-generated\r
	83	selection.\r
	84	\r
	85	@param ScreenDimensions Allows the browser to be called so\r
	86	that it occupies a portion of the\r
	87	physical screen instead of\r
	88	dynamically determining the screen\r
	89	dimensions. If the input values\r
	90	violate the platform policy then the\r
	91	dimensions will be dynamically\r
	92	adjusted to comply.\r
	93	\r
	94	@param ResetRequired This BOOLEAN value will tell the caller\r
	95	if a reset is required based on the data\r
	96	that might have been changed. The\r
	97	ResetRequired parameter is primarily\r
	98	applicable for configuration\r
	99	applications, and is an optional\r
	100	parameter.\r
	101	\r
	102	@retval EFI_SUCCESS The function completed successfully\r
	103	\r
	104	@retval EFI_NOT_FOUND The variable was not found.\r
	105	\r
	106	@retval EFI_BUFFER_TOO_SMALL The DataSize is too small for\r
	107	the result. DataSize has been\r
	108	updated with the size needed to\r
	109	complete the request.\r
	110	\r
	111	@retval EFI_INVALID_PARAMETER One of the parameters has an\r
	112	invalid value.\r
	113	\r
	114	@retval EFI_DEVICE_ERROR The variable could not be saved due\r
	115	to a hardware failure.\r
	116	\r
	117	**/\r
	118	typedef\r
	119	EFI_STATUS\r
5a1fc221	120	(EFIAPI *EFI_SEND_FORM2) (\r
7d582d6b	121	IN CONST EFI_FORM_BROWSER2_PROTOCOL *This,\r
	122	IN EFI_HII_HANDLE *Handle,\r
	123	IN UINTN HandleCount,\r
	124	IN EFI_GUID *FormSetGuid, OPTIONAL\r
	125	IN EFI_FORM_ID FormId, OPTIONAL\r
5a1fc221	126	IN CONST EFI_SCREEN_DESCRIPTOR *ScreenDimensions, OPTIONAL\r
5a1fc221	127	OUT EFI_BROWSER_ACTION_REQUEST *ActionRequest OPTIONAL\r
d1f95000	128	);\r
	129	\r
	130	\r
	131	/**\r
	132	\r
	133	This routine is called by a routine which was called by the\r
	134	browser. This routine called this service in the browser to\r
	135	retrieve or set certain uncommitted state information.\r
	136	\r
7d582d6b	137	@param This A pointer to the EFI_FORM_BROWSER2_PROTOCOL\r
d1f95000	138	instance.\r
	139	\r
	140	@param ResultsDataSize A pointer to the size of the buffer\r
	141	associated with ResultsData. \r
	142	\r
	143	@param ResultsData A string returned from an IFR browser or\r
	144	equivalent. The results string will have\r
	145	no routing information in them.\r
	146	\r
	147	@param RetrieveData A BOOLEAN field which allows an agent to\r
	148	retrieve (if RetrieveData = TRUE) data\r
	149	from the uncommitted browser state\r
	150	information or set (if RetrieveData =\r
	151	FALSE) data in the uncommitted browser\r
	152	state information.\r
	153	\r
	154	@param VariableGuid An optional field to indicate the target\r
	155	variable GUID name to use.\r
	156	\r
	157	@param VariableName An optional field to indicate the target\r
	158	human-readable variable name.\r
	159	\r
	160	\r
	161	@retval EFI_SUCCESS The results have been distributed or are\r
	162	awaiting distribution.\r
	163	\r
	164	@retval EFI_OUT_OF_RESOURCES The ResultsDataSize specified\r
	165	was too small to contain the\r
	166	results data.\r
	167	\r
	168	**/\r
	169	typedef\r
	170	EFI_STATUS\r
5a1fc221	171	(EFIAPI *EFI_BROWSER_CALLBACK2 ) (\r
7d582d6b	172	IN CONST EFI_FORM_BROWSER2_PROTOCOL *This,\r
d1f95000	173	IN OUT UINTN *ResultsDataSize,\r
	174	IN OUT EFI_STRING ResultsData,\r
	175	IN CONST BOOLEAN RetrieveData,\r
	176	IN CONST EFI_GUID *VariableGuid, OPTIONAL\r
	177	IN CONST CHAR16 *VariableName OPTIONAL\r
	178	);\r
	179	\r
	180	/**\r
	181	\r
	182	This protocol is the interface to call for drivers to leverage\r
	183	the EFI configuration driver interface.\r
	184	\r
	185	@param SendForm Provides direction to the configuration\r
	186	driver whether to use the HII database or to\r
	187	use a passed-in set of data. This functions\r
	188	also establishes a pointer to the calling\r
	189	driver's callback interface. See the\r
	190	SendForm() function description.\r
	191	\r
	192	@param BrowserCallback Routine used to expose internal\r
	193	configuration state of the browser.\r
	194	This is primarily used by callback\r
	195	handler routines which were called by\r
	196	the browser and in-turn need to get\r
	197	additional information from the\r
	198	browser itself. See the\r
	199	BrowserCallback() function\r
	200	description.\r
	201	\r
	202	**/\r
5a1fc221	203	struct _EFI_FORM_BROWSER2_PROTOCOL {\r
	204	EFI_SEND_FORM2 SendForm;\r
	205	EFI_BROWSER_CALLBACK2 BrowserCallback;\r
d1f95000	206	} ;\r
	207	\r
	208	\r
5a1fc221	209	extern EFI_GUID gEfiFormBrowser2ProtocolGuid;\r
d1f95000	210	\r
	211	#endif\r
	212	\r