MdePkg/Include/Protocol/FormBrowser2.h

   1 /** @file
   2   This protocol is defined in UEFI spec.
   3
   4   The EFI_FORM_BROWSER2_PROTOCOL is the interface to call for drivers to
   5   leverage the EFI configuration driver interface.
   6
   7   Copyright (c) 2006 - 2008, Intel Corporation
   8   All rights reserved. This program and the accompanying materials
   9   are licensed and made available under the terms and conditions of the BSD License
  10   which accompanies this distribution.  The full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16 **/
  17
  18 #ifndef __EFI_FORM_BROWSER2_H__
  19 #define __EFI_FORM_BROWSER2_H__
  20
  21 #define EFI_FORM_BROWSER2_PROTOCOL_GUID \
  22   {0xb9d4c360, 0xbcfb, 0x4f9b, {0x92, 0x98, 0x53, 0xc1, 0x36, 0x98, 0x22, 0x58 }}
  23
  24
  25 typedef struct _EFI_FORM_BROWSER2_PROTOCOL   EFI_FORM_BROWSER2_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
  35   @param RightColumn  Value that designates the text
  36                       column where the browser window will end
  37                       on the right-hand side of the screen.
  38
  39   @param TopRow       Value that designates the text row from the
  40                       top of the screen where the browser window
  41                       will start.
  42
  43   @param BottomRow    Value that designates the text row from the
  44                       bottom of the screen where the browser
  45                       window will end.
  46 **/
  47 typedef struct {
  48   UINTN   LeftColumn;
  49   UINTN   RightColumn;
  50   UINTN   TopRow;
  51   UINTN   BottomRow;
  52 } EFI_SCREEN_DESCRIPTOR;
  53
  54 typedef UINTN EFI_BROWSER_ACTION_REQUEST;
  55
  56 #define EFI_BROWSER_ACTION_REQUEST_NONE   0
  57 #define EFI_BROWSER_ACTION_REQUEST_RESET  1
  58 #define EFI_BROWSER_ACTION_REQUEST_SUBMIT 2
  59 #define EFI_BROWSER_ACTION_REQUEST_EXIT   3
  60
  61
  62 /**
  63   This function is the primary interface to the internal forms-based browser.
  64   The forms browser will display forms associated with the specified Handles.
  65   The browser will select all forms in packages which have the specified Type
  66   and (for EFI_HII_PACKAGE_TYPE_GUID) the specified PackageGuid.
  67
  68   @param This            A pointer to the EFI_FORM_BROWSER2_PROTOCOL instance
  69
  70   @param Handles         A pointer to an array of Handles. This value should correspond
  71                          to the value of the HII form package that is required to be displayed. Type
  72
  73   @param HandleCount     The number of Handles specified in Handle.
  74
  75   @param FormSetGuid     This field points to the EFI_GUID which must match the Guid
  76                          field in the EFI_IFR_FORM_SET op-code for the specified
  77                          forms-based package. If FormSetGuid is NULL, then this
  78                          function will display the first found forms package.
  79
  80   @param FormId          This field specifies which EFI_IFR_FORM to render as the first
  81                          displayable page. If this field has a value of 0x0000, then
  82                          the forms browser will render the specified forms in their encoded order.
  83
  84   @param ScreenDimensions Points to recommended form dimensions, including any non-content area, in
  85                           characters.
  86
  87   @param ActionRequest   Points to the action recommended by the form.
  88
  89   @retval EFI_SUCCESS           The function completed successfully
  90
  91   @retval EFI_NOT_FOUND         The variable was not found.
  92
  93   @retval EFI_INVALID_PARAMETER One of the parameters has an
  94                                 invalid value.
  95 **/
  96 typedef
  97 EFI_STATUS
  98 (EFIAPI *EFI_SEND_FORM2)(
  99   IN CONST  EFI_FORM_BROWSER2_PROTOCOL  *This,
 100   IN        EFI_HII_HANDLE              *Handle,
 101   IN        UINTN                      HandleCount,
 102   IN        EFI_GUID                   *FormSetGuid, OPTIONAL
 103   IN        EFI_FORM_ID                FormId, OPTIONAL
 104   IN CONST  EFI_SCREEN_DESCRIPTOR      *ScreenDimensions, OPTIONAL
 105   OUT       EFI_BROWSER_ACTION_REQUEST *ActionRequest  OPTIONAL
 106 );
 107
 108
 109 /**
 110
 111   This routine is called by a routine which was called by the
 112   browser. This routine called this service in the browser to
 113   retrieve or set certain uncommitted state information.
 114
 115   @param This           A pointer to the EFI_FORM_BROWSER2_PROTOCOL instance.
 116
 117   @param ResultsDataSize  A pointer to the size of the buffer
 118                           associated with ResultsData. On input, the size in
 119                           bytes of ResultsData. On output, the size of data returned in ResultsData.
 120
 121   @param ResultsData    A string returned from an IFR browser or
 122                         equivalent. The results string will have
 123                         no routing information in them.
 124
 125   @param RetrieveData   A BOOLEAN field which allows an agent to
 126                         retrieve (if RetrieveData = TRUE) data
 127                         from the uncommitted browser state
 128                         information or set (if RetrieveData =
 129                         FALSE) data in the uncommitted browser
 130                         state information.
 131
 132   @param VariableGuid   An optional field to indicate the target
 133                         variable GUID name to use.
 134
 135   @param VariableName   An optional field to indicate the target
 136                         human-readable variable name.
 137
 138   @retval EFI_SUCCESS           The results have been distributed or are
 139                                 awaiting distribution.
 140
 141   @retval EFI_OUT_OF_RESOURCES  The ResultsDataSize specified
 142                                 was too small to contain the
 143                                 results data.
 144
 145 **/
 146 typedef
 147 EFI_STATUS
 148 (EFIAPI *EFI_BROWSER_CALLBACK2)(
 149   IN CONST  EFI_FORM_BROWSER2_PROTOCOL *This,
 150   IN OUT    UINTN                     *ResultsDataSize,
 151   IN OUT    EFI_STRING                ResultsData,
 152   IN CONST  BOOLEAN                   RetrieveData,
 153   IN CONST  EFI_GUID                  *VariableGuid, OPTIONAL
 154   IN CONST  CHAR16                    *VariableName OPTIONAL
 155 );
 156
 157 /**
 158   @par Protocol Description:
 159   This interface will allow the caller to direct the configuration
 160   driver to use either the HII database or use the passed-in packet of data.
 161
 162   @param SendForm         Browse the specified configuration forms.
 163
 164   @param BrowserCallback  Routine used to expose internal
 165                           configuration state of the browser.
 166                           This is primarily used by callback
 167                           handler routines which were called by
 168                           the browser and in-turn need to get
 169                           additional information from the
 170                           browser itself.
 171
 172 **/
 173 struct _EFI_FORM_BROWSER2_PROTOCOL {
 174   EFI_SEND_FORM2         SendForm;
 175   EFI_BROWSER_CALLBACK2  BrowserCallback;
 176 } ;
 177
 178
 179 extern EFI_GUID gEfiFormBrowser2ProtocolGuid;
 180
 181 #endif
 182