PsReferenceImpersonationToken routine

The PsReferenceImpersonationToken routine increments the reference count of the impersonation token for the specified thread.

Syntax


PACCESS_TOKEN PsReferenceImpersonationToken(
  _Inout_ PETHREAD                      Thread,
  _Out_   PBOOLEAN                      CopyOnOpen,
  _Out_   PBOOLEAN                      EffectiveOnly,
  _Out_   PSECURITY_IMPERSONATION_LEVEL ImpersonationLevel
);

Parameters

Thread [in, out]

Address of the thread whose impersonation token's reference count is to be incremented.

CopyOnOpen [out]

Pointer to a caller-allocated Boolean variable. On return, this parameter receives TRUE if the token cannot be opened directly. In this case, the token must be duplicated, and the duplicate token must be used instead. If the token can be opened directly, this parameter receives FALSE.

EffectiveOnly [out]

Pointer to a caller-allocated Boolean variable. On return, this parameter receives FALSE if the thread is allowed to enable groups and privileges that are currently disabled in the client security context, TRUE otherwise.

ImpersonationLevel [out]

Pointer to a caller-allocated SECURITY_IMPERSONATION_LEVEL variable. On return, this parameter receives a value that specifies the impersonation level at which the thread is allowed to access the token.

Return value

PsReferenceImpersonationToken returns a pointer to the impersonation token for the given thread. If the thread is not currently impersonating a client, a NULL pointer is returned.

Remarks

This routine is available starting with Microsoft Windows 2000.

If the thread is currently impersonating a client, PsReferenceImpersonationToken increments the reference count of the impersonation token and returns a pointer to the token. If the returned pointer is non-NULL, the impersonation token's reference count must be decremented by calling one of the following functions:

  • ObDereferenceObject, for Windows 2000.

  • PsDereferenceImpersonationToken, for Microsoft Windows XP or later.

For more information about security and access control, see the documentation on these topics in the Microsoft Windows SDK.

Requirements

Target platform

Universal

Header

Ntifs.h (include FltKernel.h or Ntifs.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

PASSIVE_LEVEL

See also

ObDereferenceObject
PsDereferenceImpersonationToken
PsImpersonateClient
SECURITY_IMPERSONATION_LEVEL

 

 

Send comments about this topic to Microsoft

Show: