Edit

CSid class

  • Article

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

Important

This class and its members can't be used in applications that execute in the Windows Runtime.

Syntax

class CSid;

Members

Public typedefs

Name Description
CSid::CSidArray An array of CSid objects.

Public constructors

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

Public methods

Name Description
CSid::AccountName Returns the name of the account associated with the CSid object.
CSid::Domain Returns the name of the domain associated with the CSid object.
CSid::EqualPrefix Tests SID (security identifier) prefixes for equality.
CSid::GetLength Returns the length of the CSid object.
CSid::GetPSID Returns a pointer to a SID structure.
CSid::GetPSID_IDENTIFIER_AUTHORITY Returns a pointer to the SID_IDENTIFIER_AUTHORITY structure.
CSid::GetSubAuthority Returns a specified subauthority in a SID structure.
CSid::GetSubAuthorityCount Returns the subauthority count.
CSid::IsValid Tests the CSid object for validity.
CSid::LoadAccount Updates the CSid object given the account name and domain, or an existing SID structure.
CSid::Sid Returns the ID string.
CSid::SidNameUse Returns a description of the state of the CSid object.

Operators

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

Global Operators

Name Description
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.

Remarks

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

Applications shouldn't 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.

Requirements

Header: atlsecurity.h

CSid::AccountName

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 result 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 an SID that identifies a sign-in session.

CSid::CSid

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.

CSid::~CSid

The destructor.

virtual ~CSid() throw();

Remarks

The destructor frees any resources acquired by the object.

CSid::CSidArray

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.

CSid::Domain

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 result 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 an SID that identifies a sign-in session.

CSid::EqualPrefix

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

For more information, see EqualPrefixSid.

CSid::GetLength

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 isn't valid, the return value is undefined. Before calling GetLength, use the CSid::IsValid member function to verify that CSid is valid.

Note

Under debug builds the function will cause an ASSERT if the CSid object isn't valid.

CSid::GetPSID

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.

CSid::GetPSID_IDENTIFIER_AUTHORITY

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 isn't valid, in which case the CSid::IsValid method returns FALSE. The function GetLastError can be called for extended error information.

Note

Under debug builds the function will cause an ASSERT if the CSid object isn't valid.

CSid::GetSubAuthority

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.

Note

Under debug builds the function will cause an ASSERT if the CSid object isn't valid.

CSid::GetSubAuthorityCount

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.

Note

Under debug builds the function will cause an ASSERT if the CSid object isn't valid.

CSid::IsValid

Tests the CSid object for validity.

bool IsValid() const throw();

Return value

Returns TRUE if the CSid object is valid, FALSE if not. There's no extended error information for this method; don't 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.

CSid::LoadAccount

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. For more information, see LookupAccountSid.

CSid::operator =

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.

operator ==

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.

operator !=

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 aren't equal, otherwise FALSE.

operator <

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.

operator <=

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.

operator >

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.

operator >=

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.

CSid::operator const SID *

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

operator const SID *() const;

Remarks

Returns the address of the SID structure.

CSid::Sid

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.

CSid::SidNameUse

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.

Value Description
SidTypeUser Indicates a user SID (security identifier).
SidTypeGroup Indicates a group SID.
SidTypeDomain Indicates a domain SID.
SidTypeAlias Indicates an alias SID.
SidTypeWellKnownGroup Indicates a SID for a well-known group.
SidTypeDeletedAccount Indicates a SID for a deleted account.
SidTypeInvalid Indicates an invalid SID.
SidTypeUnknown Indicates an unknown SID type.
SidTypeComputer Indicates a SID for a computer.

Remarks

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

See also

Security sample
Class overview
Security global functions
Operators