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