CAutoRevertImpersonation Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CAutoRevertImpersonation Class.
This class reverts CAccessToken objects to a nonimpersonating state when it goes out of scope.
Syntax
class CAutoRevertImpersonation
Members
Public Constructors
| Name | Description |
|---|---|
| CAutoRevertImpersonation::CAutoRevertImpersonation | Constructs an CAutoRevertImpersonation object |
| CAutoRevertImpersonation::~CAutoRevertImpersonation | Destroys the object and reverts access token impersonation. |
Public Methods
| Name | Description |
|---|---|
| CAutoRevertImpersonation::Attach | Automates the impersonation reversion of an access token. |
| CAutoRevertImpersonation::Detach | Cancels the automatic impersonation reversion. |
| CAutoRevertImpersonation::GetAccessToken | Retrieves the access token current associated with this object. |
Remarks
An access token is an object that describes the security context of a process or thread and is allocated to each user logged onto a Windows NT or Windows 2000 system. These access tokens can be represented with the CAccessToken class.
It is sometimes necessary to impersonate access tokens. This class is provided as a convenience, but it does not perform the impersonation of access tokens; it only performs the automatic reversion to a nonimpersonated state. This is because token access impersonation can be performed several different ways.
For an introduction to the access control model in Windows, see Access Control in the Windows SDK.
Requirements
Header: atlsecurity.h
CAutoRevertImpersonation::Attach
Automates the impersonation reversion of an access token.
void Attach(const CAccessToken* pAT) throw();
Parameters
pAT
The address of the CAccessToken object to be reverted automatically
Remarks
This method should only be used if the CAutoRevertImpersonation object was created with a NULL CAccessToken pointer, or if Detach was called previously. For simple cases, it is not necessary to use this method.
CAutoRevertImpersonation::CAutoRevertImpersonation
Constructs a CAutoRevertImpersonation object.
CAutoRevertImpersonation(const CAccessToken* pAT) throw();
Parameters
pAT
The address of the CAccessToken object to be reverted automatically.
Remarks
The actual impersonation of the access token should be performed separately from and preferably before the creation of a CAutoRevertImpersonation object. This impersonation will be reverted automatically when the CAutoRevertImpersonation object goes out of scope.
CAutoRevertImpersonation::~CAutoRevertImpersonation
Destroys the object and reverts access token impersonation.
~CAutoRevertImpersonation() throw();
Remarks
Reverts any impersonation currently in effect for the CAccessToken object provided either at construction or through the Attach method. If no CAccessToken is associated, the destructor has no effect.
CAutoRevertImpersonation::Detach
Cancels the automatic impersonation reversion.
const CAccessToken* Detach() throw();
Return Value
The address of the previously associated CAccessToken, or NULL if no association existed.
Remarks
Calling Detach prevents the CAutoRevertImpersonation object from reverting any impersonation currently in effect for the CAccessToken object associated with this object. CAutoRevertImpersonation can then be destroyed with no effect or reassociated to the same or another CAccessToken object using Attach.
CAutoRevertImpersonation::GetAccessToken
Retrieves the access token current associated with this object.
const CAccessToken* GetAccessToken() throw();
Return Value
The address of the previously associated CAccessToken, or NULL if no association existed.
Remarks
If this method is called for the purposes that include the reversion of an impersonation of the CAccessToken object, the Detach method should be used instead.