MdePkg/Include/Protocol/FormBrowser.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:  FormBrowser.h
  18
  19   @par Revision Reference:
  20   This protocol is defined in HII spec 0.92.
  21
  22 **/
  23
  24 #ifndef __FORM_BROWSER_H__
  25 #define __FORM_BROWSER_H__
  26
  27
  28 #define EFI_FORM_BROWSER_PROTOCOL_GUID \
  29   { \
  30     0xe5a1333e, 0xe1b4, 0x4d55, {0xce, 0xeb, 0x35, 0xc3, 0xef, 0x13, 0x34, 0x43 } \
  31   }
  32
  33 typedef struct _EFI_FORM_BROWSER_PROTOCOL EFI_FORM_BROWSER_PROTOCOL;
  34
  35 typedef struct {
  36   UINT32  Length;
  37   UINT16  Type;
  38   UINT8   Data[1];
  39 } EFI_HII_PACKET;
  40
  41 typedef struct {
  42   EFI_HII_IFR_PACK    *IfrData;
  43   EFI_HII_STRING_PACK *StringData;
  44 } EFI_IFR_PACKET;
  45
  46 typedef struct {
  47   UINTN LeftColumn;
  48   UINTN RightColumn;
  49   UINTN TopRow;
  50   UINTN BottomRow;
  51 } EFI_SCREEN_DESCRIPTOR;
  52
  53 /**
  54   Provides direction to the configuration driver whether to use the HII
  55   database or a passed-in set of data. This function also establishes a
  56   pointer to the calling driver¡¯s callback interface.
  57
  58   @param  This A pointer to the EFI_FORM_BROWSER_PROTOCOL instance.
  59
  60   @param  UseDatabase Determines whether the HII database is to be
  61   used to gather information. If the value is FALSE, the configuration
  62   driver will get the information provided in the passed-in Packet parameters.
  63
  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
  68   @param  HandleCount The number of handles in the array specified by Handle.
  69
  70   @param  Packet A pointer to a set of data containing pointers to IFR
  71   and/or string data.
  72
  73   @param  CallbackHandle The handle to the driver¡¯s callback interface.
  74   This parameter is used only when the UseDatabase parameter is FALSE
  75   and an application wants to register a callback with the browser
  76
  77   @param  NvMapOverride This buffer is used only when there is no NV variable
  78   to define the current settings and the caller needs to provide to the browser
  79   the current settings for the "fake" NV variable.
  80
  81   @param  ScreenDimensions Allows the browser to be called so that it occupies
  82   a portion of the physical screen instead of dynamically determining the
  83   screen dimensions.
  84
  85   @param  ResetRequired This BOOLEAN value will tell the caller if a reset
  86   is required based on the data that might have been changed. The ResetRequired
  87   parameter is primarily applicable for configuration applications, and is an
  88   optional parameter.
  89
  90   @retval EFI_SUCCESS The function completed successfully
  91
  92   @retval EFI_NOT_FOUND The variable was not found.
  93
  94   @retval EFI_BUFFER_TOO_SMALL The DataSize is too small for the result.
  95   DataSize has been updated with the size needed to complete the request.
  96
  97   @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
  98
  99   @retval EFI_DEVICE_ERROR The variable could not be saved due to a hardware failure.
 100
 101 **/
 102 typedef
 103 EFI_STATUS
 104 (EFIAPI *EFI_SEND_FORM) (
 105   IN  EFI_FORM_BROWSER_PROTOCOL       *This,
 106   IN  BOOLEAN                         UseDatabase,
 107   IN  EFI_HII_HANDLE                  *Handle,
 108   IN  UINTN                           HandleCount,
 109   IN  EFI_IFR_PACKET                  *Packet, OPTIONAL
 110   IN  EFI_HANDLE                      CallbackHandle, OPTIONAL
 111   IN  UINT8                           *NvMapOverride, OPTIONAL
 112   IN EFI_SCREEN_DESCRIPTOR            *ScreenDimensions, OPTIONAL
 113   OUT BOOLEAN                         *ResetRequired OPTIONAL
 114   );
 115
 116 /**
 117   Routine used to abstract a generic dialog interface and return the selected
 118   key or string.
 119
 120   @param  NumberOfLines The number of lines for the dialog box.
 121
 122   @param  HotKey Defines whether a single character is parsed (TRUE)
 123   and returned in KeyValue or if a string is returned in StringBuffer.
 124
 125   @param  MaximumStringSize The maximum size in bytes of a typed-in string.
 126   Because each character is a CHAR16, the minimum string returned is two bytes.
 127
 128   @param  StringBuffer The passed-in pointer to the buffer that will hold
 129   the typed in string if HotKey is FALSE.
 130
 131   @param  KeyValue The EFI_INPUT_KEY value returned if HotKey is TRUE.
 132
 133   @param  String The pointer to the first string in the list of strings
 134   that comprise the dialog box.
 135
 136   @param  ... A series of NumberOfLines text strings that will be used
 137   to construct the dialog box.
 138
 139   @retval EFI_SUCCESS The dialog was displayed and user interaction was received.
 140
 141   @retval EFI_DEVICE_ERROR The user typed in an ESC character to exit the routine.
 142
 143   @retval EFI_INVALID_PARAMETER One of the parameters was invalid
 144
 145 **/
 146 typedef
 147 EFI_STATUS
 148 (EFIAPI *EFI_CREATE_POP_UP) (
 149   IN  UINTN                           NumberOfLines,
 150   IN  BOOLEAN                         HotKey,
 151   IN  UINTN                           MaximumStringSize,
 152   OUT CHAR16                          *StringBuffer,
 153   OUT EFI_INPUT_KEY                   *KeyValue,
 154   IN  CHAR16                          *String,
 155   ...
 156   );
 157
 158 /**
 159   @par Protocol Description:
 160   The EFI_FORM_BROWSER_PROTOCOL is the interface to call for drivers to
 161   leverage the EFI configuration driver interface.
 162
 163   @param SendForm
 164   Provides direction to the configuration driver whether to use the HII
 165   database or to use a passed-in set of data. This functions also establishes
 166   a pointer to the calling driver¡¯s callback interface.
 167
 168   @param CreatePopUp
 169   Routine used to abstract a generic dialog interface and return the
 170   selected key or string.
 171
 172 **/
 173 struct _EFI_FORM_BROWSER_PROTOCOL {
 174   EFI_SEND_FORM     SendForm;
 175   EFI_CREATE_POP_UP CreatePopUp;
 176 };
 177
 178 extern EFI_GUID gEfiFormBrowserProtocolGuid;
 179
 180 #endif