1 /*++ 2 3 Copyright (c) 2007, Intel Corporation. All rights reserved.<BR> 4 This program and the accompanying materials 5 are licensed and made available under the terms and conditions of the BSD License 6 which accompanies this distribution. The full text of the license may be found at 7 http://opensource.org/licenses/bsd-license.php 8 9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 11 12 Module Name: 13 14 HiiConfigRouting.h 15 16 Abstract: 17 18 EFI_HII_CONFIG_ROUTING_PROTOCOL as defined in UEFI 2.1 spec. 19 20 --*/ 21 22 #ifndef __EFI_HII_CONFIG_ROUTING_H__ 23 #define __EFI_HII_CONFIG_ROUTING_H__ 24 25 #include "EfiHii.h" 26 27 #define EFI_HII_CONFIG_ROUTING_PROTOCOL_GUID \ 28 { \ 29 0x587e72d7, 0xcc50, 0x4f79, {0x82, 0x09, 0xca, 0x29, 0x1f, 0xc1, 0xa1, 0x0f} \ 30 } 31 32 // 33 // Forward reference for pure ANSI compatability 34 // 35 EFI_FORWARD_DECLARATION (EFI_HII_CONFIG_ROUTING_PROTOCOL); 36 37 typedef 38 EFI_STATUS 39 (EFIAPI *EFI_HII_EXTRACT_CONFIG) ( 40 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, 41 IN CONST EFI_STRING Request, 42 OUT EFI_STRING *Progress, 43 OUT EFI_STRING *Results 44 ) 45 /*++ 46 47 Routine Description: 48 This function allows a caller to extract the current configuration 49 for one or more named elements from one or more drivers. 50 51 Arguments: 52 This - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. 53 Request - A null-terminated Unicode string in <MultiConfigRequest> format. 54 Progress - On return, points to a character in the Request string. Points to the string's null 55 terminator if request was successful. Points to the most recent '&' before the first 56 failing name / value pair (or the beginning of the string if the failure is in the first 57 name / value pair) if the request was not successful. 58 Results - Null-terminated Unicode string in <MultiConfigAltResp> format which has all 59 values filled in for the names in the Request string. String to be allocated by the called 60 function. 61 62 Returns: 63 EFI_SUCCESS - The Results string is filled with the values 64 corresponding to all requested names. 65 EFI_OUT_OF_RESOURCES - Not enough memory to store the parts of the results 66 that must be stored awaiting possible future 67 protocols. 68 EFI_NOT_FOUND - Routing data doesn't match any known driver. 69 Progress set to the 'G' in "GUID" of the routing 70 header that doesn't match. Note: There is no 71 requirement that all routing data be validated before 72 any configuration extraction. 73 EFI_INVALID_PARAMETER - For example, passing in a NULL for the Request 74 parameter would result in this type of error. The 75 Progress parameter is set to NULL. 76 77 EFI_INVALID_PARAMETER - Illegal syntax. Progress set to most recent & before 78 the error or the beginning of the string. 79 80 EFI_INVALID_PARAMETER - Unknown name. Progress points to the & before 81 the name in question. 82 83 --*/ 84 ; 85 86 typedef 87 EFI_STATUS 88 (EFIAPI *EFI_HII_EXPORT_CONFIG) ( 89 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, 90 OUT EFI_STRING *Results 91 ) 92 /*++ 93 94 Routine Description: 95 This function allows the caller to request the current configuration for the 96 entirety of the current HII database and returns the data in a null-terminated Unicode string. 97 98 Arguments: 99 This - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. 100 Results - Null-terminated Unicode string in <MultiConfigAltResp> format which has all 101 values filled in for the names in the Request string. String to be allocated by the called 102 function. De-allocation is up to the caller. 103 104 Returns: 105 EFI_SUCCESS - The Results string is filled with the values 106 corresponding to all requested names. 107 EFI_OUT_OF_RESOURCES - Not enough memory to store the parts of the results 108 that must be stored awaiting possible future 109 protocols. 110 EFI_INVALID_PARAMETER - For example, passing in a NULL for the Results 111 parameter would result in this type of error. 112 113 --*/ 114 ; 115 116 typedef 117 EFI_STATUS 118 (EFIAPI *EFI_HII_ROUTE_CONFIG) ( 119 IN EFI_HII_CONFIG_ROUTING_PROTOCOL *This, 120 IN CONST EFI_STRING Configuration, 121 OUT EFI_STRING *Progress 122 ) 123 /*++ 124 125 Routine Description: 126 This function processes the results of processing forms and routes it to the 127 appropriate handlers or storage. 128 129 Arguments: 130 This - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. 131 Configuration - A null-terminated Unicode string in <MulltiConfigResp> format. 132 Progress - A pointer to a string filled in with the offset of the most recent "&" before the first 133 failing name / value pair (or the beginning of the string if the failure is in the first 134 name / value pair) or the terminating NULL if all was successful. 135 136 Returns: 137 EFI_SUCCESS - The results have been distributed or are awaiting 138 distribution. 139 EFI_OUT_OF_RESOURCES - Not enough memory to store the parts of the results 140 that must be stored awaiting possible future 141 protocols. 142 EFI_INVALID_PARAMETER - Passing in a NULL for the Configuration 143 parameter would result in this type of error. 144 EFI_NOT_FOUND - Target for the specified routing data was not found. 145 146 --*/ 147 ; 148 149 150 typedef 151 EFI_STATUS 152 (EFIAPI *EFI_HII_BLOCK_TO_CONFIG) ( 153 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, 154 IN CONST EFI_STRING ConfigRequest, 155 IN CONST UINT8 *Block, 156 IN CONST UINTN BlockSize, 157 OUT EFI_STRING *Config, 158 OUT EFI_STRING *Progress 159 ) 160 /*++ 161 162 Routine Description: 163 This helper function is to be called by drivers to map configuration data stored 164 in byte array ("block") formats such as UEFI Variables into current configuration strings. 165 166 Arguments: 167 This - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. 168 ConfigRequest - A null-terminated Unicode string in <ConfigRequest> format. 169 Block - Array of bytes defining the block's configuration. 170 BlockSize - Length in bytes of Block. 171 Config - Filled-in configuration string. String allocated by the function. 172 Returned only if call is successful. 173 Progress - A pointer to a string filled in with the offset of the most recent "&" before the first 174 failing name / value pair (or the beginning of the string if the failure is in the first 175 name / value pair) or the terminating NULL if all was successful. 176 177 Returns: 178 EFI_SUCCESS - The request succeeded. Progress points to the null 179 terminator at the end of the ConfigRequest 180 string. 181 EFI_OUT_OF_RESOURCES - Not enough memory to allocate Config. 182 Progress points to the first character of 183 ConfigRequest. 184 EFI_INVALID_PARAMETER - Passing in a NULL for the ConfigRequest or 185 Block parameter would result in this type of 186 error. Progress points to the first character of 187 ConfigRequest. 188 EFI_NOT_FOUND - Target for the specified routing data was not found. 189 Progress points to the "G" in "GUID" of the 190 errant routing data. 191 EFI_DEVICE_ERROR - Block not large enough. Progress undefined. 192 EFI_INVALID_PARAMETER - Encountered non <BlockName> formatted string. 193 Block is left updated and Progress points at the "&" 194 preceding the first non-<BlockName>. 195 196 --*/ 197 ; 198 199 typedef 200 EFI_STATUS 201 (EFIAPI *EFI_HII_CONFIG_TO_BLOCK) ( 202 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, 203 IN CONST EFI_STRING ConfigResp, 204 IN OUT UINT8 *Block, 205 IN OUT UINTN *BlockSize, 206 OUT EFI_STRING *Progress 207 ) 208 /*++ 209 210 Routine Description: 211 This helper function is to be called by drivers to map configuration strings 212 to configurations stored in byte array ("block") formats such as UEFI Variables. 213 214 Arguments: 215 This - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. 216 ConfigResp - A null-terminated Unicode string in <ConfigResp> format. 217 Block - A possibly null array of bytes representing the current block. 218 Only bytes referenced in the ConfigResp string in the block are modified. 219 If this parameter is null or if the *BlockSize parameter is (on input) 220 shorter than required by the Configuration string, only the BlockSize 221 parameter is updated and an appropriate status (see below) is returned. 222 223 BlockSize - The length of the Block in units of UINT8. On input, this is the size of the Block. 224 On output, if successful, contains the index of the last modified byte in the Block. 225 226 Progress - On return, points to an element of the ConfigResp string filled in with the offset of 227 the most recent "&" before the first failing name / value pair (or the beginning of the 228 string if the failure is in the first name / value pair) or the terminating NULL if all was 229 successful. 230 Returns: 231 EFI_SUCCESS - The request succeeded. Progress points to the null 232 terminator at the end of the ConfigResp 233 string. 234 EFI_OUT_OF_RESOURCES - Not enough memory to allocate Config. 235 Progress points to the first character of 236 ConfigResp. 237 EFI_INVALID_PARAMETER - Passing in a NULL for the ConfigResp or 238 Block parameter would result in this type of error. 239 Progress points to the first character of 240 ConfigResp. 241 EFI_NOT_FOUND - Target for the specified routing data was not found. 242 Progress points to the "G" in "GUID" of the 243 errant routing data. 244 EFI_INVALID_PARAMETER - Encountered non <BlockName> formatted name / 245 value pair. Block is left updated and 246 Progress points at the "&" preceding the first 247 non-<BlockName>. 248 249 --*/ 250 ; 251 252 typedef 253 EFI_STATUS 254 (EFIAPI * EFI_HII_GET_ALT_CFG) ( 255 IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, 256 IN CONST EFI_STRING Configuration, 257 IN CONST EFI_GUID *Guid, 258 IN CONST EFI_STRING Name, 259 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, 260 IN CONST UINT16 *AltCfgId, 261 OUT EFI_STRING *AltCfgResp 262 ) 263 /*++ 264 265 Routine Description: 266 This helper function is to be called by drivers to extract portions of 267 a larger configuration string. 268 269 Arguments: 270 This - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. 271 Configuration - A null-terminated Unicode string in <MultiConfigAltResp> format. 272 Guid - A pointer to the GUID value to search for in the 273 routing portion of the ConfigResp string when retrieving 274 the requested data. If Guid is NULL, then all GUID 275 values will be searched for. 276 Name - A pointer to the NAME value to search for in the 277 routing portion of the ConfigResp string when retrieving 278 the requested data. If Name is NULL, then all Name 279 values will be searched for. 280 DevicePath - A pointer to the PATH value to search for in the 281 routing portion of the ConfigResp string when retrieving 282 the requested data. If DevicePath is NULL, then all 283 DevicePath values will be searched for. 284 AltCfgId - A pointer to the ALTCFG value to search for in the 285 routing portion of the ConfigResp string when retrieving 286 the requested data. If this parameter is NULL, 287 then the current setting will be retrieved. 288 AltCfgResp - A pointer to a buffer which will be allocated by the 289 function which contains the retrieved string as requested. 290 This buffer is only allocated if the call was successful. 291 292 Returns: 293 EFI_SUCCESS - The request succeeded. The requested data was extracted 294 and placed in the newly allocated AltCfgResp buffer. 295 EFI_OUT_OF_RESOURCES - Not enough memory to allocate AltCfgResp. 296 EFI_INVALID_PARAMETER - Any parameter is invalid. 297 EFI_NOT_FOUND - Target for the specified routing data was not found. 298 299 --*/ 300 ; 301 302 303 struct _EFI_HII_CONFIG_ROUTING_PROTOCOL { 304 EFI_HII_EXTRACT_CONFIG ExtractConfig; 305 EFI_HII_EXPORT_CONFIG ExportConfig; 306 EFI_HII_ROUTE_CONFIG RouteConfig; 307 EFI_HII_BLOCK_TO_CONFIG BlockToConfig; 308 EFI_HII_CONFIG_TO_BLOCK ConfigToBlock; 309 EFI_HII_GET_ALT_CFG GetAltConfig; 310 }; 311 312 extern EFI_GUID gEfiHiiConfigRoutingProtocolGuid; 313 314 #endif 315
