xref: /illumos-gate/usr/src/boot/efi/include/Protocol/FormBrowser2.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
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 - 2018, Intel Corporation. All rights reserved.<BR>
8 SPDX-License-Identifier: BSD-2-Clause-Patent
9 
10 **/
11 
12 #ifndef __EFI_FORM_BROWSER2_H__
13 #define __EFI_FORM_BROWSER2_H__
14 
15 #include <Guid/HiiPlatformSetupFormset.h>
16 
17 #define EFI_FORM_BROWSER2_PROTOCOL_GUID \
18   {0xb9d4c360, 0xbcfb, 0x4f9b, {0x92, 0x98, 0x53, 0xc1, 0x36, 0x98, 0x22, 0x58 }}
19 
20 typedef struct _EFI_FORM_BROWSER2_PROTOCOL EFI_FORM_BROWSER2_PROTOCOL;
21 
22 /**
23 
24   @param LeftColumn   The value that designates the text column
25                       where the browser window will begin from
26                       the left-hand side of the screen
27 
28   @param RightColumn  The value that designates the text
29                       column where the browser window will end
30                       on the right-hand side of the screen.
31 
32   @param TopRow       The value that designates the text row from the
33                       top of the screen where the browser window
34                       will start.
35 
36   @param BottomRow    The value that designates the text row from the
37                       bottom of the screen where the browser
38                       window will end.
39 **/
40 typedef struct {
41   UINTN    LeftColumn;
42   UINTN    RightColumn;
43   UINTN    TopRow;
44   UINTN    BottomRow;
45 } EFI_SCREEN_DESCRIPTOR;
46 
47 typedef UINTN EFI_BROWSER_ACTION_REQUEST;
48 
49 #define EFI_BROWSER_ACTION_REQUEST_NONE               0
50 #define EFI_BROWSER_ACTION_REQUEST_RESET              1
51 #define EFI_BROWSER_ACTION_REQUEST_SUBMIT             2
52 #define EFI_BROWSER_ACTION_REQUEST_EXIT               3
53 #define EFI_BROWSER_ACTION_REQUEST_FORM_SUBMIT_EXIT   4
54 #define EFI_BROWSER_ACTION_REQUEST_FORM_DISCARD_EXIT  5
55 #define EFI_BROWSER_ACTION_REQUEST_FORM_APPLY         6
56 #define EFI_BROWSER_ACTION_REQUEST_FORM_DISCARD       7
57 #define EFI_BROWSER_ACTION_REQUEST_RECONNECT          8
58 
59 /**
60   Initialize the browser to display the specified configuration forms.
61 
62   This function is the primary interface to the internal forms-based browser.
63   The forms browser will display forms associated with the specified Handles.
64   The browser will select all forms in packages which have the specified Type
65   and (for EFI_HII_PACKAGE_TYPE_GUID) the specified PackageGuid.
66 
67   @param This            A pointer to the EFI_FORM_BROWSER2_PROTOCOL instance
68 
69   @param Handles         A pointer to an array of Handles. This value should correspond
70                          to the value of the HII form package that is required to be displayed.
71 
72   @param HandleCount     The number of Handles specified in Handle.
73 
74   @param FormSetGuid     This field points to the EFI_GUID which must match the Guid field or one of the
75                          elements of the ClassId field  in the EFI_IFR_FORM_SET op-code.  If
76                          FormsetGuid is NULL, then this function will display the form set class
77                          EFI_HII_PLATFORM_SETUP_FORMSET_GUID.
78 
79   @param FormId          This field specifies the identifier of the form within the form set to render as the first
80                          displayable page. If this field has a value of 0x0000, then the Forms Browser will
81                          render the first enabled form in the form set.
82 
83   @param ScreenDimensions Points to recommended form dimensions, including any non-content area, in
84                           characters.
85 
86   @param ActionRequest   Points to the action recommended by the form.
87 
88   @retval EFI_SUCCESS           The function completed successfully
89 
90   @retval EFI_NOT_FOUND         The variable was not found.
91 
92   @retval EFI_INVALID_PARAMETER One of the parameters has an
93                                 invalid value.
94 **/
95 typedef
96 EFI_STATUS
97 (EFIAPI *EFI_SEND_FORM2)(
98   IN CONST  EFI_FORM_BROWSER2_PROTOCOL  *This,
99   IN        EFI_HII_HANDLE              *Handle,
100   IN        UINTN                      HandleCount,
101   IN        EFI_GUID                   *FormSetGuid  OPTIONAL,
102   IN        EFI_FORM_ID                FormId  OPTIONAL,
103   IN CONST  EFI_SCREEN_DESCRIPTOR      *ScreenDimensions  OPTIONAL,
104   OUT       EFI_BROWSER_ACTION_REQUEST *ActionRequest  OPTIONAL
105   );
106 
107 /**
108   This function is called by a callback handler to retrieve uncommitted state data from the browser.
109 
110   This routine is called by a routine which was called by the
111   browser. This routine called this service in the browser to
112   retrieve or set certain uncommitted state information.
113 
114   @param This           A pointer to the EFI_FORM_BROWSER2_PROTOCOL instance.
115 
116   @param ResultsDataSize  A pointer to the size of the buffer
117                           associated with ResultsData. On input, the size in
118                           bytes of ResultsData. On output, the size of data
119                           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 /// This interface will allow the caller to direct the configuration
159 /// driver to use either the HII database or use the passed-in packet of data.
160 ///
161 struct _EFI_FORM_BROWSER2_PROTOCOL {
162   EFI_SEND_FORM2           SendForm;
163   EFI_BROWSER_CALLBACK2    BrowserCallback;
164 };
165 
166 extern EFI_GUID  gEfiFormBrowser2ProtocolGuid;
167 
168 #endif
169