]>
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 | |
2f88bd3a | 23 | // ***********************************************************\r |
5ca4bb9f | 24 | // Progress Errors\r |
2f88bd3a MK |
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 | |
5ca4bb9f ED |
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 | 96 | EFI_STATUS\r |
2f88bd3a | 97 | (EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_SET_DATA)(\r |
5ca4bb9f ED |
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 | |
5ca4bb9f ED |
104 | /**\r |
105 | \r | |
9095d37b | 106 | This function accepts a <MultiKeywordRequest> formatted string, finds the underlying\r |
5ca4bb9f ED |
107 | keyword owners, creates a <MultiConfigRequest> string from it and forwards it to the\r |
108 | EFI_HII_ROUTING_PROTOCOL.ExtractConfig function.\r | |
9095d37b | 109 | \r |
5ca4bb9f ED |
110 | If there is an issue in resolving the contents of the KeywordString, then the function\r |
111 | returns an EFI_INVALID_PARAMETER and also set the Progress and ProgressErr with the\r | |
112 | appropriate information about where the issue occurred and additional data about the\r | |
113 | nature of the issue.\r | |
9095d37b | 114 | \r |
5ca4bb9f ED |
115 | In the case when KeywordString is NULL, or contains multiple keywords, or when\r |
116 | EFI_NOT_FOUND is generated while processing the keyword elements, the Results string\r | |
9095d37b | 117 | contains values returned for all keywords processed prior to the keyword generating the\r |
5ca4bb9f ED |
118 | error but no values for the keyword with error or any following keywords.\r |
119 | \r | |
9095d37b | 120 | \r |
5ca4bb9f | 121 | @param This Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance.\r |
9095d37b | 122 | \r |
5ca4bb9f ED |
123 | @param NameSpaceId A null-terminated string containing the platform configuration\r |
124 | language to search through in the system. If a NULL is passed\r | |
125 | in, then it is assumed that any platform configuration language\r | |
126 | with the prefix of "x-UEFI-" are searched.\r | |
9095d37b | 127 | \r |
5ca4bb9f | 128 | @param KeywordString A null-terminated string in <MultiKeywordRequest> format. If a\r |
9095d37b LG |
129 | NULL is passed in the KeywordString field, all of the known\r |
130 | keywords in the system for the NameSpaceId specified are\r | |
5ca4bb9f | 131 | returned in the Results field.\r |
9095d37b | 132 | \r |
5ca4bb9f | 133 | @param Progress On return, points to a character in the KeywordString. Points\r |
9095d37b | 134 | to the string's NULL terminator if the request was successful.\r |
38baa5b6 DB |
135 | Points to the most recent '&' before the first failing name / value\r |
136 | pair (or the beginning of the string if the failure is in the first\r | |
137 | name / value pair) if the request was not successful.\r | |
9095d37b | 138 | \r |
5ca4bb9f | 139 | @param ProgressErr If during the processing of the KeywordString there was a\r |
9095d37b | 140 | failure, this parameter gives additional information about the\r |
5ca4bb9f ED |
141 | possible source of the problem. See the definitions in SetData()\r |
142 | for valid value definitions.\r | |
9095d37b | 143 | \r |
5ca4bb9f | 144 | @param Results A null-terminated string in <MultiKeywordResp> format is returned\r |
9095d37b | 145 | which has all the values filled in for the keywords in the\r |
5ca4bb9f | 146 | KeywordString. This is a callee-allocated field, and must be freed\r |
9095d37b | 147 | by the caller after being used.\r |
5ca4bb9f ED |
148 | \r |
149 | @retval EFI_SUCCESS The specified action was completed successfully.\r | |
9095d37b | 150 | \r |
5ca4bb9f | 151 | @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:\r |
a750b4ae | 152 | 1.Progress, ProgressErr, or Results is NULL.\r |
5ca4bb9f ED |
153 | 2.Parsing of the KeywordString resulted in an error. See\r |
154 | Progress and ProgressErr for more data.\r | |
9095d37b | 155 | \r |
5ca4bb9f ED |
156 | \r |
157 | @retval EFI_NOT_FOUND An element of the KeywordString was not found. See\r | |
158 | ProgressErr for more data.\r | |
159 | \r | |
160 | @retval EFI_NOT_FOUND The NamespaceId specified was not found. See ProgressErr\r | |
161 | for more data.\r | |
162 | \r | |
163 | @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. See\r | |
164 | ProgressErr for more data.\r | |
9095d37b | 165 | \r |
5ca4bb9f ED |
166 | @retval EFI_ACCESS_DENIED The action violated system policy. See ProgressErr for\r |
167 | more data.\r | |
168 | \r | |
169 | @retval EFI_DEVICE_ERROR An unexpected system error occurred. See ProgressErr\r | |
170 | for more data.\r | |
171 | \r | |
172 | **/\r | |
9095d37b | 173 | typedef\r |
5ca4bb9f | 174 | EFI_STATUS\r |
2f88bd3a | 175 | (EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_GET_DATA)(\r |
5ca4bb9f | 176 | IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL *This,\r |
d0e2f823 MK |
177 | IN CONST EFI_STRING NameSpaceId OPTIONAL,\r |
178 | IN CONST EFI_STRING KeywordString OPTIONAL,\r | |
9095d37b | 179 | OUT EFI_STRING *Progress,\r |
5ca4bb9f ED |
180 | OUT UINT32 *ProgressErr,\r |
181 | OUT EFI_STRING *Results\r | |
182 | );\r | |
183 | \r | |
184 | ///\r | |
9095d37b LG |
185 | /// The EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL provides the mechanism\r |
186 | /// to set and get the values associated with a keyword exposed\r | |
5ca4bb9f ED |
187 | /// through a x-UEFI- prefixed configuration language namespace\r |
188 | ///\r | |
189 | \r | |
190 | struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL {\r | |
2f88bd3a MK |
191 | EFI_CONFIG_KEYWORD_HANDLER_SET_DATA SetData;\r |
192 | EFI_CONFIG_KEYWORD_HANDLER_GET_DATA GetData;\r | |
5ca4bb9f ED |
193 | };\r |
194 | \r | |
2f88bd3a | 195 | extern EFI_GUID gEfiConfigKeywordHandlerProtocolGuid;\r |
5ca4bb9f ED |
196 | \r |
197 | #endif\r |