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   Module Name: FormBrowser.h
  16
  17 **/
  18
  19 #ifndef __EFI_FORM_BROWSER_H__
  20 #define __EFI_FORM_BROWSER_H__
  21
  22
  23 #define EFI_FORM_BROWSER_PROTOCOL_GUID \
  24   { 0xe5a1333e, 0xe1b4, 0x4e55, { 0xce, 0xeb, 0x35, 0xc3, 0xef, 0x13, 0x34, 0x43 } }
  25
  26
  27 typedef struct _EFI_FORM_BROWSER_PROTOCOL   EFI_FORM_BROWSER_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 /**
  56
  57   This function is the primary interface to the internal
  58   forms-based browser. By calling this routine, one is directing
  59   the browser to use a variety of passed-in information or
  60   primarily use the HII database as the source of information.
  61
  62   @param This   A pointer to the EFI_FORM_BROWSER_PROTOCOL
  63                 instance.
  64
  65   @param Handle   A pointer to an array of HII handles to
  66                   display. This value should correspond to the
  67                   value of the HII form package that is required
  68                   to be displayed.
  69
  70   @param HandleCount  The number of handles in the array
  71                       specified by Handle.
  72
  73   @param SingleUse  If FALSE, the browser operates as a standard
  74                     forms processor and exits only when
  75                     explicitly requested by the user. If TRUE,
  76                     the browser will return immediately after
  77                     processing the first user-generated
  78                     selection.
  79
  80   @param ScreenDimensions   Allows the browser to be called so
  81                             that it occupies a portion of the
  82                             physical screen instead of
  83                             dynamically determining the screen
  84                             dimensions. If the input values
  85                             violate the platform policy then the
  86                             dimensions will be dynamically
  87                             adjusted to comply.
  88
  89   @param ResetRequired  This BOOLEAN value will tell the caller
  90                         if a reset is required based on the data
  91                         that might have been changed. The
  92                         ResetRequired parameter is primarily
  93                         applicable for configuration
  94                         applications, and is an optional
  95                         parameter.
  96
  97   @retval EFI_SUCCESS   The function completed successfully
  98
  99   @retval EFI_NOT_FOUND   The variable was not found.
 100
 101   @retval EFI_BUFFER_TOO_SMALL  The DataSize is too small for
 102                                 the result. DataSize has been
 103                                 updated with the size needed to
 104                                 complete the request.
 105
 106   @retval EFI_INVALID_PARAMETER   One of the parameters has an
 107                                   invalid value.
 108
 109   @retval EFI_DEVICE_ERROR  The variable could not be saved due
 110                             to a hardware failure.
 111
 112 **/
 113 typedef
 114 EFI_STATUS
 115 (EFIAPI *EFI_SEND_FORM) (
 116   IN CONST  EFI_FORM_BROWSER_PROTOCOL *This,
 117   IN CONST  EFI_HII_HANDLE            *Handle,
 118   IN CONST  UINTN                     HandleCount,
 119   IN CONST  BOOLEAN                   SingleUse,
 120   IN CONST  EFI_SCREEN_DESCRIPTOR     *ScreenDimensions, OPTIONAL
 121   OUT       BOOLEAN                   *ResetRequired OPTIONAL
 122 );
 123
 124
 125 /**
 126
 127   This routine is called by a routine which was called by the
 128   browser. This routine called this service in the browser to
 129   retrieve or set certain uncommitted state information.
 130
 131   @param This   A pointer to the EFI_FORM_BROWSER_PROTOCOL
 132                 instance.
 133
 134   @param ResultsDataSize  A pointer to the size of the buffer
 135                           associated with ResultsData.
 136
 137   @param ResultsData  A string returned from an IFR browser or
 138                       equivalent. The results string will have
 139                       no routing information in them.
 140
 141   @param RetrieveData   A BOOLEAN field which allows an agent to
 142                         retrieve (if RetrieveData = TRUE) data
 143                         from the uncommitted browser state
 144                         information or set (if RetrieveData =
 145                         FALSE) data in the uncommitted browser
 146                         state information.
 147
 148   @param VariableGuid   An optional field to indicate the target
 149                         variable GUID name to use.
 150
 151   @param VariableName   An optional field to indicate the target
 152                         human-readable variable name.
 153
 154
 155   @retval EFI_SUCCESS   The results have been distributed or are
 156                         awaiting distribution.
 157
 158   @retval EFI_OUT_OF_RESOURCES  The ResultsDataSize specified
 159                                 was too small to contain the
 160                                 results data.
 161
 162 **/
 163 typedef
 164 EFI_STATUS
 165 (EFIAPI *EFI_BROWSER_CALLBACK ) (
 166   IN CONST  EFI_FORM_BROWSER_PROTOCOL *This,
 167   IN OUT    UINTN                     *ResultsDataSize,
 168   IN OUT    EFI_STRING                ResultsData,
 169   IN CONST  BOOLEAN                   RetrieveData,
 170   IN CONST  EFI_GUID                  *VariableGuid, OPTIONAL
 171   IN CONST  CHAR16                    *VariableName OPTIONAL
 172 );
 173
 174 /**
 175
 176   This protocol is the interface to call for drivers to leverage
 177   the EFI configuration driver interface.
 178
 179   @param SendForm   Provides direction to the configuration
 180                     driver whether to use the HII database or to
 181                     use a passed-in set of data. This functions
 182                     also establishes a pointer to the calling
 183                     driver's callback interface. See the
 184                     SendForm() function description.
 185
 186   @param BrowserCallback  Routine used to expose internal
 187                           configuration state of the browser.
 188                           This is primarily used by callback
 189                           handler routines which were called by
 190                           the browser and in-turn need to get
 191                           additional information from the
 192                           browser itself. See the
 193                           BrowserCallback() function
 194                           description.
 195
 196 **/
 197 struct _EFI_FORM_BROWSER_PROTOCOL {
 198   EFI_SEND_FORM         SendForm;
 199   EFI_BROWSER_CALLBACK  BrowserCallback;
 200 } ;
 201
 202
 203 extern EFI_GUID gEfiFormBrowserProtocolGuid;
 204
 205 #endif
 206
 207