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