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.

System_CAPS_ICON_important.jpg Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

class CTokenPrivileges

Public Constructors

NameDescription
CTokenPrivileges::CTokenPrivilegesThe constructor.
CTokenPrivileges::~CTokenPrivilegesThe destructor.

Public Methods

NameDescription
CTokenPrivileges::AddAdds one or more privileges to the CTokenPrivileges object.
CTokenPrivileges::DeleteDeletes a privilege from the CTokenPrivileges object.
CTokenPrivileges::DeleteAllDeletes all privileges from the CTokenPrivileges object.
CTokenPrivileges::GetCountReturns the number of privilege entries in the CTokenPrivileges object.
CTokenPrivileges::GetDisplayNamesRetrieves display names for the privileges contained in the CTokenPrivileges object.
CTokenPrivileges::GetLengthReturns the buffer size in bytes required to hold the TOKEN_PRIVILEGES structure represented by the CTokenPrivileges object.
CTokenPrivileges::GetLuidsAndAttributesRetrieves the locally unique identifiers (LUIDs) and attribute flags from the CTokenPrivileges object.
CTokenPrivileges::GetNamesAndAttributesRetrieves the privilege names and attribute flags from the CTokenPrivileges object.
CTokenPrivileges::GetPTOKEN_PRIVILEGESReturns a pointer to the TOKEN_PRIVILEGES structure.
CTokenPrivileges::LookupPrivilegeRetrieves the attribute associated with a given privilege name.

Public Operators

NameDescription
CTokenPrivileges::operator const TOKEN_PRIVILEGES *Casts a value to a pointer to the TOKEN_PRIVILEGES structure.
CTokenPrivileges::operator =Assignment operator.

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.

Header: atlsecurity.h

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.

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.

The destructor.

virtual ~CTokenPrivileges() throw();

Remarks

The destructor frees all allocated resources.

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.

Deletes all privileges from the CTokenPrivileges access token object.

void DeleteAll() throw();

Remarks

Deletes all privileges contained in the CTokenPrivileges access token object.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Security Sample
TOKEN_PRIVILEGES
LUID
LUID_AND_ATTRIBUTES
Class Overview
Security Global Functions

Show: