CTokenPrivileges Class
This class is a wrapper for the TOKEN_PRIVILEGES structure.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
class CTokenPrivileges
Members
Public Constructors
| Name | Description |
|---|---|
| CTokenPrivileges::CTokenPrivileges | The constructor. |
| CTokenPrivileges::~CTokenPrivileges | The destructor. |
Public Methods
| Name | Description |
|---|---|
| CTokenPrivileges::Add | Adds one or more privileges to the CTokenPrivileges object. |
| CTokenPrivileges::Delete | Deletes a privilege from the CTokenPrivileges object. |
| CTokenPrivileges::DeleteAll | Deletes all privileges from the CTokenPrivileges object. |
| CTokenPrivileges::GetCount | Returns the number of privilege entries in the CTokenPrivileges object. |
| CTokenPrivileges::GetDisplayNames | Retrieves display names for the privileges contained in the CTokenPrivileges object. |
| CTokenPrivileges::GetLength | Returns the buffer size in bytes required to hold the TOKEN_PRIVILEGES structure represented by the CTokenPrivileges object. |
| CTokenPrivileges::GetLuidsAndAttributes | Retrieves the locally unique identifiers (LUIDs) and attribute flags from the CTokenPrivileges object. |
| CTokenPrivileges::GetNamesAndAttributes | Retrieves the privilege names and attribute flags from the CTokenPrivileges object. |
| CTokenPrivileges::GetPTOKEN_PRIVILEGES | Returns a pointer to the TOKEN_PRIVILEGES structure. |
| CTokenPrivileges::LookupPrivilege | Retrieves the attribute associated with a given privilege name. |
Public Operators
| Name | Description |
|---|---|
| CTokenPrivileges::operator const TOKEN_PRIVILEGES * | Casts a value to a pointer to the TOKEN_PRIVILEGES structure. |
| CTokenPrivileges::operator = | Assignment operator. |
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 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.
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
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for