MdePkg/Include/Protocol/FormBrowser2.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 #define EFI_FORM_BROWSER2_PROTOCOL_GUID \
  21   {0xb9d4c360, 0xbcfb, 0x4f9b, {0x92, 0x98, 0x53, 0xc1, 0x36, 0x98, 0x22, 0x58 }}
  22
  23
  24 typedef struct _EFI_FORM_BROWSER2_PROTOCOL   EFI_FORM_BROWSER2_PROTOCOL;
  25
  26
  27
  28 /**
  29
  30   @param LeftColumn   Value that designates the text column
  31                       where the browser window will begin from
  32                       the left-hand side of the screen
  33                       RightColumn Value that designates the text
  34                       column where the browser window will end
  35                       on the right-hand side of the screen.
  36
  37   @param TopRow   Value that designates the text row from the
  38                   top of the screen where the browser window
  39                   will start.
  40
  41   @param BottomRow  Value that designates the text row from the
  42                     bottom of the screen where the browser
  43                     window will end.
  44 **/
  45 typedef struct {
  46   UINTN   LeftColumn;
  47   UINTN   RightColumn;
  48   UINTN   TopRow;
  49   UINTN   BottomRow;
  50 } EFI_SCREEN_DESCRIPTOR;
  51
  52 typedef UINTN EFI_BROWSER_ACTION_REQUEST;
  53
  54 #define EFI_BROWSER_ACTION_REQUEST_NONE   0
  55 #define EFI_BROWSER_ACTION_REQUEST_RESET  1
  56 #define EFI_BROWSER_ACTION_REQUEST_SUBMIT 2
  57 #define EFI_BROWSER_ACTION_REQUEST_EXIT   3
  58
  59
  60 /**
  61
  62   This function is the primary interface to the internal
  63   forms-based browser. By calling this routine, one is directing
  64   the browser to use a variety of passed-in information or
  65   primarily use the HII database as the source of information.
  66
  67   @param This   A pointer to the EFI_FORM_BROWSER2_PROTOCOL
  68                 instance.
  69
  70   @param Handle   A pointer to an array of HII handles to
  71                   display. This value should correspond to the
  72                   value of the HII form package that is required
  73                   to be displayed.
  74
  75   @param HandleCount  The number of handles in the array
  76                       specified by Handle.
  77
  78   @param SingleUse  If FALSE, the browser operates as a standard
  79                     forms processor and exits only when
  80                     explicitly requested by the user. If TRUE,
  81                     the browser will return immediately after
  82                     processing the first user-generated
  83                     selection.
  84
  85   @param ScreenDimensions   Allows the browser to be called so
  86                             that it occupies a portion of the
  87                             physical screen instead of
  88                             dynamically determining the screen
  89                             dimensions. If the input values
  90                             violate the platform policy then the
  91                             dimensions will be dynamically
  92                             adjusted to comply.
  93
  94   @param ResetRequired  This BOOLEAN value will tell the caller
  95                         if a reset is required based on the data
  96                         that might have been changed. The
  97                         ResetRequired parameter is primarily
  98                         applicable for configuration
  99                         applications, and is an optional
 100                         parameter.
 101
 102   @retval EFI_SUCCESS   The function completed successfully
 103
 104   @retval EFI_NOT_FOUND   The variable was not found.
 105
 106   @retval EFI_BUFFER_TOO_SMALL  The DataSize is too small for
 107                                 the result. DataSize has been
 108                                 updated with the size needed to
 109                                 complete the request.
 110
 111   @retval EFI_INVALID_PARAMETER   One of the parameters has an
 112                                   invalid value.
 113
 114   @retval EFI_DEVICE_ERROR  The variable could not be saved due
 115                             to a hardware failure.
 116
 117 **/
 118 typedef
 119 EFI_STATUS
 120 (EFIAPI *EFI_SEND_FORM2) (
 121   IN CONST  EFI_FORM_BROWSER2_PROTOCOL  *This,
 122   IN        EFI_HII_HANDLE              *Handle,
 123   IN        UINTN                      HandleCount,
 124   IN        EFI_GUID                   *FormSetGuid, OPTIONAL
 125   IN        EFI_FORM_ID                FormId, OPTIONAL
 126   IN CONST  EFI_SCREEN_DESCRIPTOR      *ScreenDimensions, OPTIONAL
 127   OUT       EFI_BROWSER_ACTION_REQUEST *ActionRequest  OPTIONAL
 128 );
 129
 130
 131 /**
 132
 133   This routine is called by a routine which was called by the
 134   browser. This routine called this service in the browser to
 135   retrieve or set certain uncommitted state information.
 136
 137   @param This   A pointer to the EFI_FORM_BROWSER2_PROTOCOL
 138                 instance.
 139
 140   @param ResultsDataSize  A pointer to the size of the buffer
 141                           associated with ResultsData.
 142
 143   @param ResultsData  A string returned from an IFR browser or
 144                       equivalent. The results string will have
 145                       no routing information in them.
 146
 147   @param RetrieveData   A BOOLEAN field which allows an agent to
 148                         retrieve (if RetrieveData = TRUE) data
 149                         from the uncommitted browser state
 150                         information or set (if RetrieveData =
 151                         FALSE) data in the uncommitted browser
 152                         state information.
 153
 154   @param VariableGuid   An optional field to indicate the target
 155                         variable GUID name to use.
 156
 157   @param VariableName   An optional field to indicate the target
 158                         human-readable variable name.
 159
 160
 161   @retval EFI_SUCCESS   The results have been distributed or are
 162                         awaiting distribution.
 163
 164   @retval EFI_OUT_OF_RESOURCES  The ResultsDataSize specified
 165                                 was too small to contain the
 166                                 results data.
 167
 168 **/
 169 typedef
 170 EFI_STATUS
 171 (EFIAPI *EFI_BROWSER_CALLBACK2 ) (
 172   IN CONST  EFI_FORM_BROWSER2_PROTOCOL *This,
 173   IN OUT    UINTN                     *ResultsDataSize,
 174   IN OUT    EFI_STRING                ResultsData,
 175   IN CONST  BOOLEAN                   RetrieveData,
 176   IN CONST  EFI_GUID                  *VariableGuid, OPTIONAL
 177   IN CONST  CHAR16                    *VariableName OPTIONAL
 178 );
 179
 180 /**
 181
 182   This protocol is the interface to call for drivers to leverage
 183   the EFI configuration driver interface.
 184
 185   @param SendForm   Provides direction to the configuration
 186                     driver whether to use the HII database or to
 187                     use a passed-in set of data. This functions
 188                     also establishes a pointer to the calling
 189                     driver's callback interface. See the
 190                     SendForm() function description.
 191
 192   @param BrowserCallback  Routine used to expose internal
 193                           configuration state of the browser.
 194                           This is primarily used by callback
 195                           handler routines which were called by
 196                           the browser and in-turn need to get
 197                           additional information from the
 198                           browser itself. See the
 199                           BrowserCallback() function
 200                           description.
 201
 202 **/
 203 struct _EFI_FORM_BROWSER2_PROTOCOL {
 204   EFI_SEND_FORM2         SendForm;
 205   EFI_BROWSER_CALLBACK2  BrowserCallback;
 206 } ;
 207
 208
 209 extern EFI_GUID gEfiFormBrowser2ProtocolGuid;
 210
 211 #endif
 212