IntelFrameworkPkg/Include/Protocol/FrameworkFormBrowser.h

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