add a error macro to prevent this file from included for now #error "UEFI 2.1 HII...
[mirror_edk2.git] / MdePkg / Include / Protocol / HiiConfigRouting.h
1 /** @file
2 The file provides services to manage the movement of
3 configuration data from drivers to configuration applications.
4 It then serves as the single point to receive configuration
5 information from configuration applications, routing the
6 results to the appropriate drivers.
7
8 Copyright (c) 2006 - 2007, Intel Corporation
9 All rights reserved. This program and the accompanying materials
10 are licensed and made available under the terms and conditions of the BSD License
11 which accompanies this distribution. The full text of the license may be found at
12 http://opensource.org/licenses/bsd-license.php
13
14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16
17 **/
18
19 #ifndef __HII_CONFIG_ROUTING_H__
20 #define __HII_CONFIG_ROUTING_H__
21
22 #error "UEFI 2.1 HII is not fully implemented for now, Please don't include this file now."
23
24 #define EFI_HII_CONFIG_ROUTING_PROTOCOL_GUID \
25 { 0x587e72d7, 0xcc50, 0x4f79, { 0x82, 0x09, 0xca, 0x29, 0x1f, 0xc1, 0xa1, 0x0f } }
26
27
28 typedef struct _EFI_HII_CONFIG_ROUTING_PROTOCOL EFI_HII_CONFIG_ROUTING_PROTOCOL;
29
30
31 /**
32
33 This function allows the caller to request the current
34 configuration for one or more named elements from one or more
35 drivers. The resulting string is in the standard HII
36 configuration string format. If Successful Results contains an
37 equivalent string with "=" and the values associated with all
38 names added in. The expected implementation is for each
39 <ConfigRequest> substring in the Request, call the HII
40 Configuration Routing Protocol ExtractProtocol function for the
41 driver corresponding to the <ConfigHdr> at the start of the
42 <ConfigRequest> substring. The request fails if no driver
43 matches the <ConfigRequest> substring. Note: Alternative
44 configuration strings may also be appended to the end of the
45 current configuration string. If they are, they must appear
46 after the current configuration. They must contain the same
47 routing (GUID, NAME, PATH) as the current configuration string.
48 They must have an additional description indicating the type of
49 alternative configuration the string represents,
50 "ALTCFG=<StringToken>". That <StringToken> (when converted from
51 Hex UNICODE to binary) is a reference to a string in the
52 associated string pack. As an example, assume that the Request
53 string is:
54 GUID=...&NAME=00480050&PATH=...&Fred&George&Ron&Neville A result
55 might be:
56 GUID=...&NAME=00480050&PATH=...&Fred=16&George=16&Ron=12&Neville=11&
57 GUID=...&NAME=00480050&PATH=...&ALTCFG=0037&Fred=12&Neville=7
58
59 @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL
60 instance.
61
62 @param Request A null-terminated Unicode string in
63 <MultiConfigRequest> format.
64
65 @param Progress On return, points to a character in the
66 Request string. Points to the string's null
67 terminator if request was successful. Points
68 to the most recent '&' before the first
69 failing name / value pair (or the beginning
70 of the string if the failure is in the first
71 name / value pair) if the request was not
72 successful
73
74 @param Results Null-terminated Unicode string in
75 <MultiConfigAltResp> format which has all
76 values filled in for the names in the
77 Request string. String to be allocated by
78 the called function.
79
80 @retval EFI_SUCCESS The Results string is filled with the
81 values corresponding to all requested
82 names.
83
84 @retval EFI_OUT_OF_MEMORY Not enough memory to store the
85 parts of the results that must be
86 stored awaiting possible future
87 protocols.
88
89 @retval EFI_INVALID_PARAMETER For example, passing in a NULL
90 for the Request parameter
91 would result in this type of
92 error. The Progress parameter
93 is set to NULL. EFI_NOT_FOUND
94 Routing data doesn't match any
95 known driver. Progress set to
96 the "G" in "GUID" of the
97 routing header that doesn't
98 match. Note: There is no
99 requirement that all routing
100 data be validated before any
101 configuration extraction.
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 @retval EFI_INVALID_PARAMETER Unknown name.
108
109
110 **/
111 typedef
112 EFI_STATUS
113 (EFIAPI * EFI_HII_ROUTING_EXTRACT_CONFIG ) (
114 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
115 IN CONST EFI_STRING *Request,
116 OUT EFI_STRING *Progress,
117 OUT EFI_STRING *Results
118 );
119
120 /**
121
122 This function allows the caller to request the current
123 configuration for all of the current HII database. The results
124 include both the current and alternate configurations as
125 described in ExtractConfig() above. Implementation note: This
126 call has deceptively few inputs but the implementation is likely
127 to be somewhat complex. The requirement is to scan all IFR in
128 the HII database to determine the list of names and then request
129 the configuration using the corresponding drivers??
130 EFI_HII_CONFIG_ACCESS_PROTOCOL.ExtractConfig() interfaces below.
131
132 @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL
133 instance.
134
135 @param Results A null-terminated Unicode string in
136 <MultiConfigAltResp> format which has all
137 values filled in for the names in the Request
138 string. String to be allocated by this
139 function. De-allocation is up to the caller.
140
141 @retval EFI_SUCCESS The Results string is filled with the
142 values corresponding to all requested
143 names.
144
145 @retval EFI_OUT_OF_MEMORY Not enough memory to store the
146 parts of the results that must be
147 stored awaiting possible future
148 protocols.
149
150 @retval EFI_INVALID_PARAMETERS For example, passing in a NULL
151 for the Results parameter
152 would result in this type of
153 error.
154
155 **/
156 typedef
157 EFI_STATUS
158 (EFIAPI * EFI_HII_ROUTING_EXPORT_CONFIG ) (
159 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
160 OUT EFI_STRING *Results
161 );
162
163 /**
164
165 This function routes the results of processing forms to the
166 appropriate targets. It scans for <ConfigHdr> within the string
167 and passes the header and subsequent body to the driver whose
168 location is described in the <ConfigHdr>. Many <ConfigHdr>s may
169 appear as a single request. The expected implementation is to
170 hand off the various <ConfigResp> substrings to the
171 Configuration Access Protocol RouteConfig routine corresponding
172 to the driver whose routing information is defined by the
173 <ConfigHdr> in turn.
174
175 @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL
176 instance.
177
178 @param Configuration A null-terminated Unicode string in
179 <MulltiConfigResp> format.
180
181 @param Progress A pointer to a string filled in with the
182 offset of the most recent '&' before the
183 first failing name / value pair (or the
184 beginning of the string if the failure is in
185 the first name / value pair) or the
186 terminating NULL if all was successful.
187
188 @retval EFI_SUCCESS The results have been distributed or are
189 awaiting distribution.
190
191 @retval EFI_OUT_OF_MEMORY Not enough memory to store the
192 parts of the results that must be
193 stored awaiting possible future
194 protocols.
195
196 @retval EFI_INVALID_PARAMETERS Passing in a NULL for the
197 Results parameter would result
198 in this type of error.
199
200 @retval EFI_NOT_FOUND Target for the specified routing data
201 was not found
202
203 **/
204 typedef
205 EFI_STATUS
206 (EFIAPI * EFI_HII_ROUTING_ROUTE_CONFIG ) (
207 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
208 IN CONST EFI_STRING Configuration,
209 OUT EFI_STRING *Progress
210 );
211
212
213 /**
214
215 This function extracts the current configuration from a block of
216 bytes. To do so, it requires that the ConfigRequest string
217 consists of a list of <BlockName> formatted names. It uses the
218 offset in the name to determine the index into the Block to
219 start the extraction and the width of each name to determine the
220 number of bytes to extract. These are mapped to a UNICODE value
221 using the equivalent of the C "%x" format (with optional leading
222 spaces). The call fails if, for any (offset, width) pair in
223 ConfigRequest, offset+value >= BlockSize.
224
225 @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL
226 instance.
227
228 @param ConfigRequest A null-terminated Unicode string in
229 <ConfigRequest> format.
230
231 @param Block Array of bytes defining the block's
232 configuration.
233
234 @param BlockSize Length in bytes of Block.
235
236 @param Config Filled-in configuration string. String
237 allocated by the function. Returned only if
238 call is successful.
239
240 @param Progress A pointer to a string filled in with the
241 offset of the most recent '&' before the
242 first failing name / value pair (or the
243 beginning of the string if the failure is in
244 the first name / value pair) or the
245 terminating NULL if all was successful.
246
247 @retval EFI_SUCCESS The request succeeded. Progress points
248 to the null terminator at the end of the
249 ConfigRequest string.
250 @retval EFI_OUT_OF_MEMORY Not enough memory to allocate
251 Config. Progress points to the
252 first character of ConfigRequest.
253
254 @retval EFI_INVALID_PARAMETERS Passing in a NULL for the
255 ConfigRequest or Block
256 parameter would result in this
257 type of error. Progress points
258 to the first character of
259 ConfigRequest.
260
261 @retval EFI_NOT_FOUND Target for the specified routing data
262 was not found. Progress points to the
263 'G' in "GUID" of the errant routing
264 data. EFI_DEVICE_ERROR Block not large
265 enough. Progress undefined.
266
267 @retval EFI_INVALID_PARAMETER Encountered non <BlockName>
268 formatted string. Block is
269 left updated and Progress
270 points at the '&' preceding
271 the first non-<BlockName>.
272
273 **/
274 typedef
275 EFI_STATUS
276 (EFIAPI * EFI_HII_ROUTING_BLOCK_TO_CONFIG ) (
277 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
278 IN CONST EFI_STRING ConfigRequest,
279 IN CONST UINT8 *Block,
280 IN CONST UINTN BlockSize,
281 OUT EFI_STRING **Config,
282 OUT EFI_STRING *Progress
283 );
284
285
286
287 /**
288
289 This function maps a configuration containing a series of
290 <BlockConfig> formatted name value pairs in ConfigResp into a
291 Block so it may be stored in a linear mapped storage such as a
292 UEFI Variable. If present, the function skips GUID, NAME, and
293 PATH in <ConfigResp>. It stops when it finds a non-<BlockConfig>
294 name / value pair (after skipping the routing header) or when it
295 reaches the end of the string.
296 Example Assume an existing block containing: 00 01 02 03 04 05
297 And the ConfigResp string is:
298 OFFSET=4&WIDTH=1&VALUE=7&OFFSET=0&WIDTH=2&VALUE=AA55
299 The results are
300 55 AA 02 07 04 05
301
302 @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL
303 instance.
304
305 @param ConfigResp A null-terminated Unicode string in
306 <ConfigResp> format.
307
308 @param CurrentBlock A possibly null array of bytes
309 representing the current block. Only
310 bytes referenced in the ConfigResp
311 string in the block are modified. If
312 this parameter is null or if the
313 BlockLength parameter is (on input)
314 shorter than required by the
315 Configuration string, only the BlockSize
316 parameter is updated and an appropriate
317 status (see below) is returned.
318
319 @param BlockSize The length of the Block in units of UINT8.
320 On input, this is the size of the Block. On
321 output, if successful, contains the index of
322 the last modified byte in the Block.
323
324 @param Progress On return, points to an element of the
325 ConfigResp string filled in with the offset
326 of the most recent "&" before the first
327 failing name / value pair (or the beginning
328 of the string if the failure is in the first
329 name / value pair) or the terminating NULL
330 if all was successful.
331
332 **/
333 typedef
334 EFI_STATUS
335 (EFIAPI * EFI_HII_ROUTING_CONFIG_TO_BLOCK ) (
336 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
337 IN CONST EFI_STRING *ConfigResp,
338 IN CONST UINT8 *Block,
339 IN OUT UINTN *BlockSize,
340 OUT EFI_STRING *Progress
341 );
342
343
344 /**
345
346 This protocol defines the configuration routing interfaces
347 between external applications and the HII. There may only be one
348 instance of this protocol in the system.
349
350 **/
351 struct _EFI_HII_CONFIG_ROUTING_PROTOCOL {
352 EFI_HII_ROUTING_EXTRACT_CONFIG ExtractConfig;
353 EFI_HII_ROUTING_EXPORT_CONFIG ExportConfig;
354 EFI_HII_ROUTING_ROUTE_CONFIG RouteConfig;
355 EFI_HII_ROUTING_BLOCK_TO_CONFIG BlockToConfig;
356 EFI_HII_ROUTING_CONFIG_TO_BLOCK ConfigToBlock;
357 };
358
359 extern EFI_GUID gEfiHiiConfigRoutingProtocolGuid;
360
361
362 #endif
363