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