CTokenGroups Class

 

This class is a wrapper for the TOKEN_GROUPS structure.

System_CAPS_ICON_important.jpg Important

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

class CTokenGroups

Public Constructors

NameDescription
CTokenGroups::CTokenGroupsThe constructor.
CTokenGroups::~CTokenGroupsThe destructor.

Public Methods

NameDescription
CTokenGroups::AddAdds a CSid or existing TOKEN_GROUPS structure to the CTokenGroups object.
CTokenGroups::DeleteDeletes a CSid and its associated attributes from the CTokenGroups object.
CTokenGroups::DeleteAllDeletes all CSid objects and their associated attributes from the CTokenGroups object.
CTokenGroups::GetCountReturns the number of CSid objects and associated attributes contained in the CTokenGroups object.
CTokenGroups::GetLengthReturns the size of the CTokenGroups object.
CTokenGroups::GetPTOKEN_GROUPSRetrieves a pointer to the TOKEN_GROUPS structure.
CTokenGroups::GetSidsAndAttributesRetrieves the CSid objects and attributes belonging to the CTokenGroups object.
CTokenGroups::LookupSidRetrieves the attributes associated with a CSid object.

Public Operators

NameDescription
CTokenGroups::operator const TOKEN_GROUPS *Casts the CTokenGroups object to a pointer to the TOKEN_GROUPS structure.
CTokenGroups::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 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(...);

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.

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.

The destructor.

virtual ~CTokenGroups() throw();

Remarks

The destructor frees all allocated resources.

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.

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

Return Value

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

Remarks

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

Return Value

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

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.

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 as incorrect results may occur under Windows 2000. Applications should instead use the CAccessToken::CheckTokenMembership method.

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.

Casts a value to a pointer to the TOKEN_GROUPS structure.

Remarks

Casts a value to a pointer to the TOKEN_GROUPS structure.

Security Sample
CSid Class
Class Overview
Security Global Functions

Show: