Rename Protocol/FormCallback.h to Protocol/FormCallbackFramework.h to follow the...
authorqwang12 <qwang12@6f19259b-4bc3-4df7-8a09-765794883524>
Mon, 2 Jul 2007 09:07:42 +0000 (09:07 +0000)
committerqwang12 <qwang12@6f19259b-4bc3-4df7-8a09-765794883524>
Mon, 2 Jul 2007 09:07:42 +0000 (09:07 +0000)
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@2947 6f19259b-4bc3-4df7-8a09-765794883524

IntelFrameworkPkg/Include/Protocol/FormCallbackFramework.h [new file with mode: 0644]

diff --git a/IntelFrameworkPkg/Include/Protocol/FormCallbackFramework.h b/IntelFrameworkPkg/Include/Protocol/FormCallbackFramework.h
new file mode 100644 (file)
index 0000000..3949b1e
--- /dev/null
@@ -0,0 +1,211 @@
+/** @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, 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
+  Module Name:  FormCallbackFramework.h\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 <PiDxe.h>\r
+\r
+#include <Protocol/HiiFramework.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
+\r
+#define RESET_REQUIRED  1 // Flags setting to signify that the callback operation resulted in an eventual\r
+// reset to be done upon exit of the browser\r
+//\r
+#define EXIT_REQUIRED   2   // Flags setting to signify that after the processing of the callback results - exit the browser\r
+#define SAVE_REQUIRED   4   // Flags setting to signify that after the processing of the callback results - save the NV data\r
+#define NV_CHANGED      8   // Flags setting to signify that after the processing of the callback results - turn the NV flag on\r
+#define NV_NOT_CHANGED  16  // Flags setting to signify that after the processing of the callback results - turn the NV flag off\r
+#pragma pack(1)\r
+typedef struct {\r
+  UINT8   OpCode;           // Likely a string, numeric, or one-of\r
+  UINT8   Length;           // Length of the 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
+  // 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 EFI_IFR_NV_DATA structure\r
+  //\r
+} 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
+  // this is a pointer to a buffer copy\r
+  //\r
+  UINT32              EntryCount; // How many EFI_IFR_DATA_ENTRY entries\r
+  //\r
+  // EFI_IFR_DATA_ENTRY  Data[1];    // The in-line Data entries.\r
+  //\r
+} EFI_IFR_DATA_ARRAY;\r
+\r
+\r
+typedef union {\r
+  EFI_IFR_DATA_ARRAY  DataArray;  // Primarily used by those who call back to their drivers and use HII as a repository\r
+  EFI_IFR_PACKET      DataPacket; // Primarily used by those which do not use HII as a repository\r
+  CHAR16              *String;  // If returning an error - fill the string with null-terminated contents\r
+} EFI_HII_CALLBACK_PACKET;\r
+\r
+typedef struct {\r
+  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
+} 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     EFI_IFR_DATA_ARRAY            *Data,\r
+  OUT    EFI_HII_CALLBACK_PACKET       **Packet\r
+  );\r
+\r
+/**\r
+  @par Protocol Description:\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
+  @param NvRead\r
+  The read operation to access the NV data serviced by a hardware-specific driver.\r
+\r
+  @param NvWrite\r
+  The write operation to access the NV data serviced by a hardware-specific driver.\r
+\r
+  @param Callback\r
+  The function that is called from the configuration browser to communicate key value pairs.\r
+\r
+**/\r
+struct _EFI_FORM_CALLBACK_PROTOCOL {\r
+  EFI_NV_READ       NvRead;\r
+  EFI_NV_WRITE      NvWrite;\r
+  EFI_FORM_CALLBACK Callback;\r
+};\r
+\r
+extern EFI_GUID gEfiFormCallbackProtocolGuid;\r
+\r
+#endif\r