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