MdePkg/Include/Protocol/FormBrowser.h

   1 /** @file
   2
   3   The file provides services to call for drivers to leverage the
   4   EFI configuration driver interface.
   5
   6   Copyright (c) 2006 - 2007, Intel Corporation
   7   All rights reserved. This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef __EFI_FORM_BROWSER_H__
  18 #define __EFI_FORM_BROWSER_H__
  19
  20 #error "UEFI 2.1 HII is not fully implemented for now, Please don't include this file now."
  21
  22
  23 #define EFI_FORM_BROWSER2_PROTOCOL_GUID \
  24   { 0xe5a1333e, 0xe1b4, 0x4e55, { 0xce, 0xeb, 0x35, 0xc3, 0xef, 0x13, 0x34, 0x43 } }
  25
  26
  27 typedef struct _EFI_FORM_BROWSER2_PROTOCOL   EFI_FORM_BROWSER2_PROTOCOL;
  28
  29
  30
  31 /**
  32
  33   @param LeftColumn   Value that designates the text column
  34                       where the browser window will begin from
  35                       the left-hand side of the screen
  36                       RightColumn Value that designates the text
  37                       column where the browser window will end
  38                       on the right-hand side of the screen.
  39
  40   @param TopRow   Value that designates the text row from the
  41                   top of the screen where the browser window
  42                   will start.
  43
  44   @param BottomRow  Value that designates the text row from the
  45                     bottom of the screen where the browser
  46                     window will end.
  47 **/
  48 typedef struct {
  49   UINTN   LeftColumn;
  50   UINTN   RightColumn;
  51   UINTN   TopRow;
  52   UINTN   BottomRow;
  53 } EFI_SCREEN_DESCRIPTOR;
  54
  55 typedef UINTN EFI_BROWSER_ACTION_REQUEST;
  56
  57 #define EFI_BROWSER_ACTION_NONE   0
  58 #define EFI_BROWSER_ACTION_RESET  1
  59 #define EFI_BROWSER_ACTION_SUMBIT 2
  60 #define EFI_BROWSER_ACTION_EXIT   3
  61
  62
  63 /**
  64
  65   This function is the primary interface to the internal
  66   forms-based browser. By calling this routine, one is directing
  67   the browser to use a variety of passed-in information or
  68   primarily use the HII database as the source of information.
  69
  70   @param This   A pointer to the EFI_FORM_BROWSER_PROTOCOL
  71                 instance.
  72
  73   @param Handle   A pointer to an array of HII handles to
  74                   display. This value should correspond to the
  75                   value of the HII form package that is required
  76                   to be displayed.
  77
  78   @param HandleCount  The number of handles in the array
  79                       specified by Handle.
  80
  81   @param SingleUse  If FALSE, the browser operates as a standard
  82                     forms processor and exits only when
  83                     explicitly requested by the user. If TRUE,
  84                     the browser will return immediately after
  85                     processing the first user-generated
  86                     selection.
  87
  88   @param ScreenDimensions   Allows the browser to be called so
  89                             that it occupies a portion of the
  90                             physical screen instead of
  91                             dynamically determining the screen
  92                             dimensions. If the input values
  93                             violate the platform policy then the
  94                             dimensions will be dynamically
  95                             adjusted to comply.
  96
  97   @param ResetRequired  This BOOLEAN value will tell the caller
  98                         if a reset is required based on the data
  99                         that might have been changed. The
 100                         ResetRequired parameter is primarily
 101                         applicable for configuration
 102                         applications, and is an optional
 103                         parameter.
 104
 105   @retval EFI_SUCCESS   The function completed successfully
 106
 107   @retval EFI_NOT_FOUND   The variable was not found.
 108
 109   @retval EFI_BUFFER_TOO_SMALL  The DataSize is too small for
 110                                 the result. DataSize has been
 111                                 updated with the size needed to
 112                                 complete the request.
 113
 114   @retval EFI_INVALID_PARAMETER   One of the parameters has an
 115                                   invalid value.
 116
 117   @retval EFI_DEVICE_ERROR  The variable could not be saved due
 118                             to a hardware failure.
 119
 120 **/
 121 typedef
 122 EFI_STATUS
 123 (EFIAPI *EFI_SEND_FORM2) (
 124   IN CONST  EFI_FORM_BROWSER_PROTOCOL  *This,
 125   IN CONST  EFI_HII_HANDLE             *Handle,
 126   IN CONST  UINTN                      HandleCount,
 127   IN CONST  BOOLEAN                    SingleUse,
 128   IN CONST  EFI_SCREEN_DESCRIPTOR      *ScreenDimensions, OPTIONAL
 129   OUT       BOOLEAN                    *ResetRequired OPTIONAL
 130   OUT       EFI_BROWSER_ACTION_REQUEST *ActionRequest  OPTIONAL
 131 );
 132
 133
 134 /**
 135
 136   This routine is called by a routine which was called by the
 137   browser. This routine called this service in the browser to
 138   retrieve or set certain uncommitted state information.
 139
 140   @param This   A pointer to the EFI_FORM_BROWSER_PROTOCOL
 141                 instance.
 142
 143   @param ResultsDataSize  A pointer to the size of the buffer
 144                           associated with ResultsData.
 145
 146   @param ResultsData  A string returned from an IFR browser or
 147                       equivalent. The results string will have
 148                       no routing information in them.
 149
 150   @param RetrieveData   A BOOLEAN field which allows an agent to
 151                         retrieve (if RetrieveData = TRUE) data
 152                         from the uncommitted browser state
 153                         information or set (if RetrieveData =
 154                         FALSE) data in the uncommitted browser
 155                         state information.
 156
 157   @param VariableGuid   An optional field to indicate the target
 158                         variable GUID name to use.
 159
 160   @param VariableName   An optional field to indicate the target
 161                         human-readable variable name.
 162
 163
 164   @retval EFI_SUCCESS   The results have been distributed or are
 165                         awaiting distribution.
 166
 167   @retval EFI_OUT_OF_RESOURCES  The ResultsDataSize specified
 168                                 was too small to contain the
 169                                 results data.
 170
 171 **/
 172 typedef
 173 EFI_STATUS
 174 (EFIAPI *EFI_BROWSER_CALLBACK2 ) (
 175   IN CONST  EFI_FORM_BROWSER_PROTOCOL *This,
 176   IN OUT    UINTN                     *ResultsDataSize,
 177   IN OUT    EFI_STRING                ResultsData,
 178   IN CONST  BOOLEAN                   RetrieveData,
 179   IN CONST  EFI_GUID                  *VariableGuid, OPTIONAL
 180   IN CONST  CHAR16                    *VariableName OPTIONAL
 181 );
 182
 183 /**
 184
 185   This protocol is the interface to call for drivers to leverage
 186   the EFI configuration driver interface.
 187
 188   @param SendForm   Provides direction to the configuration
 189                     driver whether to use the HII database or to
 190                     use a passed-in set of data. This functions
 191                     also establishes a pointer to the calling
 192                     driver's callback interface. See the
 193                     SendForm() function description.
 194
 195   @param BrowserCallback  Routine used to expose internal
 196                           configuration state of the browser.
 197                           This is primarily used by callback
 198                           handler routines which were called by
 199                           the browser and in-turn need to get
 200                           additional information from the
 201                           browser itself. See the
 202                           BrowserCallback() function
 203                           description.
 204
 205 **/
 206 struct _EFI_FORM_BROWSER2_PROTOCOL {
 207   EFI_SEND_FORM2         SendForm;
 208   EFI_BROWSER_CALLBACK2  BrowserCallback;
 209 } ;
 210
 211
 212 extern EFI_GUID gEfiFormBrowser2ProtocolGuid;
 213
 214 #endif
 215
 216