CSid 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 CSid Class.

This class is a wrapper for a SID (security identifier) structure.

System_CAPS_ICON_important.jpg Important

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

class CSid

Public Typedefs

NameDescription
CSid::CSidArrayAn array of CSid objects.

Public Constructors

NameDescription
CSid::CSidThe constructor.
CSid::~CSidThe destructor.

Public Methods

NameDescription
CSid::AccountNameReturns the name of the account associated with the CSid object.
CSid::DomainReturns the name of the domain associated with the CSid object.
CSid::EqualPrefixTests SID (security identifier) prefixes for equality.
CSid::GetLengthReturns the length of the CSid object.
CSid::GetPSIDReturns a pointer to a SID structure.
CSid::GetPSID_IDENTIFIER_AUTHORITYReturns a pointer to the SID_IDENTIFIER_AUTHORITY structure.
CSid::GetSubAuthorityReturns a specified subauthority in a SID structure.
CSid::GetSubAuthorityCountReturns the subauthority count.
CSid::IsValidTests the CSid object for validity.
CSid::LoadAccountUpdates the CSid object given the account name and domain, or an existing SID structure.
CSid::SidReturns the ID string.
CSid::SidNameUseReturns a description of the state of the CSid object.

Operators

operator =Assignment operator.
operator const SID *Casts a CSid object to a pointer to a SID structure.

Global Operators

operator ==Tests two security descriptor objects for equality
operator !=Tests two security descriptor objects for inequality
operator <Compares relative value of two security descriptor objects.
operator >Compares relative value of two security descriptor objects.
operator <=Compares relative value of two security descriptor objects.
operator >=Compares relative value of two security descriptor objects.

The SID structure is a variable-length structure used to uniquely identify users or groups.

Applications should not modify the SID structure directly, but instead use the methods provided in this wrapper class. See also AtlGetOwnerSid, AtlSetGroupSid, AtlGetGroupSid, and AtlSetOwnerSid.

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

Header: atlsecurity.h

Returns the name of the account associated with the CSid object.

LPCTSTR AccountName() const throw(...);

Return Value

Returns the LPCTSTR pointing to the name of the account.

Remarks

This method attempts to find a name for the specified SID (security identifier). For full details, see LookupAccountSid.

If no account name for the SID can be found, AccountName returns an empty string. This can occur if a network timeout prevents this method from finding the name. It also occurs for security identifiers with no corresponding account name, such as a logon SID that identifies a logon session.

The constructor.

CSid() throw();
CSid(const SID& rhs) throw(...);
CSid(const CSid& rhs) throw(...);

CSid(
    const SID_IDENTIFIER_AUTHORITY& IdentifierAuthority,
    BYTE nSubAuthorityCount,
    ...) throw(...);

explicit CSid(
    LPCTSTR pszAccountName,
    LPCTSTR pszSystem = NULL) throw(...);

explicit CSid(
    const SID* pSid,
    LPCTSTR pszSystem = NULL) throw(...);

Parameters

rhs
An existing CSid object or SID (security identifier) structure.

IdentifierAuthority
The authority.

nSubAuthorityCount
The subauthority count.

pszAccountName
The account name.

pszSystem
The system name. This string can be the name of a remote computer. If this string is NULL, the local system is used instead.

pSid
A pointer to a SID structure.

Remarks

The constructor initializes the CSid object, setting an internal data member to SidTypeInvalid, or by copying the settings from an existing CSid, SID, or existing account.

If initialization fails, the constructor will throw a CAtlException Class.

The destructor.

virtual ~CSid() throw();

Remarks

The destructor frees any resources acquired by the object.

An array of CSid objects.

typedef CAtlArray<CSid> CSidArray;

Remarks

This typedef specifies the array type that can be used to retrieve security identifiers from an ACL (access-control list). See CAcl::GetAclEntries.

Returns the name of the domain associated with the CSid object.

LPCTSTR Domain() const throw(...);

Return Value

Returns the LPCTSTR pointing to the domain.

Remarks

This method attempts to find a name for the specified SID (security identifier). For full details, see LookupAccountSid.

If no account name for the SID can be found, Domain returns the domain as an empty string. This can occur if a network timeout prevents this method from finding the name. It also occurs for security identifiers with no corresponding account name, such as a logon SID that identifies a logon session.

Tests SID (security identifier) prefixes for equality.

bool EqualPrefix(const SID& rhs) const throw();
bool EqualPrefix(const CSid& rhs) const throw();

Parameters

rhs
The SID (security identifier) structure or CSid object to compare.

Return Value

Returns true on success, false on failure.

Remarks

See EqualPrefixSid in the Windows SDK for more details.

Returns the length of the CSid object.

UINT GetLength() const throw();

Return Value

Returns the length in bytes of the CSid object.

Remarks

If the CSid structure is not valid, the return value is undefined. Before calling GetLength, use the CSid::IsValid member function to verify that CSid is valid.

System_CAPS_ICON_note.jpg Note

Under debug builds the function will cause an ASSERT if the CSid object is not valid.

Returns a pointer to a SID (security identifier) structure.

const SID* GetPSID() const throw(...);

Return Value

Returns the address of the CSid object's underlying SID structure.

Returns a pointer to the SID_IDENTIFIER_AUTHORITY structure.

const SID_IDENTIFIER_AUTHORITY* GetPSID_IDENTIFIER_AUTHORITY() const throw();

Return Value

If the method succeeds, it returns the address of the SID_IDENTIFIER_AUTHORITY structure. If it fails, the return value is undefined. Failure may occur if the CSid object is not valid, in which case the CSid::IsValid method returns false. The function GetLastError can be called for extended error information.

System_CAPS_ICON_note.jpg Note

Under debug builds the function will cause an ASSERT if the CSid object is not valid.

Returns a specified subauthority in a SID (security identifier) structure.

DWORD GetSubAuthority(DWORD nSubAuthority) const throw();

Parameters

nSubAuthority
The subauthority.

Return Value

Returns the subauthority referenced by nSubAuthority. The subauthority value is a relative identifier (RID).

Remarks

The nSubAuthority parameter specifies an index value identifying the subauthority array element the method will return. The method performs no validation tests on this value. An application can call CSid::GetSubAuthorityCount to discover the range of acceptable values.

System_CAPS_ICON_note.jpg Note

Under debug builds the function will cause an ASSERT if the CSid object is not valid.

Returns the subauthority count.

UCHAR GetSubAuthorityCount() const throw();

Return Value

If the method succeeds, the return value is the subauthority count.

If the method fails, the return value is undefined. The method fails if the CSid object is invalid. To get extended error information, call GetLastError.

System_CAPS_ICON_note.jpg Note

Under debug builds the function will cause an ASSERT if the CSid object is not valid.

Tests the CSid object for validity.

bool IsValid() const throw();

Return Value

Returns true if the CSid object is valid, false if not. There is no extended error information for this method; do not call GetLastError.

Remarks

The IsValid method validates the CSid object by verifying that the revision number is within a known range and that the number of subauthorities is less than the maximum.

Updates the CSid object given the account name and domain, or an existing SID (security identifier) structure.

bool LoadAccount(
    LPCTSTR pszAccountName,
    LPCTSTR pszSystem = NULL) throw(...);

bool LoadAccount(
    const SID* pSid,
    LPCTSTR pszSystem = NULL) throw(...);

Parameters

pszAccountName
The account name.

pszSystem
The system name. This string can be the name of a remote computer. If this string is NULL, the local system is used instead.

pSid
A pointer to a SID structure.

Return Value

Returns true on success, false on failure. To get extended error information, call GetLastError.

Remarks

LoadAccount attempts to find a security identifier for the specified name. See LookupAccountSid for more details.

Assignment operator.

CSid& operator= (const CSid& rhs) throw(...);  
CSid& operator= (const SID& rhs) throw(...);

Parameters

rhs
The SID (security identifier) or CSid to assign to the CSid object.

Return Value

Returns a reference to the updated CSid object.

Tests two security descriptor objects for equality.

bool operator==(const CSid& lhs, const CSid& rhs) throw(); 

Parameters

lhs
The SID (security identifier) or CSid that appears on the left side of the == operator.

rhs
The SID (security identifier) or CSid that appears on the right side of the == operator.

Return Value

true if the security descriptors are equal, otherwise false.

Tests two security descriptor objects for inequality.

bool operator!=(
    const CSid& lhs,
    const CSid& rhs) throw();

Parameters

lhs
The SID (security identifier) or CSid that appears on the left side of the != operator.

rhs
The SID (security identifier) or CSid that appears on the right side of the != operator.

Return Value

true if the security descriptors are not equal, otherwise false.

Compares relative value of two security descriptor objects.

bool operator<(const CSid& lhs, const CSid& rhs) throw(); 

Parameters

lhs
The SID (security identifier) or CSid that appears on the left side of the != operator.

rhs
The SID (security identifier) or CSid that appears on the right side of the != operator.

Return Value

true if lhs is less than rhs, otherwise false.

Compares relative value of two security descriptor objects.

bool operator<(const CSid& lhs, const CSid& rhs) throw(); 

Parameters

lhs
The SID (security identifier) or CSid that appears on the left side of the != operator.

rhs
The SID (security identifier) or CSid that appears on the right side of the != operator.

Return Value

true if lhs is less than or equal to rhs, otherwise false.

Compares relative value of two security descriptor objects.

bool operator<(const CSid& lhs, const CSid& rhs) throw(); 

Parameters

lhs
The SID (security identifier) or CSid that appears on the left side of the != operator.

rhs
The SID (security identifier) or CSid that appears on the right side of the != operator.

Return Value

true if lhs is greater than rhs, otherwise false.

Compares relative value of two security descriptor objects.

bool operator<(
    const CSid& lhs,
    const CSid& rhs) throw());

Parameters

lhs
The SID (security identifier) or CSid that appears on the left side of the != operator.

rhs
The SID (security identifier) or CSid that appears on the right side of the != operator.

Return Value

true if lhs is greater than or equal to rhs, otherwise false.

Casts a CSid object to a pointer to a SID (security identifier) structure.

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

Remarks

Returns the address of the SID structure.

Returns the SID (security identifier) structure as a string.

LPCTSTR Sid() const throw(...);

Return Value

Returns the SID structure as a string in a format suitable for display, storage, or transmission. Equivalent to ConvertSidToStringSid, although this function is only available on Windows 2000 or later and so is emulated for earlier operating systems.

Returns a description of the state of the CSid object.

SID_NAME_USE SidNameUse() const throw();

Return Value

Returns the value of the data member that stores a value describing the state of the CSid object.

ValueDescription
SidTypeUserIndicates a user SID (security identifier).
SidTypeGroupIndicates a group SID.
SidTypeDomainIndicates a domain SID.
SidTypeAliasIndicates an alias SID.
SidTypeWellKnownGroupIndicates a SID for a well-known group.
SidTypeDeletedAccountIndicates a SID for a deleted account.
SidTypeInvalidIndicates an invalid SID.
SidTypeUnknownIndicates an unknown SID type.
SidTypeComputerIndicates a SID for a computer.

Remarks

Call CSid::LoadAccount to update the CSid object before calling SidNameUse to return its state. SidNameUse does not change the state of the object (by calling to LookupAccountName or LookupAccountSid), but only returns the current state.

Security Sample
Class Overview
Security Global Functions
Operators

Show: