]> git.proxmox.com Git - mirror_edk2.git/blame - MdePkg/Include/Protocol/HiiConfigRouting.h
Clarify some definitions in HII Configure Routine Protocol
[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
c8c44377 8 Copyright (c) 2006 - 2009, Intel Corporation\r
d1f95000 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
22#define EFI_HII_CONFIG_ROUTING_PROTOCOL_GUID \\r
23 { 0x587e72d7, 0xcc50, 0x4f79, { 0x82, 0x09, 0xca, 0x29, 0x1f, 0xc1, 0xa1, 0x0f } }\r
24\r
25\r
26typedef struct _EFI_HII_CONFIG_ROUTING_PROTOCOL EFI_HII_CONFIG_ROUTING_PROTOCOL;\r
27\r
d1f95000 28/**\r
29 \r
30 This function allows the caller to request the current\r
31 configuration for one or more named elements from one or more\r
32 drivers. The resulting string is in the standard HII\r
33 configuration string format. If Successful Results contains an\r
34 equivalent string with "=" and the values associated with all\r
35 names added in. The expected implementation is for each\r
36 <ConfigRequest> substring in the Request, call the HII\r
37 Configuration Routing Protocol ExtractProtocol function for the\r
38 driver corresponding to the <ConfigHdr> at the start of the\r
39 <ConfigRequest> substring. The request fails if no driver\r
40 matches the <ConfigRequest> substring. Note: Alternative\r
41 configuration strings may also be appended to the end of the\r
42 current configuration string. If they are, they must appear\r
43 after the current configuration. They must contain the same\r
44 routing (GUID, NAME, PATH) as the current configuration string.\r
45 They must have an additional description indicating the type of\r
46 alternative configuration the string represents,\r
47 "ALTCFG=<StringToken>". That <StringToken> (when converted from\r
48 Hex UNICODE to binary) is a reference to a string in the\r
49 associated string pack. As an example, assume that the Request\r
50 string is:\r
51 GUID=...&NAME=00480050&PATH=...&Fred&George&Ron&Neville A result\r
52 might be:\r
53 GUID=...&NAME=00480050&PATH=...&Fred=16&George=16&Ron=12&Neville=11&\r
54 GUID=...&NAME=00480050&PATH=...&ALTCFG=0037&Fred=12&Neville=7\r
55\r
4ca9b6c4
LG
56 @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL\r
57 instance.\r
d1f95000 58\r
29c18ab5 59 @param Request A null-terminated string in <MultiConfigRequest>\r
60 format. If a NULL is passed in for the Request field,\r
61 all of the settings being abstracted by this function\r
62 will be returned in the Results field.\r
d1f95000 63\r
64 @param Progress On return, points to a character in the\r
65 Request string. Points to the string's null\r
66 terminator if request was successful. Points\r
67 to the most recent '&' before the first\r
68 failing name / value pair (or the beginning\r
69 of the string if the failure is in the first\r
70 name / value pair) if the request was not\r
71 successful\r
72\r
29c18ab5 73 @param Results A null-terminated string in <ConfigAltResp> format\r
74 which has all values filled in for the names in the\r
75 Request string. If the Request string was NULL, the data\r
76 returned is in <MultiConfigAltResp> format. String to be\r
77 allocated by the called function.\r
d1f95000 78\r
4ca9b6c4
LG
79 @retval EFI_SUCCESS The Results string is filled with the\r
80 values corresponding to all requested\r
81 names.\r
d1f95000 82\r
e1f1fb16 83 @retval EFI_OUT_OF_RESOURCES Not enough memory to store the\r
4ca9b6c4
LG
84 parts of the results that must be\r
85 stored awaiting possible future\r
86 protocols.\r
d1f95000 87\r
88 @retval EFI_INVALID_PARAMETER For example, passing in a NULL\r
89 for the Request parameter\r
90 would result in this type of\r
91 error. The Progress parameter\r
630b4187 92 is set to NULL. \r
93 \r
94 @retval EFI_NOT_FOUND Routing data doesn't match any\r
d1f95000 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
c8c44377 113(EFIAPI * EFI_HII_EXTRACT_CONFIG)(\r
d1f95000 114 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
7d582d6b 115 IN CONST EFI_STRING Request,\r
d1f95000 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
29c18ab5 125 described in ExtractConfig() above. \r
d1f95000 126 \r
4ca9b6c4 127 @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.\r
d1f95000 128 \r
129 @param Results A null-terminated Unicode string in\r
130 <MultiConfigAltResp> format which has all\r
131 values filled in for the names in the Request\r
132 string. String to be allocated by this\r
133 function. De-allocation is up to the caller.\r
134 \r
4ca9b6c4
LG
135 @retval EFI_SUCCESS The Results string is filled with the\r
136 values corresponding to all requested\r
137 names.\r
d1f95000 138 \r
e1f1fb16 139 @retval EFI_OUT_OF_RESOURCES Not enough memory to store the\r
4ca9b6c4
LG
140 parts of the results that must be\r
141 stored awaiting possible future\r
142 protocols.\r
d1f95000 143 \r
144 @retval EFI_INVALID_PARAMETERS For example, passing in a NULL\r
145 for the Results parameter\r
146 would result in this type of\r
147 error.\r
148\r
149**/\r
150typedef\r
151EFI_STATUS\r
c8c44377 152(EFIAPI * EFI_HII_EXPORT_CONFIG)(\r
d1f95000 153 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
154 OUT EFI_STRING *Results\r
155);\r
156\r
157/**\r
158 \r
159 This function routes the results of processing forms to the\r
160 appropriate targets. It scans for <ConfigHdr> within the string\r
161 and passes the header and subsequent body to the driver whose\r
162 location is described in the <ConfigHdr>. Many <ConfigHdr>s may\r
163 appear as a single request. The expected implementation is to\r
164 hand off the various <ConfigResp> substrings to the\r
165 Configuration Access Protocol RouteConfig routine corresponding\r
166 to the driver whose routing information is defined by the\r
167 <ConfigHdr> in turn.\r
168\r
4ca9b6c4 169 @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.\r
d1f95000 170\r
171 @param Configuration A null-terminated Unicode string in\r
172 <MulltiConfigResp> format.\r
173\r
4ca9b6c4
LG
174 @param Progress A pointer to a string filled in with the\r
175 offset of the most recent '&' before the\r
176 first failing name / value pair (or the\r
177 beginning of the string if the failure is in\r
178 the first name / value pair) or the\r
179 terminating NULL if all was successful.\r
d1f95000 180\r
4ca9b6c4
LG
181 @retval EFI_SUCCESS The results have been distributed or are\r
182 awaiting distribution.\r
d1f95000 183 \r
e1f1fb16 184 @retval EFI_OUT_OF_RESOURCES Not enough memory to store the\r
4ca9b6c4
LG
185 parts of the results that must be\r
186 stored awaiting possible future\r
187 protocols.\r
d1f95000 188 \r
189 @retval EFI_INVALID_PARAMETERS Passing in a NULL for the\r
190 Results parameter would result\r
191 in this type of error.\r
192 \r
4ca9b6c4
LG
193 @retval EFI_NOT_FOUND Target for the specified routing data\r
194 was not found\r
d1f95000 195\r
196**/\r
197typedef\r
198EFI_STATUS\r
c8c44377 199(EFIAPI * EFI_HII_ROUTE_CONFIG)(\r
d1f95000 200 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
201 IN CONST EFI_STRING Configuration,\r
202 OUT EFI_STRING *Progress\r
203);\r
204\r
205\r
206/**\r
207 \r
208 This function extracts the current configuration from a block of\r
209 bytes. To do so, it requires that the ConfigRequest string\r
210 consists of a list of <BlockName> formatted names. It uses the\r
211 offset in the name to determine the index into the Block to\r
212 start the extraction and the width of each name to determine the\r
213 number of bytes to extract. These are mapped to a UNICODE value\r
214 using the equivalent of the C "%x" format (with optional leading\r
215 spaces). The call fails if, for any (offset, width) pair in\r
216 ConfigRequest, offset+value >= BlockSize.\r
217\r
4ca9b6c4 218 @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.\r
d1f95000 219\r
220 @param ConfigRequest A null-terminated Unicode string in\r
221 <ConfigRequest> format.\r
222\r
4ca9b6c4
LG
223 @param Block Array of bytes defining the block's\r
224 configuration.\r
d1f95000 225\r
226 @param BlockSize Length in bytes of Block.\r
227\r
4ca9b6c4
LG
228 @param Config Filled-in configuration string. String\r
229 allocated by the function. Returned only if\r
230 call is successful.\r
d1f95000 231\r
232 @param Progress A pointer to a string filled in with the\r
233 offset of the most recent '&' before the\r
234 first failing name / value pair (or the\r
235 beginning of the string if the failure is in\r
236 the first name / value pair) or the\r
237 terminating NULL if all was successful.\r
238\r
4ca9b6c4
LG
239 @retval EFI_SUCCESS The request succeeded. Progress points\r
240 to the null terminator at the end of the\r
241 ConfigRequest string.\r
242\r
e1f1fb16 243 @retval EFI_OUT_OF_RESOURCES Not enough memory to allocate\r
4ca9b6c4
LG
244 Config. Progress points to the\r
245 first character of ConfigRequest.\r
d1f95000 246\r
247 @retval EFI_INVALID_PARAMETERS Passing in a NULL for the\r
248 ConfigRequest or Block\r
249 parameter would result in this\r
250 type of error. Progress points\r
251 to the first character of\r
252 ConfigRequest.\r
253\r
4ca9b6c4
LG
254 @retval EFI_NOT_FOUND Target for the specified routing data\r
255 was not found. Progress points to the\r
256 'G' in "GUID" of the errant routing\r
630b4187 257 data. \r
01a54966 258 @retval EFI_DEVICE_ERROR Block not large enough. Progress undefined.\r
d1f95000 259\r
260 @retval EFI_INVALID_PARAMETER Encountered non <BlockName>\r
261 formatted string. Block is\r
262 left updated and Progress\r
263 points at the '&' preceding\r
264 the first non-<BlockName>.\r
265\r
266**/\r
267typedef\r
268EFI_STATUS\r
c8c44377 269(EFIAPI * EFI_HII_BLOCK_TO_CONFIG)(\r
d1f95000 270 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
271 IN CONST EFI_STRING ConfigRequest,\r
272 IN CONST UINT8 *Block,\r
273 IN CONST UINTN BlockSize,\r
7d582d6b 274 OUT EFI_STRING *Config,\r
d1f95000 275 OUT EFI_STRING *Progress\r
276);\r
277\r
278\r
279\r
280/**\r
d1f95000 281 This function maps a configuration containing a series of\r
282 <BlockConfig> formatted name value pairs in ConfigResp into a\r
283 Block so it may be stored in a linear mapped storage such as a\r
284 UEFI Variable. If present, the function skips GUID, NAME, and\r
285 PATH in <ConfigResp>. It stops when it finds a non-<BlockConfig>\r
286 name / value pair (after skipping the routing header) or when it\r
287 reaches the end of the string.\r
288 Example Assume an existing block containing: 00 01 02 03 04 05\r
289 And the ConfigResp string is:\r
290 OFFSET=4&WIDTH=1&VALUE=7&OFFSET=0&WIDTH=2&VALUE=AA55\r
291 The results are\r
292 55 AA 02 07 04 05\r
293\r
4ca9b6c4 294 @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.\r
d1f95000 295\r
4ca9b6c4
LG
296 @param ConfigResp A null-terminated Unicode string in\r
297 <ConfigResp> format.\r
d1f95000 298\r
4ca9b6c4 299 @param Block A possibly null array of bytes\r
d1f95000 300 representing the current block. Only\r
301 bytes referenced in the ConfigResp\r
302 string in the block are modified. If\r
303 this parameter is null or if the\r
304 BlockLength parameter is (on input)\r
305 shorter than required by the\r
306 Configuration string, only the BlockSize\r
307 parameter is updated and an appropriate\r
308 status (see below) is returned.\r
309\r
4ca9b6c4
LG
310 @param BlockSize The length of the Block in units of UINT8.\r
311 On input, this is the size of the Block. On\r
312 output, if successful, contains the index of\r
313 the last modified byte in the Block.\r
314\r
315 @param Progress On return, points to an element of the\r
316 ConfigResp string filled in with the offset\r
317 of the most recent "&" before the first\r
318 failing name / value pair (or the beginning\r
319 of the string if the failure is in the first\r
320 name / value pair) or the terminating NULL\r
321 if all was successful.\r
322\r
323 @retval EFI_SUCCESS The request succeeded. Progress points to the null\r
324 terminator at the end of the ConfigResp string.\r
630b4187 325 @retval EFI_OUT_OF_RESOURCES Not enough memory to allocate Config. Progress\r
4ca9b6c4
LG
326 points to the first character of ConfigResp.\r
327 @retval EFI_INVALID_PARAMETER Passing in a NULL for the ConfigResp or\r
328 Block parameter would result in this type of\r
329 error. Progress points to the first character of\r
330 ConfigResp.\r
331 @retval EFI_INVALID_PARAMETER Encountered non <BlockName> formatted name /\r
332 value pair. Block is left updated and\r
333 Progress points at the '&' preceding the first\r
334 non-<BlockName>.\r
d1f95000 335\r
336**/\r
337typedef\r
338EFI_STATUS\r
c8c44377 339(EFIAPI * EFI_HII_CONFIG_TO_BLOCK)(\r
d1f95000 340 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,\r
7d582d6b 341 IN CONST EFI_STRING ConfigResp,\r
342 IN OUT UINT8 *Block,\r
d1f95000 343 IN OUT UINTN *BlockSize,\r
344 OUT EFI_STRING *Progress\r
345);\r
346\r
4ca9b6c4
LG
347/**\r
348 This helper function is to be called by drivers to extract portions of \r
349 a larger configuration string.\r
350 \r
351 @param This A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. \r
352 @param Configuration A null-terminated Unicode string in <MultiConfigAltResp> format.\r
353 @param Guid A pointer to the GUID value to search for in the \r
354 routing portion of the ConfigResp string when retrieving \r
355 the requested data. If Guid is NULL, then all GUID \r
356 values will be searched for.\r
357 @param Name A pointer to the NAME value to search for in the \r
358 routing portion of the ConfigResp string when retrieving \r
359 the requested data. If Name is NULL, then all Name \r
360 values will be searched for. \r
361 @param DevicePath A pointer to the PATH value to search for in the \r
362 routing portion of the ConfigResp string when retrieving \r
363 the requested data. If DevicePath is NULL, then all \r
364 DevicePath values will be searched for. \r
365 @param AltCfgId A pointer to the ALTCFG value to search for in the \r
366 routing portion of the ConfigResp string when retrieving \r
367 the requested data. If this parameter is NULL, \r
368 then the current setting will be retrieved.\r
369 @param AltCfgResp A pointer to a buffer which will be allocated by the \r
370 function which contains the retrieved string as requested. \r
371 This buffer is only allocated if the call was successful. \r
372 \r
373 @retval EFI_SUCCESS The request succeeded. The requested data was extracted \r
374 and placed in the newly allocated AltCfgResp buffer.\r
375 @retval EFI_OUT_OF_RESOURCES Not enough memory to allocate AltCfgResp. \r
376 @retval EFI_INVALID_PARAMETER Any parameter is invalid.\r
377 @retval EFI_NOT_FOUND Target for the specified routing data was not found.\r
378**/\r
7d582d6b 379typedef\r
380EFI_STATUS \r
8b13229b 381(EFIAPI * EFI_HII_GET_ALT_CFG)(\r
7d582d6b 382 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, \r
383 IN CONST EFI_STRING Configuration, \r
384 IN CONST EFI_GUID *Guid, \r
385 IN CONST EFI_STRING Name, \r
386 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, \r
387 IN CONST UINT16 *AltCfgId,\r
388 OUT EFI_STRING *AltCfgResp \r
ed66e1bc 389 );\r
7d582d6b 390\r
44717a39 391///\r
392/// This protocol defines the configuration routing interfaces\r
393/// between external applications and the HII. There may only be one\r
394/// instance of this protocol in the system.\r
395///\r
d1f95000 396struct _EFI_HII_CONFIG_ROUTING_PROTOCOL {\r
c8c44377 397 EFI_HII_EXTRACT_CONFIG ExtractConfig;\r
398 EFI_HII_EXPORT_CONFIG ExportConfig;\r
399 EFI_HII_ROUTE_CONFIG RouteConfig;\r
400 EFI_HII_BLOCK_TO_CONFIG BlockToConfig;\r
401 EFI_HII_CONFIG_TO_BLOCK ConfigToBlock;\r
f754f721 402 EFI_HII_GET_ALT_CFG GetAltConfig;\r
d1f95000 403};\r
404\r
405extern EFI_GUID gEfiHiiConfigRoutingProtocolGuid;\r
406\r
407\r
408#endif\r
409\r