CAutoRevertImpersonation Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

This class reverts CAccessToken objects to a nonimpersonating state when it goes out of scope.

class CAutoRevertImpersonation

Public Constructors

NameDescription
CAutoRevertImpersonation::CAutoRevertImpersonationConstructs an CAutoRevertImpersonation object
CAutoRevertImpersonation::~CAutoRevertImpersonationDestroys the object and reverts access token impersonation.

Public Methods

NameDescription
CAutoRevertImpersonation::AttachAutomates the impersonation reversion of an access token.
CAutoRevertImpersonation::DetachCancels the automatic impersonation reversion.
CAutoRevertImpersonation::GetAccessTokenRetrieves the access token current associated with this object.

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.

Header: atlsecurity.h

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.

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.

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.

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.

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.

ATLSecurity Sample
Access Tokens
Class Overview

Show: