Add protocol and related definitions defined in the UEFI 2.3 spec chapter 31 “User Identification”.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@9128 6f19259b-4bc3-4df7-8a09-765794883524
This commit is contained in:
334
MdePkg/Include/Protocol/UserManager.h
Normal file
334
MdePkg/Include/Protocol/UserManager.h
Normal file
@@ -0,0 +1,334 @@
|
||||
/** @file
|
||||
UEFI 2.2 User Manager Protocol definition.
|
||||
|
||||
This protocol manages user profiles.
|
||||
|
||||
Copyright (c) 2009, Intel Corporation
|
||||
All rights reserved. This program and the accompanying materials
|
||||
are licensed and made available under the terms and conditions of the BSD License
|
||||
which accompanies this distribution. The full text of the license may be found at
|
||||
http://opensource.org/licenses/bsd-license.php
|
||||
|
||||
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
|
||||
|
||||
**/
|
||||
|
||||
#ifndef __USER_MANAGER_H__
|
||||
#define __USER_MANAGER_H__
|
||||
|
||||
#include <Protocol/UserCredential.h>
|
||||
|
||||
///
|
||||
/// Global ID for the User Manager Protocol
|
||||
///
|
||||
#define EFI_USER_MANAGER_PROTOCOL_GUID \
|
||||
{ \
|
||||
0x6fd5b00c, 0xd426, 0x4283, { 0x98, 0x87, 0x6c, 0xf5, 0xcf, 0x1c, 0xb1, 0xfe } \
|
||||
}
|
||||
|
||||
#define EFI_EVENT_GROUP_USER_PROFILE_CHANGED \
|
||||
{ \
|
||||
0xbaf1e6de, 0x209e, 0x4adb, { 0x8d, 0x96, 0xfd, 0x8b, 0x71, 0xf3, 0xf6, 0x83 } \
|
||||
}
|
||||
|
||||
typedef struct _EFI_USER_MANAGER_PROTOCOL EFI_USER_MANAGER_PROTOCOL;
|
||||
|
||||
/**
|
||||
Create a new user profile.
|
||||
|
||||
This function creates a new user profile with only a new user identifier attached and returns its
|
||||
handle. The user profile is non-volatile, but the handle User can change across reboots.
|
||||
|
||||
@param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
|
||||
@param[out] User On return, points to the new user profile handle.
|
||||
The user profile handle is unique only during this boot.
|
||||
|
||||
@retval EFI_SUCCESS User profile was successfully created.
|
||||
@retval EFI_ACCESS_DENIED Current user does not have sufficient permissions to create a user profile.
|
||||
@retval EFI_UNSUPPORTED Creation of new user profiles is not supported.
|
||||
@retval EFI_INVALID_PARAMETER The User parameter is NULL.
|
||||
**/
|
||||
typedef
|
||||
EFI_STATUS
|
||||
(EFIAPI *EFI_USER_PROFILE_CREATE)(
|
||||
IN CONST EFI_USER_MANAGER_PROTOCOL *This,
|
||||
OUT EFI_USER_PROFILE_HANDLE *User
|
||||
);
|
||||
|
||||
/**
|
||||
Delete an existing user profile.
|
||||
|
||||
@param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
|
||||
@param[in] User User profile handle.
|
||||
|
||||
@retval EFI_SUCCESS User profile was successfully deleted.
|
||||
@retval EFI_ACCESS_DENIED Current user does not have sufficient permissions to delete a user
|
||||
profile or there is only one user profile.
|
||||
@retval EFI_UNSUPPORTED Deletion of new user profiles is not supported.
|
||||
@retval EFI_INVALID_PARAMETER User does not refer to a valid user profile.
|
||||
**/
|
||||
typedef
|
||||
EFI_STATUS
|
||||
(EFIAPI *EFI_USER_PROFILE_DELETE)(
|
||||
IN CONST EFI_USER_MANAGER_PROTOCOL *This,
|
||||
IN EFI_USER_PROFILE_HANDLE User
|
||||
);
|
||||
|
||||
/**
|
||||
Enumerate all of the enrolled users on the platform.
|
||||
|
||||
This function returns the next enrolled user profile. To retrieve the first user profile handle, point
|
||||
User at a NULL. Each subsequent call will retrieve another user profile handle until there are no
|
||||
more, at which point User will point to NULL.
|
||||
|
||||
@param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
|
||||
@param[in,out] User On entry, points to the previous user profile handle or NULL to
|
||||
start enumeration. On exit, points to the next user profile handle
|
||||
or NULL if there are no more user profiles.
|
||||
|
||||
@retval EFI_SUCCESS Next enrolled user profile successfully returned.
|
||||
@retval EFI_ACCESS_DENIED Next enrolled user profile was not successfully returned.
|
||||
@retval EFI_INVALID_PARAMETER The User parameter is NULL.
|
||||
**/
|
||||
typedef
|
||||
EFI_STATUS
|
||||
(EFIAPI *EFI_USER_PROFILE_GET_NEXT)(
|
||||
IN CONST EFI_USER_MANAGER_PROTOCOL *This,
|
||||
IN OUT EFI_USER_PROFILE_HANDLE *User
|
||||
);
|
||||
|
||||
/**
|
||||
Return the current user profile handle.
|
||||
|
||||
@param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
|
||||
@param[out] CurrentUser On return, points to the current user profile handle.
|
||||
|
||||
@retval EFI_SUCCESS Current user profile handle returned successfully.
|
||||
@retval EFI_INVALID_PARAMETER The CurrentUser parameter is NULL.
|
||||
**/
|
||||
typedef
|
||||
EFI_STATUS
|
||||
(EFIAPI *EFI_USER_PROFILE_CURRENT)(
|
||||
IN CONST EFI_USER_MANAGER_PROTOCOL *This,
|
||||
OUT EFI_USER_PROFILE_HANDLE *CurrentUser
|
||||
);
|
||||
|
||||
/**
|
||||
Identify a user.
|
||||
|
||||
Identify the user and, if authenticated, returns the user handle and changes the current user profile.
|
||||
All user information marked as private in a previously selected profile is no longer available for
|
||||
inspection.
|
||||
Whenever the current user profile is changed then the an event with the GUID
|
||||
EFI_EVENT_GROUP_USER_PROFILE_CHANGED is signaled.
|
||||
|
||||
@param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
|
||||
@param[out] User On return, points to the user profile handle for the current user profile.
|
||||
|
||||
@retval EFI_SUCCESS User was successfully identified.
|
||||
@retval EFI_ACCESS_DENIED User was not successfully identified.
|
||||
@retval EFI_INVALID_PARAMETER The User parameter is NULL.
|
||||
**/
|
||||
typedef
|
||||
EFI_STATUS
|
||||
(EFIAPI *EFI_USER_PROFILE_IDENTIFY)(
|
||||
IN CONST EFI_USER_MANAGER_PROTOCOL *This,
|
||||
OUT EFI_USER_PROFILE_HANDLE *User
|
||||
);
|
||||
|
||||
/**
|
||||
Find a user using a user information record.
|
||||
|
||||
This function searches all user profiles for the specified user information record. The search starts
|
||||
with the user information record handle following UserInfo and continues until either the
|
||||
information is found or there are no more user profiles.
|
||||
A match occurs when the Info.InfoType field matches the user information record type and the
|
||||
user information record data matches the portion of Info passed the EFI_USER_INFO header.
|
||||
|
||||
@param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
|
||||
@param[in,out] User On entry, points to the previously returned user profile handle or NULL to start
|
||||
searching with the first user profile. On return, points to the user profile handle or
|
||||
NULL if not found.
|
||||
@param[in,out] UserInfo On entry, points to the previously returned user information handle or NULL to start
|
||||
searching with the first. On return, points to the user information handle of the user
|
||||
information record or NULL if not found. Can be NULL, in which case only one user
|
||||
information record per user can be returned.
|
||||
@param[in] Info Points to the buffer containing the user information to be compared to the user
|
||||
information record. If NULL, then only the user information record type is compared.
|
||||
If InfoSize is 0, then the user information record must be empty.
|
||||
|
||||
@param[in] InfoSize The size of Info, in bytes.
|
||||
|
||||
@retval EFI_SUCCESS User information was found. User points to the user profile handle and
|
||||
UserInfo points to the user information handle.
|
||||
@retval EFI_NOT_FOUND User information was not found. User points to NULL and UserInfo points to NULL.
|
||||
**/
|
||||
typedef
|
||||
EFI_STATUS
|
||||
(EFIAPI *EFI_USER_PROFILE_FIND)(
|
||||
IN CONST EFI_USER_MANAGER_PROTOCOL *This,
|
||||
IN OUT EFI_USER_PROFILE_HANDLE *User,
|
||||
IN OUT EFI_USER_INFO_HANDLE *UserInfo OPTIONAL,
|
||||
IN CONST EFI_USER_INFO *Info,
|
||||
IN UINTN InfoSize
|
||||
);
|
||||
|
||||
/**
|
||||
Called by credential provider to notify of information change.
|
||||
|
||||
This function allows the credential provider to notify the User Identity Manager when user status has
|
||||
changed while deselected.
|
||||
If the User Identity Manager doesn't support asynchronous changes in credentials, then this function
|
||||
should return EFI_UNSUPPORTED.
|
||||
If the User Identity Manager supports this, it will call User() to get the user identifier and then
|
||||
GetNextInfo() and GetInfo() in the User Credential Protocol to get all of the information
|
||||
from the credential and add it.
|
||||
|
||||
@param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
|
||||
@param[in] Changed Handle on which is installed an instance of the
|
||||
EFI_USER_CREDENTIAL_PROTOCOL where the user has changed.
|
||||
|
||||
@retval EFI_SUCCESS The User Identity Manager has handled the notification.
|
||||
@retval EFI_NOT_READY The function was called while the specified credential provider was not selected.
|
||||
@retval EFI_UNSUPPORTED The User Identity Manager doesn't support asynchronous notifications.
|
||||
**/
|
||||
typedef
|
||||
EFI_STATUS
|
||||
(EFIAPI *EFI_USER_PROFILE_NOTIFY)(
|
||||
IN CONST EFI_USER_MANAGER_PROTOCOL *This,
|
||||
IN EFI_HANDLE Changed
|
||||
);
|
||||
|
||||
/**
|
||||
Return information attached to the user.
|
||||
|
||||
This function returns user information. The format of the information is described in User
|
||||
Information. The function may return EFI_ACCESS_DENIED if the information is marked private
|
||||
and the handle specified by User is not the current user profile. The function may return
|
||||
EFI_ACCESS_DENIED if the information is marked protected and the information is associated
|
||||
with a credential provider for which the user has not been authenticated.
|
||||
|
||||
@param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
|
||||
@param[in] User Handle of the user whose profile will be retrieved.
|
||||
@param[in] UserInfo Handle of the user information data record.
|
||||
@param[out] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user
|
||||
information. If the buffer is too small to hold the information, then
|
||||
EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the
|
||||
number of bytes actually required.
|
||||
@param[in,out] InfoSize On entry, points to the size of Info. On return, points to the size of the user
|
||||
information.
|
||||
|
||||
@retval EFI_SUCCESS Information returned successfully.
|
||||
@retval EFI_ACCESS_DENIED The information about the specified user cannot be accessed by the current user.
|
||||
@retval EFI_BUFFER_TOO_SMALL The number of bytes specified by *InfoSize is too small to hold
|
||||
the returned data. The actual size required is returned in *InfoSize.
|
||||
**/
|
||||
typedef
|
||||
EFI_STATUS
|
||||
(EFIAPI *EFI_USER_PROFILE_GET_INFO)(
|
||||
IN CONST EFI_USER_MANAGER_PROTOCOL *This,
|
||||
IN EFI_USER_PROFILE_HANDLE User,
|
||||
IN EFI_USER_INFO_HANDLE UserInfo,
|
||||
OUT EFI_USER_INFO *Info,
|
||||
IN OUT UINTN *InfoSize
|
||||
);
|
||||
|
||||
/**
|
||||
Add or update user information.
|
||||
|
||||
This function changes user information. If NULL is pointed to by UserInfo, then a new user
|
||||
information record is created and its handle is returned in UserInfo. Otherwise, the existing one is
|
||||
replaced.
|
||||
If EFI_USER_INFO_EXCLUSIVE is specified in Info and a user information record of the same
|
||||
type already exists in the user profile, then EFI_ACCESS_DENIED will be returned and
|
||||
UserInfo will point to the handle of the existing record.
|
||||
|
||||
@param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
|
||||
@param[in] User Handle of the user whose profile will be retrieved.
|
||||
@param[in,out] UserInfo Handle of the user information data record.
|
||||
@param[in] Info On entry, points to a buffer of at least *InfoSize bytes. On exit, holds the user
|
||||
information. If the buffer is too small to hold the information, then
|
||||
EFI_BUFFER_TOO_SMALL is returned and InfoSize is updated to contain the
|
||||
number of bytes actually required.
|
||||
@param[in] InfoSize On entry, points to the size of Info. On return, points to the size of the user
|
||||
information.
|
||||
|
||||
@retval EFI_SUCCESS Information returned successfully.
|
||||
@retval EFI_ACCESS_DENIED The record is exclusive.
|
||||
@retval EFI_SECURITY_VIOLATION The current user does not have permission to change the specified
|
||||
user profile or user information record.
|
||||
**/
|
||||
typedef
|
||||
EFI_STATUS
|
||||
(EFIAPI *EFI_USER_PROFILE_SET_INFO)(
|
||||
IN CONST EFI_USER_MANAGER_PROTOCOL *This,
|
||||
IN EFI_USER_PROFILE_HANDLE User,
|
||||
IN OUT EFI_USER_INFO_HANDLE *UserInfo,
|
||||
IN CONST EFI_USER_INFO *Info,
|
||||
IN UINTN InfoSize
|
||||
);
|
||||
|
||||
/**
|
||||
Delete user information.
|
||||
|
||||
Delete the user information attached to the user profile specified by the UserInfo.
|
||||
|
||||
@param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
|
||||
@param[in] User Handle of the user whose information will be deleted.
|
||||
@param[in] UserInfo Handle of the user information to remove.
|
||||
|
||||
@retval EFI_SUCCESS User information deleted successfully.
|
||||
@retval EFI_NOT_FOUND User information record UserInfo does not exist in the user profile.
|
||||
@retval EFI_ACCESS_DENIED The current user does not have permission to delete this user information.
|
||||
**/
|
||||
typedef
|
||||
EFI_STATUS
|
||||
(EFIAPI *EFI_USER_PROFILE_DELETE_INFO)(
|
||||
IN CONST EFI_USER_MANAGER_PROTOCOL *This,
|
||||
IN EFI_USER_PROFILE_HANDLE User,
|
||||
IN EFI_USER_INFO_HANDLE UserInfo
|
||||
);
|
||||
|
||||
/**
|
||||
Enumerate user information of all the enrolled users on the platform.
|
||||
|
||||
This function returns the next user information record. To retrieve the first user information record
|
||||
handle, point UserInfo at a NULL. Each subsequent call will retrieve another user information
|
||||
record handle until there are no more, at which point UserInfo will point to NULL.
|
||||
|
||||
@param[in] This Points to this instance of the EFI_USER_MANAGER_PROTOCOL.
|
||||
@param[in] User Handle of the user whose information will be deleted.
|
||||
@param[in,out] UserInfo Handle of the user information to remove.
|
||||
|
||||
@retval EFI_SUCCESS User information returned.
|
||||
@retval EFI_NOT_FOUND No more user information found.
|
||||
**/
|
||||
typedef
|
||||
EFI_STATUS
|
||||
(EFIAPI *EFI_USER_PROFILE_GET_NEXT_INFO)(
|
||||
IN CONST EFI_USER_MANAGER_PROTOCOL *This,
|
||||
IN EFI_USER_PROFILE_HANDLE User,
|
||||
IN OUT EFI_USER_INFO_HANDLE *UserInfo
|
||||
);
|
||||
|
||||
///
|
||||
/// This protocol provides the services used to manage user profiles.
|
||||
///
|
||||
struct _EFI_USER_MANAGER_PROTOCOL {
|
||||
EFI_USER_PROFILE_CREATE Create;
|
||||
EFI_USER_PROFILE_DELETE Delete;
|
||||
EFI_USER_PROFILE_GET_NEXT GetNext;
|
||||
EFI_USER_PROFILE_CURRENT Current;
|
||||
EFI_USER_PROFILE_IDENTIFY Identify;
|
||||
EFI_USER_PROFILE_FIND Find;
|
||||
EFI_USER_PROFILE_NOTIFY Notify;
|
||||
EFI_USER_PROFILE_GET_INFO GetInfo;
|
||||
EFI_USER_PROFILE_SET_INFO SetInfo;
|
||||
EFI_USER_PROFILE_DELETE_INFO DeleteInfo;
|
||||
EFI_USER_PROFILE_GET_NEXT_INFO GetNextInfo;
|
||||
};
|
||||
|
||||
extern EFI_GUID gEfiUserManagerProtocolGuid;
|
||||
|
||||
#endif
|
Reference in New Issue
Block a user