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