[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / FrameworkFormBrowser.h

/** @file\r
  The EFI_FORM_BROWSER_PROTOCOL is the interface to the EFI\r
  Configuration Driver.  This interface enables the caller to direct the\r
  configuration driver to use either the HII database or the passed-in\r
  packet of data.  This will also allow the caller to post messages\r
  into the configuration drivers internal mailbox.\r
\r
Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
  Module Name:  FrameworkFormBrowser.h\r
\r
  @par Revision Reference:\r
  This protocol is defined in HII spec 0.92.\r
\r
**/\r
\r
#ifndef __FRAMEWORK_FORM_BROWSER_H__\r
#define __FRAMEWORK_FORM_BROWSER_H__\r
\r
#include <Protocol/FrameworkHii.h>\r
\r
\r
#define EFI_FORM_BROWSER_PROTOCOL_GUID \\r
  { \\r
    0xe5a1333e, 0xe1b4, 0x4d55, {0xce, 0xeb, 0x35, 0xc3, 0xef, 0x13, 0x34, 0x43 } \\r
  }\r
\r
#define EFI_FORM_BROWSER_COMPATIBILITY_PROTOCOL_GUID \\r
  { \\r
    0xfb7c852, 0xadca, 0x4853, { 0x8d, 0xf, 0xfb, 0xa7, 0x1b, 0x1c, 0xe1, 0x1a } \\r
  }\r
\r
typedef struct _EFI_FORM_BROWSER_PROTOCOL EFI_FORM_BROWSER_PROTOCOL;\r
\r
typedef struct {\r
  UINT32  Length;\r
  UINT16  Type;\r
  UINT8   Data[1];\r
} EFI_HII_PACKET;\r
\r
typedef struct {\r
  EFI_HII_IFR_PACK    *IfrData;\r
  EFI_HII_STRING_PACK *StringData;\r
} EFI_IFR_PACKET;\r
\r
typedef struct {\r
  UINTN LeftColumn;\r
  UINTN RightColumn;\r
  UINTN TopRow;\r
  UINTN BottomRow;\r
} FRAMEWORK_EFI_SCREEN_DESCRIPTOR;\r
\r
/**\r
  Provides direction to the configuration driver whether to use the HII\r
  database or a passed-in set of data. This function also establishes a\r
  pointer to the calling driver's callback interface.\r
\r
  @param  This                  A pointer to the EFI_FORM_BROWSER_PROTOCOL instance.\r
  @param  UseDatabase           Determines whether the HII database is to be\r
                                used to gather information. If the value is FALSE,\r
                                the configuration driver will get the information\r
                                provided in the passed-in Packet parameters.\r
  @param  Handle                A pointer to an array of HII handles to display.\r
                                This value should correspond to the value of the\r
                                HII form package that is required to be displayed.\r
  @param  HandleCount           The number of handles in the array specified by Handle.\r
  @param  Packet                A pointer to a set of data containing pointers to IFR\r
                                and/or string data.\r
  @param  CallbackHandle        The handle to the driver's callback interface.\r
                                This parameter is used only when the UseDatabase\r
                                parameter is FALSE and an application wants to\r
                                register a callback with the browser.\r
  @param  NvMapOverride         This buffer is used only when there is no NV variable\r
                                to define the current settings and the caller needs\r
                                to provide to the browser the current settings for\r
                                the "fake" NV variable.\r
  @param  ScreenDimensions      Allows the browser to be called so that it occupies\r
                                a portion of the physical screen instead of dynamically\r
                                determining the screen dimensions.\r
  @param  ResetRequired         This BOOLEAN value denotes whether a reset is required\r
                                based on the data that might have been changed.\r
                                The ResetRequired parameter is primarily applicable\r
                                for configuration applications, and is an\r
                                optional parameter.\r
\r
  @retval EFI_SUCCESS           The function completed successfully.\r
  @retval EFI_NOT_FOUND         The variable was not found.\r
  @retval EFI_BUFFER_TOO_SMALL  The DataSize is too small for the result.\r
                                DataSize has been updated with the size needed to\r
                                complete the request.\r
  @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.\r
  @retval EFI_DEVICE_ERROR      The variable could not be saved due to a hardware failure.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_SEND_FORM)(\r
  IN  EFI_FORM_BROWSER_PROTOCOL       *This,\r
  IN  BOOLEAN                         UseDatabase,\r
  IN  FRAMEWORK_EFI_HII_HANDLE        *Handle,\r
  IN  UINTN                           HandleCount,\r
  IN  EFI_IFR_PACKET                  *Packet, OPTIONAL\r
  IN  EFI_HANDLE                      CallbackHandle, OPTIONAL\r
  IN  UINT8                           *NvMapOverride, OPTIONAL\r
  IN  FRAMEWORK_EFI_SCREEN_DESCRIPTOR *ScreenDimensions, OPTIONAL\r
  OUT BOOLEAN                         *ResetRequired OPTIONAL\r
  );\r
\r
/**\r
  Routine used to abstract a generic dialog interface and return the selected\r
  key or string.\r
\r
  @param  NumberOfLines         The number of lines for the dialog box.\r
  @param  HotKey                Defines whether a single character is parsed (TRUE)\r
                                and returned in KeyValue, or if a string is returned\r
                                in StringBuffer.\r
  @param  MaximumStringSize     The maximum size in bytes of a typed-in string.\r
                                Because each character is a CHAR16, the minimum\r
                                string returned is two bytes.\r
  @param  StringBuffer          The passed-in pointer to the buffer that will hold\r
                                the typed in string if HotKey is FALSE.\r
  @param  KeyValue              The EFI_INPUT_KEY value returned if HotKey is TRUE.\r
  @param  String                The pointer to the first string in the list of strings\r
                                that comprise the dialog box.\r
  @param  ...                   A series of NumberOfLines text strings that will be used\r
                                to construct the dialog box.\r
\r
  @retval EFI_SUCCESS           The dialog was displayed and user interaction was received.\r
  @retval EFI_DEVICE_ERROR      The user typed in an ESC character to exit the routine.\r
  @retval EFI_INVALID_PARAMETER One of the parameters was invalid\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_CREATE_POP_UP)(\r
  IN  UINTN                           NumberOfLines,\r
  IN  BOOLEAN                         HotKey,\r
  IN  UINTN                           MaximumStringSize,\r
  OUT CHAR16                          *StringBuffer,\r
  OUT EFI_INPUT_KEY                   *KeyValue,\r
  IN  CHAR16                          *String,\r
  ...\r
  );\r
\r
/**\r
  The EFI_FORM_BROWSER_PROTOCOL is the interface to call for drivers to\r
  leverage the EFI configuration driver interface.\r
**/\r
struct _EFI_FORM_BROWSER_PROTOCOL {\r
  ///\r
  /// Provides direction to the configuration driver whether to use the HII\r
  /// database or to use a passed-in set of data. This function also establishes\r
  /// a pointer to the calling driver's callback interface.\r
  ///\r
  EFI_SEND_FORM     SendForm;\r
\r
  ///\r
  /// Routine used to abstract a generic dialog interface and return the\r
  /// selected key or string.\r
  ///\r
  EFI_CREATE_POP_UP CreatePopUp;\r
};\r
\r
extern EFI_GUID gEfiFormBrowserProtocolGuid;\r
extern EFI_GUID gEfiFormBrowserCompatibilityProtocolGuid;\r
\r
\r
#endif\r
Commit	Line	Data
	1	/** @file\r
	2	The EFI_FORM_BROWSER_PROTOCOL is the interface to the EFI\r
	3	Configuration Driver. This interface enables the caller to direct the\r
	4	configuration driver to use either the HII database or the passed-in\r
	5	packet of data. This will also allow the caller to post messages\r
	6	into the configuration drivers internal mailbox.\r
	7	\r
	8	Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
	9	SPDX-License-Identifier: BSD-2-Clause-Patent\r
	10	\r
	11	Module Name: FrameworkFormBrowser.h\r
	12	\r
	13	@par Revision Reference:\r
	14	This protocol is defined in HII spec 0.92.\r
	15	\r
	16	**/\r
	17	\r
	18	#ifndef __FRAMEWORK_FORM_BROWSER_H__\r
	19	#define __FRAMEWORK_FORM_BROWSER_H__\r
	20	\r
	21	#include <Protocol/FrameworkHii.h>\r
	22	\r
	23	\r
	24	#define EFI_FORM_BROWSER_PROTOCOL_GUID \\r
	25	{ \\r
	26	0xe5a1333e, 0xe1b4, 0x4d55, {0xce, 0xeb, 0x35, 0xc3, 0xef, 0x13, 0x34, 0x43 } \\r
	27	}\r
	28	\r
	29	#define EFI_FORM_BROWSER_COMPATIBILITY_PROTOCOL_GUID \\r
	30	{ \\r
	31	0xfb7c852, 0xadca, 0x4853, { 0x8d, 0xf, 0xfb, 0xa7, 0x1b, 0x1c, 0xe1, 0x1a } \\r
	32	}\r
	33	\r
	34	typedef struct _EFI_FORM_BROWSER_PROTOCOL EFI_FORM_BROWSER_PROTOCOL;\r
	35	\r
	36	typedef struct {\r
	37	UINT32 Length;\r
	38	UINT16 Type;\r
	39	UINT8 Data[1];\r
	40	} EFI_HII_PACKET;\r
	41	\r
	42	typedef struct {\r
	43	EFI_HII_IFR_PACK *IfrData;\r
	44	EFI_HII_STRING_PACK *StringData;\r
	45	} EFI_IFR_PACKET;\r
	46	\r
	47	typedef struct {\r
	48	UINTN LeftColumn;\r
	49	UINTN RightColumn;\r
	50	UINTN TopRow;\r
	51	UINTN BottomRow;\r
	52	} FRAMEWORK_EFI_SCREEN_DESCRIPTOR;\r
	53	\r
	54	/**\r
	55	Provides direction to the configuration driver whether to use the HII\r
	56	database or a passed-in set of data. This function also establishes a\r
	57	pointer to the calling driver's callback interface.\r
	58	\r
	59	@param This A pointer to the EFI_FORM_BROWSER_PROTOCOL instance.\r
	60	@param UseDatabase Determines whether the HII database is to be\r
	61	used to gather information. If the value is FALSE,\r
	62	the configuration driver will get the information\r
	63	provided in the passed-in Packet parameters.\r
	64	@param Handle A pointer to an array of HII handles to display.\r
	65	This value should correspond to the value of the\r
	66	HII form package that is required to be displayed.\r
	67	@param HandleCount The number of handles in the array specified by Handle.\r
	68	@param Packet A pointer to a set of data containing pointers to IFR\r
	69	and/or string data.\r
	70	@param CallbackHandle The handle to the driver's callback interface.\r
	71	This parameter is used only when the UseDatabase\r
	72	parameter is FALSE and an application wants to\r
	73	register a callback with the browser.\r
	74	@param NvMapOverride This buffer is used only when there is no NV variable\r
	75	to define the current settings and the caller needs\r
	76	to provide to the browser the current settings for\r
	77	the "fake" NV variable.\r
	78	@param ScreenDimensions Allows the browser to be called so that it occupies\r
	79	a portion of the physical screen instead of dynamically\r
	80	determining the screen dimensions.\r
	81	@param ResetRequired This BOOLEAN value denotes whether a reset is required\r
	82	based on the data that might have been changed.\r
	83	The ResetRequired parameter is primarily applicable\r
	84	for configuration applications, and is an\r
	85	optional parameter.\r
	86	\r
	87	@retval EFI_SUCCESS The function completed successfully.\r
	88	@retval EFI_NOT_FOUND The variable was not found.\r
	89	@retval EFI_BUFFER_TOO_SMALL The DataSize is too small for the result.\r
	90	DataSize has been updated with the size needed to\r
	91	complete the request.\r
	92	@retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.\r
	93	@retval EFI_DEVICE_ERROR The variable could not be saved due to a hardware failure.\r
	94	\r
	95	**/\r
	96	typedef\r
	97	EFI_STATUS\r
	98	(EFIAPI *EFI_SEND_FORM)(\r
	99	IN EFI_FORM_BROWSER_PROTOCOL *This,\r
	100	IN BOOLEAN UseDatabase,\r
	101	IN FRAMEWORK_EFI_HII_HANDLE *Handle,\r
	102	IN UINTN HandleCount,\r
	103	IN EFI_IFR_PACKET *Packet, OPTIONAL\r
	104	IN EFI_HANDLE CallbackHandle, OPTIONAL\r
	105	IN UINT8 *NvMapOverride, OPTIONAL\r
	106	IN FRAMEWORK_EFI_SCREEN_DESCRIPTOR *ScreenDimensions, OPTIONAL\r
	107	OUT BOOLEAN *ResetRequired OPTIONAL\r
	108	);\r
	109	\r
	110	/**\r
	111	Routine used to abstract a generic dialog interface and return the selected\r
	112	key or string.\r
	113	\r
	114	@param NumberOfLines The number of lines for the dialog box.\r
	115	@param HotKey Defines whether a single character is parsed (TRUE)\r
	116	and returned in KeyValue, or if a string is returned\r
	117	in StringBuffer.\r
	118	@param MaximumStringSize The maximum size in bytes of a typed-in string.\r
	119	Because each character is a CHAR16, the minimum\r
	120	string returned is two bytes.\r
	121	@param StringBuffer The passed-in pointer to the buffer that will hold\r
	122	the typed in string if HotKey is FALSE.\r
	123	@param KeyValue The EFI_INPUT_KEY value returned if HotKey is TRUE.\r
	124	@param String The pointer to the first string in the list of strings\r
	125	that comprise the dialog box.\r
	126	@param ... A series of NumberOfLines text strings that will be used\r
	127	to construct the dialog box.\r
	128	\r
	129	@retval EFI_SUCCESS The dialog was displayed and user interaction was received.\r
	130	@retval EFI_DEVICE_ERROR The user typed in an ESC character to exit the routine.\r
	131	@retval EFI_INVALID_PARAMETER One of the parameters was invalid\r
	132	\r
	133	**/\r
	134	typedef\r
	135	EFI_STATUS\r
	136	(EFIAPI *EFI_CREATE_POP_UP)(\r
	137	IN UINTN NumberOfLines,\r
	138	IN BOOLEAN HotKey,\r
	139	IN UINTN MaximumStringSize,\r
	140	OUT CHAR16 *StringBuffer,\r
	141	OUT EFI_INPUT_KEY *KeyValue,\r
	142	IN CHAR16 *String,\r
	143	...\r
	144	);\r
	145	\r
	146	/**\r
	147	The EFI_FORM_BROWSER_PROTOCOL is the interface to call for drivers to\r
	148	leverage the EFI configuration driver interface.\r
	149	**/\r
	150	struct _EFI_FORM_BROWSER_PROTOCOL {\r
	151	///\r
	152	/// Provides direction to the configuration driver whether to use the HII\r
	153	/// database or to use a passed-in set of data. This function also establishes\r
	154	/// a pointer to the calling driver's callback interface.\r
	155	///\r
	156	EFI_SEND_FORM SendForm;\r
	157	\r
	158	///\r
	159	/// Routine used to abstract a generic dialog interface and return the\r
	160	/// selected key or string.\r
	161	///\r
	162	EFI_CREATE_POP_UP CreatePopUp;\r
	163	};\r
	164	\r
	165	extern EFI_GUID gEfiFormBrowserProtocolGuid;\r
	166	extern EFI_GUID gEfiFormBrowserCompatibilityProtocolGuid;\r
	167	\r
	168	\r
	169	#endif\r