1/** @file
2
3  The EFI HII results processing protocol invokes this type of protocol
4  when it needs to forward results to a driver's configuration handler.
5  This protocol is published by drivers providing and requesting
6  configuration data from HII. It may only be invoked by HII.
7
8Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR>
9This program and the accompanying materials are licensed and made available under
10the terms and conditions of the BSD License that accompanies this distribution.
11The full text of the license may be found at
12http://opensource.org/licenses/bsd-license.php.
13
14THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16
17**/
18
19
20#ifndef __EFI_HII_CONFIG_ACCESS_H__
21#define __EFI_HII_CONFIG_ACCESS_H__
22
23#include <Protocol/FormBrowser2.h>
24
25#define EFI_HII_CONFIG_ACCESS_PROTOCOL_GUID  \
26  { 0x330d4706, 0xf2a0, 0x4e4f, { 0xa3, 0x69, 0xb6, 0x6f, 0xa8, 0xd5, 0x43, 0x85 } }
27
28typedef struct _EFI_HII_CONFIG_ACCESS_PROTOCOL  EFI_HII_CONFIG_ACCESS_PROTOCOL;
29
30typedef UINTN EFI_BROWSER_ACTION;
31
32#define EFI_BROWSER_ACTION_CHANGING   0
33#define EFI_BROWSER_ACTION_CHANGED    1
34#define EFI_BROWSER_ACTION_RETRIEVE   2
35#define EFI_BROWSER_ACTION_FORM_OPEN  3
36#define EFI_BROWSER_ACTION_FORM_CLOSE 4
37#define EFI_BROWSER_ACTION_SUBMITTED  5
38#define EFI_BROWSER_ACTION_DEFAULT_STANDARD      0x1000
39#define EFI_BROWSER_ACTION_DEFAULT_MANUFACTURING 0x1001
40#define EFI_BROWSER_ACTION_DEFAULT_SAFE          0x1002
41#define EFI_BROWSER_ACTION_DEFAULT_PLATFORM      0x2000
42#define EFI_BROWSER_ACTION_DEFAULT_HARDWARE      0x3000
43#define EFI_BROWSER_ACTION_DEFAULT_FIRMWARE      0x4000
44
45/**
46
47  This function allows the caller to request the current
48  configuration for one or more named elements. The resulting
49  string is in <ConfigAltResp> format. Any and all alternative
50  configuration strings shall also be appended to the end of the
51  current configuration string. If they are, they must appear
52  after the current configuration. They must contain the same
53  routing (GUID, NAME, PATH) as the current configuration string.
54  They must have an additional description indicating the type of
55  alternative configuration the string represents,
56  "ALTCFG=<StringToken>". That <StringToken> (when
57  converted from Hex UNICODE to binary) is a reference to a
58  string in the associated string pack.
59
60  @param This       Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
61
62  @param Request    A null-terminated Unicode string in
63                    <ConfigRequest> format. Note that this
64                    includes the routing information as well as
65                    the configurable name / value pairs. It is
66                    invalid for this string to be in
67                    <MultiConfigRequest> format.
68                    If a NULL is passed in for the Request field,
69                    all of the settings being abstracted by this function
70                    will be returned in the Results field.  In addition,
71                    if a ConfigHdr is passed in with no request elements,
72                    all of the settings being abstracted for that particular
73                    ConfigHdr reference will be returned in the Results Field.
74
75  @param Progress   On return, points to a character in the
76                    Request string. Points to the string's null
77                    terminator if request was successful. Points
78                    to the most recent "&" before the first
79                    failing name / value pair (or the beginning
80                    of the string if the failure is in the first
81                    name / value pair) if the request was not
82                    successful.
83
84  @param Results    A null-terminated Unicode string in
85                    <MultiConfigAltResp> format which has all values
86                    filled in for the names in the Request string.
87                    String to be allocated by the called function.
88
89  @retval EFI_SUCCESS             The Results string is filled with the
90                                  values corresponding to all requested
91                                  names.
92
93  @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the
94                                  parts of the results that must be
95                                  stored awaiting possible future
96                                  protocols.
97
98  @retval EFI_NOT_FOUND           A configuration element matching
99                                  the routing data is not found.
100                                  Progress set to the first character
101                                  in the routing header.
102
103  @retval EFI_INVALID_PARAMETER   Illegal syntax. Progress set
104                                  to most recent "&" before the
105                                  error or the beginning of the
106                                  string.
107
108  @retval EFI_INVALID_PARAMETER   Unknown name. Progress points
109                                  to the & before the name in
110                                  question.
111
112**/
113typedef
114EFI_STATUS
115(EFIAPI * EFI_HII_ACCESS_EXTRACT_CONFIG)(
116  IN CONST  EFI_HII_CONFIG_ACCESS_PROTOCOL  *This,
117  IN CONST  EFI_STRING                      Request,
118  OUT       EFI_STRING                      *Progress,
119  OUT       EFI_STRING                      *Results
120);
121
122
123/**
124
125  This function applies changes in a driver's configuration.
126  Input is a Configuration, which has the routing data for this
127  driver followed by name / value configuration pairs. The driver
128  must apply those pairs to its configurable storage. If the
129  driver's configuration is stored in a linear block of data
130  and the driver's name / value pairs are in <BlockConfig>
131  format, it may use the ConfigToBlock helper function (above) to
132  simplify the job.
133
134  @param This           Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
135
136  @param Configuration  A null-terminated Unicode string in
137                        <ConfigString> format.
138
139  @param Progress       A pointer to a string filled in with the
140                        offset of the most recent '&' before the
141                        first failing name / value pair (or the
142                        beginn ing of the string if the failure
143                        is in the first name / value pair) or
144                        the terminating NULL if all was
145                        successful.
146
147  @retval EFI_SUCCESS             The results have been distributed or are
148                                  awaiting distribution.
149
150  @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the
151                                  parts of the results that must be
152                                  stored awaiting possible future
153                                  protocols.
154
155  @retval EFI_INVALID_PARAMETERS  Passing in a NULL for the
156                                  Results parameter would result
157                                  in this type of error.
158
159  @retval EFI_NOT_FOUND           Target for the specified routing data
160                                  was not found
161
162**/
163typedef
164EFI_STATUS
165(EFIAPI * EFI_HII_ACCESS_ROUTE_CONFIG)(
166  IN CONST  EFI_HII_CONFIG_ACCESS_PROTOCOL  *This,
167  IN CONST  EFI_STRING                      Configuration,
168  OUT       EFI_STRING                      *Progress
169);
170
171/**
172
173  This function is called to provide results data to the driver.
174  This data consists of a unique key that is used to identify
175  which data is either being passed back or being asked for.
176
177  @param  This                   Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
178  @param  Action                 Specifies the type of action taken by the browser.
179  @param  QuestionId             A unique value which is sent to the original
180                                 exporting driver so that it can identify the type
181                                 of data to expect. The format of the data tends to
182                                 vary based on the opcode that generated the callback.
183  @param  Type                   The type of value for the question.
184  @param  Value                  A pointer to the data being sent to the original
185                                 exporting driver.
186  @param  ActionRequest          On return, points to the action requested by the
187                                 callback function.
188
189  @retval EFI_SUCCESS            The callback successfully handled the action.
190  @retval EFI_OUT_OF_RESOURCES   Not enough storage is available to hold the
191                                 variable and its data.
192  @retval EFI_DEVICE_ERROR       The variable could not be saved.
193  @retval EFI_UNSUPPORTED        The specified Action is not supported by the
194                                 callback.
195**/
196typedef
197EFI_STATUS
198(EFIAPI *EFI_HII_ACCESS_FORM_CALLBACK)(
199  IN     CONST EFI_HII_CONFIG_ACCESS_PROTOCOL   *This,
200  IN     EFI_BROWSER_ACTION                     Action,
201  IN     EFI_QUESTION_ID                        QuestionId,
202  IN     UINT8                                  Type,
203  IN OUT EFI_IFR_TYPE_VALUE                     *Value,
204  OUT    EFI_BROWSER_ACTION_REQUEST             *ActionRequest
205  )
206  ;
207
208///
209/// This protocol provides a callable interface between the HII and
210/// drivers. Only drivers which provide IFR data to HII are required
211/// to publish this protocol.
212///
213struct _EFI_HII_CONFIG_ACCESS_PROTOCOL {
214  EFI_HII_ACCESS_EXTRACT_CONFIG     ExtractConfig;
215  EFI_HII_ACCESS_ROUTE_CONFIG       RouteConfig;
216  EFI_HII_ACCESS_FORM_CALLBACK      Callback;
217} ;
218
219extern EFI_GUID gEfiHiiConfigAccessProtocolGuid;
220
221#endif
222
223
224