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.

See also

ATLSecurity Sample
Access Tokens
Class Overview