| 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 |
| d14d2707 |
336 | extern EFI_GUID gEfiEventUserProfileChangedGuid;\r |
| 2832b228 |
337 | \r |
| 338 | #endif\r |
projects / mirror_edk2.git / blame