CTokenPrivileges 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 CTokenPrivileges Class.

This class is a wrapper for the TOKEN_PRIVILEGES structure.

Syntax

class CTokenPrivileges

Members

Public Constructors

Public Methods

Public Operators

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.

The access token is used to describe the various security privileges granted to each user. A privilege consists of a 64-bit number called a locally unique identifier ( LUID) and a descriptor string.

The CTokenPrivileges class is a wrapper for the TOKEN_PRIVILEGES structure and contains 0 or more privileges. Privileges can be added, deleted, or queried using the supplied class methods.

For an introduction to the access control model in Windows, see Access Control in the Windows SDK.

Requirements

Header: atlsecurity.h

CTokenPrivileges::Add

Adds one or more privileges to the CTokenPrivileges access token object.

bool Add(LPCTSTR pszPrivilege, bool bEnable) throw(...);  
void Add(const TOKEN_PRIVILEGES& rPrivileges) throw(...);

Parameters

pszPrivilege
Pointer to a null-terminated string that specifies the name of the privilege, as defined in the WINNT.H header file.

bEnable
If true, the privilege is enabled. If false, the privilege is disabled.

rPrivileges
Reference to a TOKEN_PRIVILEGES structure. The privileges and attributes are copied from this structure and added to the CTokenPrivileges object.

Return Value

The first form of this method returns true if the privileges are successfully added, false otherwise.

CTokenPrivileges::CTokenPrivileges

The constructor.

CTokenPrivileges() throw();
CTokenPrivileges(const CTokenPrivileges& rhs) throw(... );  
CTokenPrivileges(const TOKEN_PRIVILEGES& rPrivileges) throw(...);

Parameters

rhs
The CTokenPrivileges object to assign to the new object.

rPrivileges
The TOKEN_PRIVILEGES structure to assign to the new CTokenPrivileges object.

Remarks

The CTokenPrivileges object can optionally be created using a TOKEN_PRIVILEGES structure or a previously defined CTokenPrivileges object.

CTokenPrivileges::~CTokenPrivileges

The destructor.

virtual ~CTokenPrivileges() throw();

Remarks

The destructor frees all allocated resources.

CTokenPrivileges::Delete

Deletes a privilege from the CTokenPrivileges access token object.

bool Delete(LPCTSTR pszPrivilege) throw();

Parameters

pszPrivilege
Pointer to a null-terminated string that specifies the name of the privilege, as defined in the WINNT.H header file. For example, this parameter could specify the constant SE_SECURITY_NAME, or its corresponding string, "SeSecurityPrivilege."

Return Value

Returns true if the privilege was successfully deleted, false otherwise.

Remarks

This method is useful as a tool for creating restricted tokens under Windows 2000.

CTokenPrivileges::DeleteAll

Deletes all privileges from the CTokenPrivileges access token object.

void DeleteAll() throw();

Remarks

Deletes all privileges contained in the CTokenPrivileges access token object.

CTokenPrivileges::GetDisplayNames

Retrieves display names for the privileges contained in the CTokenPrivileges access token object.

void GetDisplayNames(CNames* pDisplayNames) const throw(...);

Parameters

pDisplayNames
A pointer to an array of CString objects. CNames is defined as a typedef: CTokenPrivileges::CAtlArray<CString>.

Remarks

The parameter pDisplayNames is a pointer to an array of CString objects which will receive the display names corresponding to the privileges contained in the CTokenPrivileges object. This method retrieves display names only for the privileges specified in the Defined Privileges section of WINNT.H.

This method retrieves a displayable name: for example, if the attribute name is SE_REMOTE_SHUTDOWN_NAME, the displayable name is "Force shutdown from a remote system." To obtain the system name, use CTokenPrivileges::GetNamesAndAttributes.

CTokenPrivileges::GetCount

Returns the number of privilege entries in the CTokenPrivileges object.

UINT GetCount() const throw();

Return Value

Returns the number of privileges contained in the CTokenPrivileges object.

CTokenPrivileges::GetLength

Returns the length of the CTokenPrivileges object.

UINT GetLength() const throw();

Return Value

Returns the number of bytes required to hold a TOKEN_PRIVILEGES structure represented by the CTokenPrivileges object, including all of the privilege entries it contains.

CTokenPrivileges::GetLuidsAndAttributes

Retrieves the locally unique identifiers (LUIDs) and attribute flags from the CTokenPrivileges object.

void GetLuidsAndAttributes(
    CLUIDArray* pPrivileges,
    CAttributes* pAttributes = NULL) const throw(...);

Parameters

pPrivileges
Pointer to an array of LUID objects. CLUIDArray is a typedef defined as CAtlArray<LUID> CLUIDArray.

pAttributes
Pointer to an array of DWORD objects. If this parameter is omitted or NULL, the attributes are not retrieved. CAttributes is a typedef defined as CAtlArray <DWORD> CAttributes.

Remarks

This method will enumerate all of the privileges contained in the CTokenPrivileges access token object and place the individual LUIDs and (optionally) the attribute flags into array objects.

CTokenPrivileges::GetNamesAndAttributes

Retrieves the name and attribute flags from the CTokenPrivileges object.

void GetNamesAndAttributes(
    CNames* pNames,
    CAttributes* pAttributes = NULL) const throw(...);

Parameters

pNames
Pointer to an array of CString objects. CNames is a typedef defined as CAtlArray <CString> CNames.

pAttributes
Pointer to an array of DWORD objects. If this parameter is omitted or NULL, the attributes are not retrieved. CAttributes is a typedef defined as CAtlArray <DWORD> CAttributes.

Remarks

This method will enumerate all of the privileges contained in the CTokenPrivileges object, placing the name and (optionally) the attribute flags into array objects.

This method retrieves the attribute name, rather than the displayable name: for example, if the attribute name is SE_REMOTE_SHUTDOWN_NAME, the system name is "SeRemoteShutdownPrivilege." To obtain the displayable name, use the method CTokenPrivileges::GetDisplayNames.

CTokenPrivileges::GetPTOKEN_PRIVILEGES

Returns a pointer to the TOKEN_PRIVILEGES structure.

const TOKEN_PRIVILEGES* GetPTOKEN_PRIVILEGES() const throw(...);

Return Value

Returns a pointer to the TOKEN_PRIVILEGES structure.

CTokenPrivileges::LookupPrivilege

Retrieves the attribute associated with a given privilege name.

bool LookupPrivilege(
    LPCTSTR pszPrivilege,
    DWORD* pdwAttributes = NULL) const throw(...);

Parameters

pszPrivilege
Pointer to a null-terminated string that specifies the name of the privilege, as defined in the WINNT.H header file. For example, this parameter could specify the constant SE_SECURITY_NAME, or its corresponding string, "SeSecurityPrivilege."

pdwAttributes
Pointer to a variable that receives the attributes.

Return Value

Returns true if the attribute is successfully retrieved, false otherwise.

CTokenPrivileges::operator =

Assignment operator.

CTokenPrivileges& operator= (const TOKEN_PRIVILEGES& rPrivileges) throw(...);  
CTokenPrivileges& operator= (const CTokenPrivileges& rhs) throw(...);

Parameters

rPrivileges
The TOKEN_PRIVILEGES structure to assign to the CTokenPrivileges object.

rhs
The CTokenPrivileges object to assign to the object.

Return Value

Returns the updated CTokenPrivileges object.

CTokenPrivileges::operator const TOKEN_PRIVILEGES *

Casts a value to a pointer to the TOKEN_PRIVILEGES structure.

operator const TOKEN_PRIVILEGES *() const throw(...);

Remarks

Casts a value to a pointer to the TOKEN_PRIVILEGES structure.

See Also

Security Sample
TOKEN_PRIVILEGES
LUID
LUID_AND_ATTRIBUTES
Class Overview
Security Global Functions