IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h

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