]>
Commit | Line | Data |
---|---|---|
2832b228 | 1 | /** @file\r |
2 | UEFI 2.2 User Manager Protocol definition.\r | |
3 | \r | |
4 | This protocol manages user profiles.\r | |
5 | \r | |
6 | Copyright (c) 2009, Intel Corporation \r | |
7 | All rights reserved. This program and the accompanying materials \r | |
8 | are licensed and made available under the terms and conditions of the BSD License \r | |
9 | which accompanies this distribution. The full text of the license may be found at \r | |
10 | http://opensource.org/licenses/bsd-license.php \r | |
11 | \r | |
12 | THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r | |
13 | WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r | |
14 | \r | |
15 | **/\r | |
16 | \r | |
17 | #ifndef __USER_MANAGER_H__\r | |
18 | #define __USER_MANAGER_H__\r | |
19 | \r | |
20 | #include <Protocol/UserCredential.h>\r | |
21 | \r | |
22 | ///\r | |
23 | /// Global ID for the User Manager Protocol\r | |
24 | ///\r | |
25 | #define EFI_USER_MANAGER_PROTOCOL_GUID \\r | |
26 | { \\r | |
27 | 0x6fd5b00c, 0xd426, 0x4283, { 0x98, 0x87, 0x6c, 0xf5, 0xcf, 0x1c, 0xb1, 0xfe } \\r | |
28 | }\r | |
29 | \r | |
30 | #define EFI_EVENT_GROUP_USER_PROFILE_CHANGED \\r | |
31 | { \\r | |
32 | 0xbaf1e6de, 0x209e, 0x4adb, { 0x8d, 0x96, 0xfd, 0x8b, 0x71, 0xf3, 0xf6, 0x83 } \\r | |
33 | }\r | |
34 | \r | |
35 | typedef struct _EFI_USER_MANAGER_PROTOCOL EFI_USER_MANAGER_PROTOCOL;\r | |
36 | \r | |
37 | /**\r | |
38 | Create a new user profile.\r | |
39 | \r | |
40 | This function creates a new user profile with only a new user identifier attached and returns its \r | |
41 | handle. The user profile is non-volatile, but the handle User can change across reboots.\r | |
42 | \r | |
43 | @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.\r | |
44 | @param[out] User On return, points to the new user profile handle. \r | |
45 | The user profile handle is unique only during this boot.\r | |
46 | \r | |
47 | @retval EFI_SUCCESS User profile was successfully created.\r | |
48 | @retval EFI_ACCESS_DENIED Current user does not have sufficient permissions to create a user profile.\r | |
49 | @retval EFI_UNSUPPORTED Creation of new user profiles is not supported.\r | |
50 | @retval EFI_INVALID_PARAMETER The User parameter is NULL.\r | |
51 | **/\r | |
52 | typedef\r | |
53 | EFI_STATUS\r | |
54 | (EFIAPI *EFI_USER_PROFILE_CREATE)(\r | |
55 | IN CONST EFI_USER_MANAGER_PROTOCOL *This,\r | |
56 | OUT EFI_USER_PROFILE_HANDLE *User\r | |
57 | );\r | |
58 | \r | |
59 | /**\r | |
60 | Delete an existing user profile.\r | |
61 | \r | |
62 | @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.\r | |
63 | @param[in] User User profile handle. \r | |
64 | \r | |
65 | @retval EFI_SUCCESS User profile was successfully deleted.\r | |
66 | @retval EFI_ACCESS_DENIED Current user does not have sufficient permissions to delete a user\r | |
67 | profile or there is only one user profile.\r | |
68 | @retval EFI_UNSUPPORTED Deletion of new user profiles is not supported.\r | |
69 | @retval EFI_INVALID_PARAMETER User does not refer to a valid user profile.\r | |
70 | **/\r | |
71 | typedef\r | |
72 | EFI_STATUS\r | |
73 | (EFIAPI *EFI_USER_PROFILE_DELETE)(\r | |
74 | IN CONST EFI_USER_MANAGER_PROTOCOL *This,\r | |
75 | IN EFI_USER_PROFILE_HANDLE User\r | |
76 | );\r | |
77 | \r | |
78 | /**\r | |
79 | Enumerate all of the enrolled users on the platform.\r | |
80 | \r | |
81 | This function returns the next enrolled user profile. To retrieve the first user profile handle, point \r | |
82 | User at a NULL. Each subsequent call will retrieve another user profile handle until there are no \r | |
83 | more, at which point User will point to NULL. \r | |
84 | \r | |
85 | @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.\r | |
86 | @param[in,out] User On entry, points to the previous user profile handle or NULL to \r | |
87 | start enumeration. On exit, points to the next user profile handle\r | |
88 | or NULL if there are no more user profiles.\r | |
89 | \r | |
90 | @retval EFI_SUCCESS Next enrolled user profile successfully returned. \r | |
91 | @retval EFI_ACCESS_DENIED Next enrolled user profile was not successfully returned.\r | |
92 | @retval EFI_INVALID_PARAMETER The User parameter is NULL.\r | |
93 | **/\r | |
94 | typedef\r | |
95 | EFI_STATUS\r | |
96 | (EFIAPI *EFI_USER_PROFILE_GET_NEXT)(\r | |
97 | IN CONST EFI_USER_MANAGER_PROTOCOL *This,\r | |
98 | IN OUT EFI_USER_PROFILE_HANDLE *User\r | |
99 | );\r | |
100 | \r | |
101 | /**\r | |
102 | Return the current user profile handle.\r | |
103 | \r | |
104 | @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.\r | |
105 | @param[out] CurrentUser On return, points to the current user profile handle.\r | |
106 | \r | |
107 | @retval EFI_SUCCESS Current user profile handle returned successfully. \r | |
108 | @retval EFI_INVALID_PARAMETER The CurrentUser parameter is NULL.\r | |
109 | **/\r | |
110 | typedef\r | |
111 | EFI_STATUS\r | |
112 | (EFIAPI *EFI_USER_PROFILE_CURRENT)(\r | |
113 | IN CONST EFI_USER_MANAGER_PROTOCOL *This,\r | |
114 | OUT EFI_USER_PROFILE_HANDLE *CurrentUser\r | |
115 | );\r | |
116 | \r | |
117 | /**\r | |
118 | Identify a user.\r | |
119 | \r | |
120 | Identify the user and, if authenticated, returns the user handle and changes the current user profile.\r | |
121 | All user information marked as private in a previously selected profile is no longer available for \r | |
122 | inspection. \r | |
123 | Whenever the current user profile is changed then the an event with the GUID \r | |
124 | EFI_EVENT_GROUP_USER_PROFILE_CHANGED is signaled.\r | |
125 | \r | |
126 | @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.\r | |
127 | @param[out] User On return, points to the user profile handle for the current user profile.\r | |
128 | \r | |
129 | @retval EFI_SUCCESS User was successfully identified.\r | |
130 | @retval EFI_ACCESS_DENIED User was not successfully identified.\r | |
131 | @retval EFI_INVALID_PARAMETER The User parameter is NULL.\r | |
132 | **/\r | |
133 | typedef\r | |
134 | EFI_STATUS\r | |
135 | (EFIAPI *EFI_USER_PROFILE_IDENTIFY)(\r | |
136 | IN CONST EFI_USER_MANAGER_PROTOCOL *This,\r | |
137 | OUT EFI_USER_PROFILE_HANDLE *User\r | |
138 | );\r | |
139 | \r | |
140 | /**\r | |
141 | Find a user using a user information record.\r | |
142 | \r | |
143 | This function searches all user profiles for the specified user information record. The search starts \r | |
144 | with the user information record handle following UserInfo and continues until either the \r | |
145 | information is found or there are no more user profiles.\r | |
146 | A match occurs when the Info.InfoType field matches the user information record type and the \r | |
147 | user information record data matches the portion of Info passed the EFI_USER_INFO header.\r | |
148 | \r | |
149 | @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.\r | |
150 | @param[in,out] User On entry, points to the previously returned user profile handle or NULL to start \r | |
151 | searching with the first user profile. On return, points to the user profile handle or \r | |
152 | NULL if not found.\r | |
153 | @param[in,out] UserInfo On entry, points to the previously returned user information handle or NULL to start \r | |
154 | searching with the first. On return, points to the user information handle of the user \r | |
155 | information record or NULL if not found. Can be NULL, in which case only one user \r | |
156 | information record per user can be returned. \r | |
157 | @param[in] Info Points to the buffer containing the user information to be compared to the user \r | |
158 | information record. If NULL, then only the user information record type is compared. \r | |
159 | If InfoSize is 0, then the user information record must be empty.\r | |
160 | \r | |
161 | @param[in] InfoSize The size of Info, in bytes. \r | |
162 | \r | |
163 | @retval EFI_SUCCESS User information was found. User points to the user profile handle and \r | |
164 | UserInfo points to the user information handle.\r | |
165 | @retval EFI_NOT_FOUND User information was not found. User points to NULL and UserInfo points to NULL.\r | |
166 | **/\r | |
167 | typedef\r | |
168 | EFI_STATUS\r | |
169 | (EFIAPI *EFI_USER_PROFILE_FIND)(\r | |
170 | IN CONST EFI_USER_MANAGER_PROTOCOL *This,\r | |
171 | IN OUT EFI_USER_PROFILE_HANDLE *User,\r | |
172 | IN OUT EFI_USER_INFO_HANDLE *UserInfo OPTIONAL,\r | |
173 | IN CONST EFI_USER_INFO *Info,\r | |
174 | IN UINTN InfoSize\r | |
175 | );\r | |
176 | \r | |
177 | /**\r | |
178 | Called by credential provider to notify of information change.\r | |
179 | \r | |
180 | This function allows the credential provider to notify the User Identity Manager when user status has \r | |
181 | changed while deselected.\r | |
182 | If the User Identity Manager doesn't support asynchronous changes in credentials, then this function \r | |
183 | should return EFI_UNSUPPORTED. \r | |
184 | If the User Identity Manager supports this, it will call User() to get the user identifier and then \r | |
185 | GetNextInfo() and GetInfo() in the User Credential Protocol to get all of the information \r | |
186 | from the credential and add it.\r | |
187 | \r | |
188 | @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.\r | |
189 | @param[in] Changed Handle on which is installed an instance of the\r | |
190 | EFI_USER_CREDENTIAL_PROTOCOL where the user has changed.\r | |
191 | \r | |
192 | @retval EFI_SUCCESS The User Identity Manager has handled the notification.\r | |
193 | @retval EFI_NOT_READY The function was called while the specified credential provider was not selected.\r | |
194 | @retval EFI_UNSUPPORTED The User Identity Manager doesn't support asynchronous notifications.\r | |
195 | **/\r | |
196 | typedef\r | |
197 | EFI_STATUS\r | |
198 | (EFIAPI *EFI_USER_PROFILE_NOTIFY)(\r | |
199 | IN CONST EFI_USER_MANAGER_PROTOCOL *This,\r | |
200 | IN EFI_HANDLE Changed\r | |
201 | );\r | |
202 | \r | |
203 | /**\r | |
204 | Return information attached to the user.\r | |
205 | \r | |
206 | This function returns user information. The format of the information is described in User \r | |
207 | Information. The function may return EFI_ACCESS_DENIED if the information is marked private \r | |
208 | and the handle specified by User is not the current user profile. The function may return \r | |
209 | EFI_ACCESS_DENIED if the information is marked protected and the information is associated \r | |
210 | with a credential provider for which the user has not been authenticated.\r | |
211 | \r | |
212 | @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.\r | |
213 | @param[in] User Handle of the user whose profile will be retrieved. \r | |
214 | @param[in] UserInfo Handle of the user information data record. \r | |
215 | @param[out] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user \r | |
216 | information. If the buffer is too small to hold the information, then \r | |
217 | EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the \r | |
218 | number of bytes actually required. \r | |
219 | @param[in,out] InfoSize On entry, points to the size of Info. On return, points to the size of the user \r | |
220 | information. \r | |
221 | \r | |
222 | @retval EFI_SUCCESS Information returned successfully.\r | |
223 | @retval EFI_ACCESS_DENIED The information about the specified user cannot be accessed by the current user.\r | |
224 | @retval EFI_BUFFER_TOO_SMALL The number of bytes specified by *InfoSize is too small to hold \r | |
225 | the returned data. The actual size required is returned in *InfoSize.\r | |
226 | **/ \r | |
227 | typedef\r | |
228 | EFI_STATUS\r | |
229 | (EFIAPI *EFI_USER_PROFILE_GET_INFO)(\r | |
230 | IN CONST EFI_USER_MANAGER_PROTOCOL *This,\r | |
231 | IN EFI_USER_PROFILE_HANDLE User,\r | |
232 | IN EFI_USER_INFO_HANDLE UserInfo,\r | |
233 | OUT EFI_USER_INFO *Info,\r | |
234 | IN OUT UINTN *InfoSize\r | |
235 | );\r | |
236 | \r | |
237 | /**\r | |
238 | Add or update user information.\r | |
239 | \r | |
240 | This function changes user information. If NULL is pointed to by UserInfo, then a new user \r | |
241 | information record is created and its handle is returned in UserInfo. Otherwise, the existing one is \r | |
242 | replaced.\r | |
243 | If EFI_USER_INFO_EXCLUSIVE is specified in Info and a user information record of the same \r | |
244 | type already exists in the user profile, then EFI_ACCESS_DENIED will be returned and \r | |
245 | UserInfo will point to the handle of the existing record.\r | |
246 | \r | |
247 | @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.\r | |
248 | @param[in] User Handle of the user whose profile will be retrieved. \r | |
249 | @param[in,out] UserInfo Handle of the user information data record. \r | |
250 | @param[in] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user \r | |
251 | information. If the buffer is too small to hold the information, then \r | |
252 | EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the \r | |
253 | number of bytes actually required. \r | |
254 | @param[in] InfoSize On entry, points to the size of Info. On return, points to the size of the user \r | |
255 | information. \r | |
256 | \r | |
257 | @retval EFI_SUCCESS Information returned successfully.\r | |
258 | @retval EFI_ACCESS_DENIED The record is exclusive.\r | |
259 | @retval EFI_SECURITY_VIOLATION The current user does not have permission to change the specified \r | |
260 | user profile or user information record.\r | |
261 | **/ \r | |
262 | typedef\r | |
263 | EFI_STATUS\r | |
264 | (EFIAPI *EFI_USER_PROFILE_SET_INFO)(\r | |
265 | IN CONST EFI_USER_MANAGER_PROTOCOL *This,\r | |
266 | IN EFI_USER_PROFILE_HANDLE User,\r | |
267 | IN OUT EFI_USER_INFO_HANDLE *UserInfo,\r | |
268 | IN CONST EFI_USER_INFO *Info,\r | |
269 | IN UINTN InfoSize\r | |
270 | );\r | |
271 | \r | |
272 | /**\r | |
273 | Delete user information.\r | |
274 | \r | |
275 | Delete the user information attached to the user profile specified by the UserInfo.\r | |
276 | \r | |
277 | @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.\r | |
278 | @param[in] User Handle of the user whose information will be deleted.\r | |
279 | @param[in] UserInfo Handle of the user information to remove.\r | |
280 | \r | |
281 | @retval EFI_SUCCESS User information deleted successfully.\r | |
282 | @retval EFI_NOT_FOUND User information record UserInfo does not exist in the user profile.\r | |
283 | @retval EFI_ACCESS_DENIED The current user does not have permission to delete this user information. \r | |
284 | **/ \r | |
285 | typedef\r | |
286 | EFI_STATUS\r | |
287 | (EFIAPI *EFI_USER_PROFILE_DELETE_INFO)(\r | |
288 | IN CONST EFI_USER_MANAGER_PROTOCOL *This,\r | |
289 | IN EFI_USER_PROFILE_HANDLE User,\r | |
290 | IN EFI_USER_INFO_HANDLE UserInfo\r | |
291 | );\r | |
292 | \r | |
293 | /**\r | |
294 | Enumerate user information of all the enrolled users on the platform.\r | |
295 | \r | |
296 | This function returns the next user information record. To retrieve the first user information record \r | |
297 | handle, point UserInfo at a NULL. Each subsequent call will retrieve another user information \r | |
298 | record handle until there are no more, at which point UserInfo will point to NULL. \r | |
299 | \r | |
ea4220e3 | 300 | Note: in-consistency between code and the UEFI 2.3 specification that the type of the User parameter\r |
301 | is EFI_USER_PROFILE_HANDLE. It should be spec error and wait for spec update.\r | |
302 | \r | |
2832b228 | 303 | @param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.\r |
304 | @param[in] User Handle of the user whose information will be deleted.\r | |
305 | @param[in,out] UserInfo Handle of the user information to remove.\r | |
306 | \r | |
307 | @retval EFI_SUCCESS User information returned.\r | |
308 | @retval EFI_NOT_FOUND No more user information found.\r | |
309 | **/ \r | |
310 | typedef\r | |
311 | EFI_STATUS\r | |
312 | (EFIAPI *EFI_USER_PROFILE_GET_NEXT_INFO)(\r | |
313 | IN CONST EFI_USER_MANAGER_PROTOCOL *This,\r | |
314 | IN EFI_USER_PROFILE_HANDLE User,\r | |
315 | IN OUT EFI_USER_INFO_HANDLE *UserInfo\r | |
316 | );\r | |
317 | \r | |
318 | ///\r | |
319 | /// This protocol provides the services used to manage user profiles.\r | |
320 | ///\r | |
321 | struct _EFI_USER_MANAGER_PROTOCOL {\r | |
322 | EFI_USER_PROFILE_CREATE Create;\r | |
323 | EFI_USER_PROFILE_DELETE Delete;\r | |
324 | EFI_USER_PROFILE_GET_NEXT GetNext;\r | |
325 | EFI_USER_PROFILE_CURRENT Current;\r | |
326 | EFI_USER_PROFILE_IDENTIFY Identify;\r | |
327 | EFI_USER_PROFILE_FIND Find;\r | |
328 | EFI_USER_PROFILE_NOTIFY Notify;\r | |
329 | EFI_USER_PROFILE_GET_INFO GetInfo;\r | |
330 | EFI_USER_PROFILE_SET_INFO SetInfo;\r | |
331 | EFI_USER_PROFILE_DELETE_INFO DeleteInfo;\r | |
332 | EFI_USER_PROFILE_GET_NEXT_INFO GetNextInfo;\r | |
333 | };\r | |
334 | \r | |
335 | extern EFI_GUID gEfiUserManagerProtocolGuid;\r | |
336 | \r | |
337 | #endif\r |