1 /** @file 2 The file provides the mechanism to set and get the values 3 associated with a keyword exposed through a x-UEFI- prefixed 4 configuration language namespace. 5 6 Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR> 7 This program and the accompanying materials are licensed and made available under 8 the terms and conditions of the BSD License that accompanies this distribution. 9 The full text of the license may be found at 10 http://opensource.org/licenses/bsd-license.php. 11 12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 14 15 **/ 16 17 #ifndef __EFI_CONFIG_KEYWORD_HANDLER_H__ 18 #define __EFI_CONFIG_KEYWORD_HANDLER_H__ 19 20 #define EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL_GUID \ 21 { \ 22 0x0a8badd5, 0x03b8, 0x4d19, {0xb1, 0x28, 0x7b, 0x8f, 0x0e, 0xda, 0xa5, 0x96 } \ 23 } 24 25 //*********************************************************** 26 // Progress Errors 27 //*********************************************************** 28 #define KEYWORD_HANDLER_NO_ERROR 0x00000000 29 #define KEYWORD_HANDLER_NAMESPACE_ID_NOT_FOUND 0x00000001 30 #define KEYWORD_HANDLER_MALFORMED_STRING 0x00000002 31 #define KEYWORD_HANDLER_KEYWORD_NOT_FOUND 0x00000004 32 #define KEYWORD_HANDLER_INCOMPATIBLE_VALUE_DETECTED 0x00000008 33 #define KEYWORD_HANDLER_ACCESS_NOT_PERMITTED 0x00000010 34 #define KEYWORD_HANDLER_UNDEFINED_PROCESSING_ERROR 0x80000000 35 36 typedef struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL; 37 38 /** 39 40 This function accepts a <MultiKeywordResp> formatted string, finds the associated 41 keyword owners, creates a <MultiConfigResp> string from it and forwards it to the 42 EFI_HII_ROUTING_PROTOCOL.RouteConfig function. 43 44 If there is an issue in resolving the contents of the KeywordString, then the 45 function returns an error and also sets the Progress and ProgressErr with the 46 appropriate information about where the issue occurred and additional data about 47 the nature of the issue. 48 49 In the case when KeywordString containing multiple keywords, when an EFI_NOT_FOUND 50 error is generated during processing the second or later keyword element, the system 51 storage associated with earlier keywords is not modified. All elements of the 52 KeywordString must successfully pass all tests for format and access prior to making 53 any modifications to storage. 54 55 In the case when EFI_DEVICE_ERROR is returned from the processing of a KeywordString 56 containing multiple keywords, the state of storage associated with earlier keywords 57 is undefined. 58 59 60 @param This Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance. 61 62 @param KeywordString A null-terminated string in <MultiKeywordResp> format. 63 64 @param Progress On return, points to a character in the KeywordString. 65 Points to the string's NULL terminator if the request 66 was successful. Points to the most recent '&' before 67 the first failing name / value pair (or the beginning 68 of the string if the failure is in the first name / value 69 pair) if the request was not successful. 70 71 @param ProgressErr If during the processing of the KeywordString there was 72 a failure, this parameter gives additional information 73 about the possible source of the problem. The various 74 errors are defined in "Related Definitions" below. 75 76 77 @retval EFI_SUCCESS The specified action was completed successfully. 78 79 @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: 80 1. KeywordString is NULL. 81 2. Parsing of the KeywordString resulted in an 82 error. See Progress and ProgressErr for more data. 83 84 @retval EFI_NOT_FOUND An element of the KeywordString was not found. 85 See ProgressErr for more data. 86 87 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. 88 See ProgressErr for more data. 89 90 @retval EFI_ACCESS_DENIED The action violated system policy. See ProgressErr 91 for more data. 92 93 @retval EFI_DEVICE_ERROR An unexpected system error occurred. See ProgressErr 94 for more data. 95 96 **/ 97 typedef 98 EFI_STATUS 99 (EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_SET_DATA) ( 100 IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL *This, 101 IN CONST EFI_STRING KeywordString, 102 OUT EFI_STRING *Progress, 103 OUT UINT32 *ProgressErr 104 ); 105 106 107 /** 108 109 This function accepts a <MultiKeywordRequest> formatted string, finds the underlying 110 keyword owners, creates a <MultiConfigRequest> string from it and forwards it to the 111 EFI_HII_ROUTING_PROTOCOL.ExtractConfig function. 112 113 If there is an issue in resolving the contents of the KeywordString, then the function 114 returns an EFI_INVALID_PARAMETER and also set the Progress and ProgressErr with the 115 appropriate information about where the issue occurred and additional data about the 116 nature of the issue. 117 118 In the case when KeywordString is NULL, or contains multiple keywords, or when 119 EFI_NOT_FOUND is generated while processing the keyword elements, the Results string 120 contains values returned for all keywords processed prior to the keyword generating the 121 error but no values for the keyword with error or any following keywords. 122 123 124 @param This Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance. 125 126 @param NameSpaceId A null-terminated string containing the platform configuration 127 language to search through in the system. If a NULL is passed 128 in, then it is assumed that any platform configuration language 129 with the prefix of "x-UEFI-" are searched. 130 131 @param KeywordString A null-terminated string in <MultiKeywordRequest> format. If a 132 NULL is passed in the KeywordString field, all of the known 133 keywords in the system for the NameSpaceId specified are 134 returned in the Results field. 135 136 @param Progress On return, points to a character in the KeywordString. Points 137 to the string's NULL terminator if the request was successful. 138 Points to the most recent '&' before the first failing name / value 139 pair (or the beginning of the string if the failure is in the first 140 name / value pair) if the request was not successful. 141 142 @param ProgressErr If during the processing of the KeywordString there was a 143 failure, this parameter gives additional information about the 144 possible source of the problem. See the definitions in SetData() 145 for valid value definitions. 146 147 @param Results A null-terminated string in <MultiKeywordResp> format is returned 148 which has all the values filled in for the keywords in the 149 KeywordString. This is a callee-allocated field, and must be freed 150 by the caller after being used. 151 152 @retval EFI_SUCCESS The specified action was completed successfully. 153 154 @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: 155 1.Progress, ProgressErr, or Results is NULL. 156 2.Parsing of the KeywordString resulted in an error. See 157 Progress and ProgressErr for more data. 158 159 160 @retval EFI_NOT_FOUND An element of the KeywordString was not found. See 161 ProgressErr for more data. 162 163 @retval EFI_NOT_FOUND The NamespaceId specified was not found. See ProgressErr 164 for more data. 165 166 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. See 167 ProgressErr for more data. 168 169 @retval EFI_ACCESS_DENIED The action violated system policy. See ProgressErr for 170 more data. 171 172 @retval EFI_DEVICE_ERROR An unexpected system error occurred. See ProgressErr 173 for more data. 174 175 **/ 176 typedef 177 EFI_STATUS 178 (EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_GET_DATA) ( 179 IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL *This, 180 IN CONST EFI_STRING NameSpaceId, OPTIONAL 181 IN CONST EFI_STRING KeywordString, OPTIONAL 182 OUT EFI_STRING *Progress, 183 OUT UINT32 *ProgressErr, 184 OUT EFI_STRING *Results 185 ); 186 187 /// 188 /// The EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL provides the mechanism 189 /// to set and get the values associated with a keyword exposed 190 /// through a x-UEFI- prefixed configuration language namespace 191 /// 192 193 struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL { 194 EFI_CONFIG_KEYWORD_HANDLER_SET_DATA SetData; 195 EFI_CONFIG_KEYWORD_HANDLER_GET_DATA GetData; 196 }; 197 198 extern EFI_GUID gEfiConfigKeywordHandlerProtocolGuid; 199 200 #endif 201 202