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

/** @file\r
  The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to custom\r
  NV storage devices as well as communication of user selections in a more\r
  interactive environment.  This protocol should be published by hardware\r
  specific drivers which want to export access to custom hardware storage or\r
  publish IFR which has a requirement to call back the original driver.\r
\r
  Copyright (c) 2006 - 2009, 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
  @par Revision Reference:\r
  This protocol is defined in HII spec 0.92.\r
\r
**/\r
\r
#ifndef __FORM_CALLBACK_H__\r
#define __FORM_CALLBACK_H__\r
\r
#include <FrameworkDxe.h>\r
\r
#include <Protocol/FrameworkHii.h>\r
#include <Protocol/FrameworkFormBrowser.h>\r
\r
#define EFI_FORM_CALLBACK_PROTOCOL_GUID \\r
  { \\r
    0xf3e4543d, 0xcf35, 0x6cef, {0x35, 0xc4, 0x4f, 0xe6, 0x34, 0x4d, 0xfc, 0x54 } \\r
  }\r
\r
//\r
// Forward reference for pure ANSI compatability\r
//\r
typedef struct _EFI_FORM_CALLBACK_PROTOCOL  EFI_FORM_CALLBACK_PROTOCOL;\r
\r
#pragma pack(1)\r
typedef struct {\r
  UINT8   OpCode;           ///< Likely a string, numeric, or one-of\r
  UINT8   Length;           ///< Length of the FRAMEWORK_EFI_IFR_DATA_ENTRY packet\r
  UINT16  Flags;            ///< Flags settings to determine what behavior is desired from the browser after the callback\r
  VOID    *Data;            ///< The data in the form based on the op-code type - this is not a pointer to the data, the data follows immediately\r
  ///\r
  /// If the OpCode is a OneOf or Numeric type - Data is a UINT16 value\r
  /// If the OpCode is a String type - Data is a CHAR16[x] type\r
  /// If the OpCode is a Checkbox type - Data is a UINT8 value\r
  /// If the OpCode is a NV Access type - Data is a FRAMEWORK_EFI_IFR_NV_DATA structure\r
  ///\r
} FRAMEWORK_EFI_IFR_DATA_ENTRY;\r
\r
typedef struct {\r
  VOID                *NvRamMap;  ///< If the flag of the op-code specified retrieval of a copy of the NVRAM map,\r
  //\r
  // this is a pointer to a buffer copy\r
  //\r
  UINT32              EntryCount; ///< How many FRAMEWORK_EFI_IFR_DATA_ENTRY entries\r
  //\r
  // FRAMEWORK_EFI_IFR_DATA_ENTRY  Data[1];    // The in-line Data entries.\r
  //\r
} FRAMEWORK_EFI_IFR_DATA_ARRAY;\r
\r
\r
typedef union {\r
  FRAMEWORK_EFI_IFR_DATA_ARRAY  DataArray;  ///< Primarily used by those who call back to their drivers and use HII as a repository\r
  FRAMEWORK_EFI_IFR_PACKET      DataPacket; ///< Primarily used by those which do not use HII as a repository\r
  CHAR16                        String[1];  ///< If returning an error - fill the string with null-terminated contents\r
} EFI_HII_CALLBACK_PACKET;\r
\r
typedef struct {\r
  FRAMEWORK_EFI_IFR_OP_HEADER Header;\r
  UINT16            QuestionId;   ///< Offset into the map\r
  UINT8             StorageWidth; ///< Width of the value\r
  //\r
  // CHAR8             Data[1];      // The Data itself\r
  //\r
} FRAMEWORK_EFI_IFR_NV_DATA;\r
\r
#pragma pack()\r
//\r
// The following types are currently defined:\r
//\r
/**\r
  Returns the value of a variable.\r
\r
  @param  This                  A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
  @param  VariableName          A NULL-terminated Unicode string that is the\r
                                name of the vendor's variable.\r
  @param  VendorGuid            A unique identifier for the vendor.\r
  @param  Attributes            If not NULL, a pointer to the memory location to\r
                                return the attribute's bit-mask for the variable.\r
  @param  DataSize              The size in bytes of the Buffer. A size of zero causes\r
                                the variable to be deleted.\r
  @param  Buffer                The buffer to return the contents of the variable.\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 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_NV_READ)(\r
  IN     EFI_FORM_CALLBACK_PROTOCOL    *This,\r
  IN     CHAR16                        *VariableName,\r
  IN     EFI_GUID                      *VendorGuid,\r
  OUT    UINT32                        *Attributes OPTIONAL,\r
  IN OUT UINTN                         *DataSize,\r
  OUT    VOID                          *Buffer\r
  );\r
\r
/**\r
  Sets the value of a variable.\r
\r
  @param  This                  A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
  @param  VariableName          A NULL-terminated Unicode string that is the\r
                                name of the vendor's variable. Each VariableName is unique for each VendorGuid.\r
  @param  VendorGuid            A unique identifier for the vendor.\r
  @param  Attributes            Attributes bit-mask to set for the variable.\r
  @param  DataSize              The size in bytes of the Buffer. A size of zero causes\r
                                the variable to be deleted.\r
  @param  Buffer                The buffer containing the contents of the variable.\r
  @param  ResetRequired         Returns a value from the driver that abstracts\r
                                this information and will enable a system to know if a system reset\r
                                is required to achieve the configuration changes being enabled through\r
                                this function.\r
\r
  @retval EFI_SUCCESS           The firmware has successfully stored the variable and\r
                                its data as defined by the Attributes.\r
  @retval EFI_OUT_OF_RESOURCES  Not enough storage is available to hold\r
                                the variable and its data.\r
  @retval EFI_INVALID_PARAMETER An invalid combination of Attributes bits\r
                                was supplied, or the DataSize exceeds the maximum allowed.\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_NV_WRITE)(\r
  IN     EFI_FORM_CALLBACK_PROTOCOL    *This,\r
  IN     CHAR16                        *VariableName,\r
  IN     EFI_GUID                      *VendorGuid,\r
  IN     UINT32                        Attributes,\r
  IN     UINTN                         DataSize,\r
  IN     VOID                          *Buffer,\r
  OUT    BOOLEAN                       *ResetRequired\r
  );\r
\r
/**\r
  This function is called to provide results data to the driver.\r
\r
  @param  This                  A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
  @param  KeyValue              A unique value which is sent to the original exporting\r
                                driver so that it can identify the type of data to expect. The format of\r
                                the data tends to vary based on the opcode that generated the callback.\r
  @param  Data                  A pointer to the data being sent to the original exporting driver.\r
  @param  Packet                A pointer to a packet of information which a driver passes\r
                                back to the browser.\r
\r
  @return Status Code\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FORM_CALLBACK)(\r
  IN     EFI_FORM_CALLBACK_PROTOCOL    *This,\r
  IN     UINT16                        KeyValue,\r
  IN     FRAMEWORK_EFI_IFR_DATA_ARRAY  *Data,\r
  OUT    EFI_HII_CALLBACK_PACKET       **Packet\r
  );\r
\r
/**\r
  The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to\r
  custom NVS devices as well as communication of user selections in a more\r
  interactive environment. This protocol should be published by hardware-specific\r
  drivers that want to export access to custom hardware storage or publish IFR\r
  that has a requirement to call back the original driver.\r
**/\r
struct _EFI_FORM_CALLBACK_PROTOCOL {\r
  EFI_NV_READ       NvRead;     ///< The read operation to access the NV data serviced by a hardware-specific driver.\r
  EFI_NV_WRITE      NvWrite;    ///< The write operation to access the NV data serviced by a hardware-specific driver.\r
  EFI_FORM_CALLBACK Callback;   ///< The function that is called from the configuration browser to communicate key value pairs.\r
};\r
\r
extern EFI_GUID gEfiFormCallbackProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
92627141	1	/** @file\r
	2	The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to custom\r
	3	NV storage devices as well as communication of user selections in a more\r
	4	interactive environment. This protocol should be published by hardware\r
	5	specific drivers which want to export access to custom hardware storage or\r
	6	publish IFR which has a requirement to call back the original driver.\r
	7	\r
2bbaeb0d	8	Copyright (c) 2006 - 2009, Intel Corporation\r
92627141	9	All rights reserved. This program and the accompanying materials\r
	10	are licensed and made available under the terms and conditions of the BSD License\r
	11	which accompanies this distribution. The full text of the license may be found at\r
	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
	16	\r
92627141	17	@par Revision Reference:\r
	18	This protocol is defined in HII spec 0.92.\r
	19	\r
	20	**/\r
	21	\r
	22	#ifndef __FORM_CALLBACK_H__\r
	23	#define __FORM_CALLBACK_H__\r
	24	\r
dc7b4a5c	25	#include <FrameworkDxe.h>\r
92627141	26	\r
8e5b17b2	27	#include <Protocol/FrameworkHii.h>\r
8e5b17b2	28	#include <Protocol/FrameworkFormBrowser.h>\r
92627141	29	\r
	30	#define EFI_FORM_CALLBACK_PROTOCOL_GUID \\r
	31	{ \\r
	32	0xf3e4543d, 0xcf35, 0x6cef, {0x35, 0xc4, 0x4f, 0xe6, 0x34, 0x4d, 0xfc, 0x54 } \\r
	33	}\r
	34	\r
	35	//\r
	36	// Forward reference for pure ANSI compatability\r
	37	//\r
	38	typedef struct _EFI_FORM_CALLBACK_PROTOCOL EFI_FORM_CALLBACK_PROTOCOL;\r
	39	\r
92627141	40	#pragma pack(1)\r
92627141	41	typedef struct {\r
aa4a31e3 LG	42	UINT8 OpCode; ///< Likely a string, numeric, or one-of\r
	43	UINT8 Length; ///< Length of the FRAMEWORK_EFI_IFR_DATA_ENTRY packet\r
	44	UINT16 Flags; ///< Flags settings to determine what behavior is desired from the browser after the callback\r
	45	VOID *Data; ///< The data in the form based on the op-code type - this is not a pointer to the data, the data follows immediately\r
	46	///\r
	47	/// If the OpCode is a OneOf or Numeric type - Data is a UINT16 value\r
	48	/// If the OpCode is a String type - Data is a CHAR16[x] type\r
	49	/// If the OpCode is a Checkbox type - Data is a UINT8 value\r
	50	/// If the OpCode is a NV Access type - Data is a FRAMEWORK_EFI_IFR_NV_DATA structure\r
	51	///\r
dc7b4a5c	52	} FRAMEWORK_EFI_IFR_DATA_ENTRY;\r
92627141	53	\r
92627141	54	typedef struct {\r
aa4a31e3 LG	55	VOID *NvRamMap; ///< If the flag of the op-code specified retrieval of a copy of the NVRAM map,\r
aa4a31e3 LG	56	//\r
92627141	57	// this is a pointer to a buffer copy\r
92627141	58	//\r
aa4a31e3	59	UINT32 EntryCount; ///< How many FRAMEWORK_EFI_IFR_DATA_ENTRY entries\r
92627141	60	//\r
dc7b4a5c	61	// FRAMEWORK_EFI_IFR_DATA_ENTRY Data[1]; // The in-line Data entries.\r
92627141	62	//\r
dc7b4a5c	63	} FRAMEWORK_EFI_IFR_DATA_ARRAY;\r
92627141	64	\r
	65	\r
	66	typedef union {\r
aa4a31e3 LG	67	FRAMEWORK_EFI_IFR_DATA_ARRAY DataArray; ///< Primarily used by those who call back to their drivers and use HII as a repository\r
	68	FRAMEWORK_EFI_IFR_PACKET DataPacket; ///< Primarily used by those which do not use HII as a repository\r
	69	CHAR16 String[1]; ///< If returning an error - fill the string with null-terminated contents\r
2cec3ea5	70	} EFI_HII_CALLBACK_PACKET;\r
92627141	71	\r
92627141	72	typedef struct {\r
dc7b4a5c	73	FRAMEWORK_EFI_IFR_OP_HEADER Header;\r
aa4a31e3 LG	74	UINT16 QuestionId; ///< Offset into the map\r
aa4a31e3 LG	75	UINT8 StorageWidth; ///< Width of the value\r
92627141	76	//\r
	77	// CHAR8 Data[1]; // The Data itself\r
	78	//\r
dc7b4a5c	79	} FRAMEWORK_EFI_IFR_NV_DATA;\r
92627141	80	\r
	81	#pragma pack()\r
	82	//\r
	83	// The following types are currently defined:\r
	84	//\r
	85	/**\r
	86	Returns the value of a variable.\r
	87	\r
	88	@param This A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
	89	@param VariableName A NULL-terminated Unicode string that is the\r
	90	name of the vendor's variable.\r
	91	@param VendorGuid A unique identifier for the vendor.\r
	92	@param Attributes If not NULL, a pointer to the memory location to\r
	93	return the attribute's bit-mask for the variable.\r
	94	@param DataSize The size in bytes of the Buffer. A size of zero causes\r
	95	the variable to be deleted.\r
	96	@param Buffer The buffer to return the contents of the variable.\r
	97	\r
	98	@retval EFI_SUCCESS The function completed successfully.\r
	99	@retval EFI_NOT_FOUND The variable was not found.\r
	100	@retval EFI_BUFFER_TOO_SMALL The DataSize is too small for the result.\r
	101	DataSize has been updated with the size needed to complete the request.\r
	102	@retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.\r
	103	@retval EFI_DEVICE_ERROR The variable could not be saved due to a hardware failure.\r
	104	\r
	105	**/\r
	106	typedef\r
	107	EFI_STATUS\r
69686d56	108	(EFIAPI *EFI_NV_READ)(\r
92627141	109	IN EFI_FORM_CALLBACK_PROTOCOL *This,\r
	110	IN CHAR16 *VariableName,\r
	111	IN EFI_GUID *VendorGuid,\r
	112	OUT UINT32 *Attributes OPTIONAL,\r
	113	IN OUT UINTN *DataSize,\r
	114	OUT VOID *Buffer\r
	115	);\r
	116	\r
	117	/**\r
	118	Sets the value of a variable.\r
	119	\r
	120	@param This A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
	121	@param VariableName A NULL-terminated Unicode string that is the\r
	122	name of the vendor's variable. Each VariableName is unique for each VendorGuid.\r
	123	@param VendorGuid A unique identifier for the vendor.\r
	124	@param Attributes Attributes bit-mask to set for the variable.\r
	125	@param DataSize The size in bytes of the Buffer. A size of zero causes\r
	126	the variable to be deleted.\r
	127	@param Buffer The buffer containing the contents of the variable.\r
	128	@param ResetRequired Returns a value from the driver that abstracts\r
	129	this information and will enable a system to know if a system reset\r
	130	is required to achieve the configuration changes being enabled through\r
	131	this function.\r
	132	\r
	133	@retval EFI_SUCCESS The firmware has successfully stored the variable and\r
	134	its data as defined by the Attributes.\r
	135	@retval EFI_OUT_OF_RESOURCES Not enough storage is available to hold\r
	136	the variable and its data.\r
	137	@retval EFI_INVALID_PARAMETER An invalid combination of Attributes bits\r
	138	was supplied, or the DataSize exceeds the maximum allowed.\r
	139	@retval EFI_DEVICE_ERROR The variable could not be saved due to a hardware failure.\r
	140	\r
	141	**/\r
	142	typedef\r
	143	EFI_STATUS\r
69686d56	144	(EFIAPI *EFI_NV_WRITE)(\r
92627141	145	IN EFI_FORM_CALLBACK_PROTOCOL *This,\r
	146	IN CHAR16 *VariableName,\r
	147	IN EFI_GUID *VendorGuid,\r
	148	IN UINT32 Attributes,\r
	149	IN UINTN DataSize,\r
	150	IN VOID *Buffer,\r
	151	OUT BOOLEAN *ResetRequired\r
	152	);\r
	153	\r
	154	/**\r
	155	This function is called to provide results data to the driver.\r
	156	\r
	157	@param This A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
	158	@param KeyValue A unique value which is sent to the original exporting\r
	159	driver so that it can identify the type of data to expect. The format of\r
	160	the data tends to vary based on the opcode that generated the callback.\r
	161	@param Data A pointer to the data being sent to the original exporting driver.\r
	162	@param Packet A pointer to a packet of information which a driver passes\r
	163	back to the browser.\r
	164	\r
	165	@return Status Code\r
	166	\r
	167	**/\r
	168	typedef\r
	169	EFI_STATUS\r
69686d56	170	(EFIAPI *EFI_FORM_CALLBACK)(\r
92627141	171	IN EFI_FORM_CALLBACK_PROTOCOL *This,\r
92627141	172	IN UINT16 KeyValue,\r
534b8251	173	IN FRAMEWORK_EFI_IFR_DATA_ARRAY *Data,\r
2cec3ea5	174	OUT EFI_HII_CALLBACK_PACKET **Packet\r
92627141	175	);\r
	176	\r
	177	/**\r
92627141	178	The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to\r
	179	custom NVS devices as well as communication of user selections in a more\r
	180	interactive environment. This protocol should be published by hardware-specific\r
	181	drivers that want to export access to custom hardware storage or publish IFR\r
	182	that has a requirement to call back the original driver.\r
92627141	183	**/\r
92627141	184	struct _EFI_FORM_CALLBACK_PROTOCOL {\r
2bbaeb0d	185	EFI_NV_READ NvRead; ///< The read operation to access the NV data serviced by a hardware-specific driver.\r
	186	EFI_NV_WRITE NvWrite; ///< The write operation to access the NV data serviced by a hardware-specific driver.\r
	187	EFI_FORM_CALLBACK Callback; ///< The function that is called from the configuration browser to communicate key value pairs.\r
92627141	188	};\r
	189	\r
	190	extern EFI_GUID gEfiFormCallbackProtocolGuid;\r
	191	\r
	192	#endif\r