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
6Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR>
7This program and the accompanying materials are licensed and made available under
8the terms and conditions of the BSD License that accompanies this distribution.
9The full text of the license may be found at
10http://opensource.org/licenses/bsd-license.php.
11
12THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13WITHOUT 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
36typedef 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**/
97typedef
98EFI_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**/
176typedef
177EFI_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
193struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL {
194  EFI_CONFIG_KEYWORD_HANDLER_SET_DATA  SetData;
195  EFI_CONFIG_KEYWORD_HANDLER_GET_DATA  GetData;
196};
197
198extern EFI_GUID gEfiConfigKeywordHandlerProtocolGuid;
199
200#endif
201
202