This class is a wrapper for the TOKEN_GROUPS structure.

class CTokenGroups

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.

Header: atlsecurity.h

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(...);

rSid
A CSid object.

dwAttributes
The attributes to associate with the CSid object.

rTokenGroups
A TOKEN_GROUPS structure.

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

The constructor.

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

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

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

The destructor.

virtual ~CTokenGroups() throw();

The destructor frees all allocated resources.

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

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

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

Returns true if the CSid is removed, false otherwise.

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

void DeleteAll() throw();

Returns the number of CSid objects contained in CTokenGroups.

UINT GetCount() const throw();

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

Returns the size of the CTokenGroup object.

UINT GetLength() const throw();

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

Retrieves a pointer to the TOKEN_GROUPS structure.

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

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

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

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

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.

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.

Retrieves the attributes associated with a CSid object.

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

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.

Returns true if the CSid is found, false otherwise.

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.

Assignment operator.

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

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

Returns the updated CTokenGroups object.

Casts a value to a pointer to the TOKEN_GROUPS structure.

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

Casts a value to a pointer to the TOKEN_GROUPS structure.

Security Sample
CSid Class
Class Overview
Security Global Functions