CTokenGroups Class

This class is a wrapper for the TOKEN_GROUPS structure.

Important

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

Syntax

class CTokenGroups

Members

Public Constructors

Name	Description
CTokenGroups::CTokenGroups	The constructor.
CTokenGroups::~CTokenGroups	The destructor.

Public Methods

Name	Description
CTokenGroups::Add	Adds a CSid or existing TOKEN_GROUPS structure to the CTokenGroups object.
CTokenGroups::Delete	Deletes a CSid and its associated attributes from the CTokenGroups object.
CTokenGroups::DeleteAll	Deletes all CSid objects and their associated attributes from the CTokenGroups object.
CTokenGroups::GetCount	Returns the number of CSid objects and associated attributes contained in the CTokenGroups object.
CTokenGroups::GetLength	Returns the size of the CTokenGroups object.
CTokenGroups::GetPTOKEN_GROUPS	Retrieves a pointer to the TOKEN_GROUPS structure.
CTokenGroups::GetSidsAndAttributes	Retrieves the CSid objects and attributes belonging to the CTokenGroups object.
CTokenGroups::LookupSid	Retrieves the attributes associated with a CSid object.

Public Operators

Name	Description
CTokenGroups::operator const TOKEN_GROUPS *	Casts the CTokenGroups object to a pointer to the TOKEN_GROUPS structure.
CTokenGroups::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 CTokenGroups class is a wrapper for the TOKEN_GROUPS structure, containing information about the group security identifiers (SIDs) in an access token.

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

Requirements

Header: atlsecurity.h

CTokenGroups::Add

Adds a CSid or existing TOKEN_GROUPS structure to the CTokenGroups object.

void Add(const CSid& rSid, DWORD dwAttributes) throw(... );
void Add(const TOKEN_GROUPS& rTokenGroups) throw(...);

Parameters

rSid
A CSid object.

dwAttributes
The attributes to associate with the CSid object.

rTokenGroups
A TOKEN_GROUPS structure.

Remarks

These methods add one or more CSid objects and their associated attributes to the CTokenGroups object.

CTokenGroups::CTokenGroups

The constructor.

CTokenGroups() throw();
CTokenGroups(const CTokenGroups& rhs) throw(... );
CTokenGroups(const TOKEN_GROUPS& rhs) throw(...);

Parameters

rhs
The CTokenGroups object or TOKEN_GROUPS structure with which to construct the CTokenGroups object.

Remarks

The CTokenGroups object can optionally be created using a TOKEN_GROUPS structure or a previously defined CTokenGroups object.

CTokenGroups::~CTokenGroups

The destructor.

virtual ~CTokenGroups() throw();

Remarks

The destructor frees all allocated resources.

CTokenGroups::Delete

Deletes a CSid and its associated attributes from the CTokenGroups object.

bool Delete(const CSid& rSid) throw();

Parameters

rSid
The CSid object for which the security identifier (SID) and attributes should be removed.

Return Value

Returns true if the CSid is removed, false otherwise.

CTokenGroups::DeleteAll

Deletes all CSid objects and their associated attributes from the CTokenGroups object.

void DeleteAll() throw();

CTokenGroups::GetCount

Returns the number of CSid objects contained in CTokenGroups.

UINT GetCount() const throw();

Return Value

Returns the number of CSid objects and their associated attributes contained in the CTokenGroups object.

CTokenGroups::GetLength

Returns the size of the CTokenGroup object.

UINT GetLength() const throw();

Remarks

Returns the total size of the CTokenGroup object, in bytes.

CTokenGroups::GetPTOKEN_GROUPS

Retrieves a pointer to the TOKEN_GROUPS structure.

const TOKEN_GROUPS* GetPTOKEN_GROUPS() const throw(...);

Return Value

Retrieves a pointer to the TOKEN_GROUPS structure belonging to the CTokenGroups access token object.

CTokenGroups::GetSidsAndAttributes

Retrieves the CSid objects and (optionally) the attributes belonging to the CTokenGroups object.

void GetSidsAndAttributes(
    CSid::CSidArray* pSids,
    CAtlArray<DWORD>* pAttributes = NULL) const throw(...);

Parameters

pSids
Pointer to an array of CSid objects.

pAttributes
Pointer to an array of DWORDs. If this parameter is omitted or NULL, the attributes are not retrieved.

Remarks

This method will enumerate all of the CSid objects contained in the CTokenGroups object and place them and (optionally) the attribute flags into array objects.

CTokenGroups::LookupSid

Retrieves the attributes associated with a CSid object.

bool LookupSid(
    const CSid& rSid,
    DWORD* pdwAttributes = NULL) const throw();

Parameters

rSid
The CSid object.

pdwAttributes
Pointer to a DWORD which will accept the CSid object's attribute. If omitted or NULL, the attribute will not be retrieved.

Return Value

Returns true if the CSid is found, false otherwise.

Remarks

Setting pdwAttributes to NULL provides a way of confirming the existence of the CSid without accessing the attribute. Note that this method should not be used to check access rights. Applications should instead use the CAccessToken::CheckTokenMembership method.

CTokenGroups::operator =

Assignment operator.

CTokenGroups& operator= (const TOKEN_GROUPS& rhs) throw(...);
CTokenGroups& operator= (const CTokenGroups& rhs) throw(...);

Parameters

rhs
The CTokenGroups object or TOKEN_GROUPS structure to assign to the CTokenGroups object.

Return Value

Returns the updated CTokenGroups object.

CTokenGroups::operator const TOKEN_GROUPS *

Casts a value to a pointer to the TOKEN_GROUPS structure.

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

Remarks

Casts a value to a pointer to the TOKEN_GROUPS structure.

See also

Security Sample
CSid Class
Class Overview
Security Global Functions