CSecurityDesc 类
此类是 SECURITY_DESCRIPTOR 结构的包装器。
重要
无法在 Windows 运行时中执行的应用程序中使用此类及其成员。
语法
class CSecurityDesc
成员
公共构造函数
| 名称 | 描述 |
|---|---|
| CSecurityDesc::CSecurityDesc | 构造函数。 |
| CSecurityDesc::~CSecurityDesc | 析构函数。 |
公共方法
公共运算符
| “属性” | 描述 |
|---|---|
| CSecurityDesc::operator const SECURITY_DESCRIPTOR * | 返回指向 SECURITY_DESCRIPTOR 结构的指针。 |
| CSecurityDesc::operator = | 赋值运算符。 |
备注
SECURITY_DESCRIPTOR 结构包含与对象关联的安全信息。 应用程序使用此结构来设置和查询对象的安全状态。 另请参阅 AtlGetSecurityDescriptor。
应用程序不应直接修改 SECURITY_DESCRIPTOR 结构，而应使用提供的类方法。
有关 Windows 中访问控制模型的简介，请参阅 Windows SDK 中的访问控制。
要求
标头： atlsecurity.h
CSecurityDesc::CSecurityDesc
构造函数。
CSecurityDesc() throw();
CSecurityDesc(const CSecurityDesc& rhs) throw(... );
CSecurityDesc(const SECURITY_DESCRIPTOR& rhs) throw(...);
参数
rhs
要分配到新 CSecurityDesc 对象的 CSecurityDesc 对象或 SECURITY_DESCRIPTOR 结构。
注解
可以选择使用 SECURITY_DESCRIPTOR 结构或以前定义的 CSecurityDesc 对象创建 CSecurityDesc 对象。
CSecurityDesc::~CSecurityDesc
析构函数。
virtual ~CSecurityDesc() throw();
备注
析构函数释放所有已分配的资源。
CSecurityDesc::FromString
将字符串格式安全描述符转换为有效的功能安全描述符。
bool FromString(LPCTSTR pstr) throw(...);
参数
pstr
指向以 null 结尾的字符串的指针，该字符串包含要转换的字符串格式安全描述符。
返回值
成功时返回 true。 失败时引发异常。
备注
可以使用 CSecurityDesc::ToString 创建字符串。 将安全描述符转换为字符串可以更方便地存储和传输。
此方法调用 ConvertStringSecurityDescriptorToSecurityDescriptor。
CSecurityDesc::GetControl
从安全描述符中检索控制信息。
bool GetControl(SECURITY_DESCRIPTOR_CONTROL* psdc) const throw();
参数
psdc
指向接收安全描述符的控制信息的 SECURITY_DESCRIPTOR_CONTROL 结构的指针。
返回值
如果该方法成功，则返回 true，如果失败则返回 false。
备注
此方法调用 GetSecurityDescriptorControl。
CSecurityDesc::GetDacl
从安全描述符中检索自由访问控制列表 (DACL) 信息。
bool GetDacl(
CDacl* pDacl,
bool* pbPresent = NULL,
bool* pbDefaulted = NULL) const throw(...);
参数
pDacl
指向用于存储安全描述符的 DACL 副本的 CDacl 结构的指针。 如果存在自由 ACL，则该方法会将 pDacl 设置为安全描述符的自由 ACL 的地址。 如果不存在自由 ACL，则不存储任何值。
pbPresent
指向一个值的指针，该值指示指定的安全描述符中是否存在自由 ACL。 如果安全描述符包含自由 ACL，则此参数将设置为 true。 如果安全描述符不包含自由 ACL，则此参数将设置为 false。
pbDefaulted
如果安全描述符存在自由 ACL，则为指向一个标志的指针，该标志设置为 SECURITY_DESCRIPTOR_CONTROL 结构中 SE_DACL_DEFAULTED 标志的值。 如果此标志为 true，则自由 ACL 由默认机制检索；如果为 false，则自由 ACL 由用户显式指定。
返回值
如果该方法成功，则返回 true，如果失败则返回 false。
CSecurityDesc::GetGroup
从安全描述符中检索主要组信息。
bool GetGroup(
CSid* pSid,
bool* pbDefaulted = NULL) const throw(...);
参数
pSid
指向接收 CDacl 中存储的组副本的 CSid（安全标识符）的指针。
pbDefaulted
方法返回时指向一个标志的指针，该标志设置为 SECURITY_DESCRIPTOR_CONTROL 结构中 SE_GROUP_DEFAULTED 标志的值。
返回值
如果该方法成功，则返回 true，如果失败则返回 false。
CSecurityDesc::GetOwner
从安全描述符中检索所有者信息。
bool GetOwner(
CSid* pSid,
bool* pbDefaulted = NULL) const throw(...);
参数
pSid
指向接收 CDacl 中存储的组副本的 CSid（安全标识符）的指针。
pbDefaulted
方法返回时指向一个标志的指针，该标志设置为 SECURITY_DESCRIPTOR_CONTROL 结构中 SE_OWNER_DEFAULTED 标志的值。
返回值
如果该方法成功，则返回 true，如果失败则返回 false。
CSecurityDesc::GetPSECURITY_DESCRIPTOR
返回指向 SECURITY_DESCRIPTOR 结构的指针。
const SECURITY_DESCRIPTOR* GetPSECURITY_DESCRIPTOR() const throw();
返回值
返回指向 SECURITY_DESCRIPTOR 结构的指针。
CSecurityDesc::GetSacl
从安全描述符中检索系统访问控制列表 (SACL) 信息。
bool GetSacl(
CSacl* pSacl,
bool* pbPresent = NULL,
bool* pbDefaulted = NULL) const throw(...);
参数
pSacl
指向用于存储安全描述符的 SACL 副本的 CSacl 结构的指针。 如果系统 ACL 存在，则该方法会将 pSacl 设置为安全描述符的系统 ACL 的地址。 如果系统 ACL 不存在，则不存储任何值。
pbPresent
指向方法设置的标志的指针，以指示指定的安全描述符中是否存在系统 ACL。 如果安全描述符包含系统 ACL，则此参数将设置为 true。 如果安全描述符不包含系统 ACL，则此参数将设置为 false。
pbDefaulted
如果安全描述符存在系统 ACL，则为指向一个标志的指针，该标志设置为 SECURITY_DESCRIPTOR_CONTROL 结构中 SE_SACL_DEFAULTED 标志的值。
返回值
如果该方法成功，则返回 true，如果失败则返回 false。
CSecurityDesc::IsDaclAutoInherited
确定自由访问控制列表 (DACL) 是否配置为支持自动传播。
bool IsDaclAutoInherited() const throw();
返回值
如果安全描述符包含设置为支持将可继承访问控制条目 (ACE) 自动传播到现有子对象的 DACL，则返回 true。 否则，返回 false。
备注
系统在执行对象及其现有子对象的自动继承算法时设置此位。
CSecurityDesc::IsDaclDefaulted
确定是否为安全描述符配置了默认的自由访问控制列表 (DACL)。
bool IsDaclDefaulted() const throw();
返回值
如果安全描述符包含默认 DACL，则返回 true，否则返回 false。
注解
此标志可能影响系统处理 DACL 的访问控制条目 (ACE) 继承方面的方式。 例如，如果某个对象的创建者未指定 DACL，则该对象会从创建者的访问令牌接收默认 DACL。 如果未设置 SE_DACL_PRESENT 标志，系统将忽略此标志。
此标志用于确定如何计算对象的最终 DACL，而不会以物理方式存储在安全对象的安全描述符控制机制中。
若要设置此标志，请使用 CSecurityDesc::SetDacl 方法。
CSecurityDesc::IsDaclPresent
确定安全描述符是否包含自由访问控制列表 (DACL)。
bool IsDaclPresent() const throw();
返回值
如果安全描述符包含 DACL，则返回 true，否则返回 false。
注解
如果未设置此标志，或者设置了此标志但 DACL 为 NULL，则安全描述符允许任何人进行全权访问。
此标志用于保存调用方指定的安全信息，直到安全描述符与安全对象相关联。 将安全描述符与安全对象关联后，始终会在安全描述符控制机制中设置 SE_DACL_PRESENT 标志。
若要设置此标志，请使用 CSecurityDesc::SetDacl 方法。
CSecurityDesc::IsDaclProtected
确定是否将自由访问控制列表 (DACL) 配置为防修改。
bool IsDaclProtected() const throw();
返回值
如果 DACL 配置为防止可继承访问控制条目 (ACE) 修改安全描述符，则返回 true。 否则，返回 false。
注解
若要设置此标志，请使用 CSecurityDesc::SetDacl 方法。
此方法支持自动传播可继承 ACE。
CSecurityDesc::IsGroupDefaulted
确定是否默认设置了安全描述符的组安全标识符 (SID)。
bool IsGroupDefaulted() const throw();
返回值
如果默认机制（而不是安全描述符的原始提供者）提供了安全描述符的组 SID，则返回 true。 否则，返回 false。
注解
若要设置此标志，请使用 CSecurityDesc::SetGroup 方法。
CSecurityDesc::IsOwnerDefaulted
确定是否默认设置了安全描述符的所有者安全标识符 (SID)。
bool IsOwnerDefaulted() const throw();
返回值
如果默认机制（而不是安全描述符的原始提供者）提供了安全描述符的所有者 SID，则返回 true。 否则，返回 false。
备注
若要设置此标志，请使用 CSecurityDesc::SetOwner 方法。
CSecurityDesc::IsSaclAutoInherited
确定系统访问控制列表 (SACL) 是否配置为支持自动传播。
bool IsSaclAutoInherited() const throw();
返回值
如果安全描述符包含设置为支持将可继承访问控制条目 (ACE) 自动传播到现有子对象的 SACL，则返回 true。 否则，返回 false。
备注
系统在执行对象及其现有子对象的自动继承算法时设置此位。
CSecurityDesc::IsSaclDefaulted
确定是否为安全描述符配置了默认的系统访问控制列表 (SACL)。
bool IsSaclDefaulted() const throw();
返回值
如果安全描述符包含默认 SACL，则返回 true，否则返回 false。
备注
此标志可能影响系统处理 SACL 的访问控制条目 (ACE) 继承方面的方式。 如果未设置 SE_SACL_PRESENT 标志，系统将忽略此标志。
若要设置此标志，请使用 CSecurityDesc::SetSacl 方法。
CSecurityDesc::IsSaclPresent
确定安全描述符是否包含系统访问控制列表 (SACL)。
bool IsSaclPresent() const throw();
返回值
如果安全描述符包含 SACL，则返回 true，否则返回 false。
注解
若要设置此标志，请使用 CSecurityDesc::SetSacl 方法。
CSecurityDesc::IsSaclProtected
确定是否将系统访问控制列表 (SACL) 配置为防修改。
bool IsSaclProtected() const throw();
返回值
如果 SACL 配置为防止可继承访问控制条目 (ACE) 修改安全描述符，则返回 true。 否则，返回 false。
备注
若要设置此标志，请使用 CSecurityDesc::SetSacl 方法。
此方法支持自动传播可继承 ACE。
CSecurityDesc::IsSelfRelative
确定安全描述符是否采用自我相对格式。
bool IsSelfRelative() const throw();
返回值
如果安全描述符采用自我相对格式，并且所有安全信息存储在连续内存块中，则返回 true。 如果安全描述符采用绝对格式，则返回 false。 有关详细信息，请参阅绝对和自我相对安全描述符。
CSecurityDesc::MakeAbsolute
调用此方法可将安全描述符转换为绝对格式。
bool MakeAbsolute() throw(...);
返回值
如果该方法成功，则返回 true，否则返回 false。
注解
采用绝对格式的安全描述符包含指向它所包含的信息的指针，而不是信息本身。 采用自我相对格式的安全描述符包含连续内存块中的信息。 在自我相对安全描述符中，SECURITY_DESCRIPTOR 结构始终是信息的开头部分，但安全描述符的其他组成部分能够以任意顺序接在该结构的后面。 自我相对安全描述符的组成部分不使用内存地址，而是由安全描述符开头的偏移来标识。 当安全描述符必须存储在磁盘上或通过通信协议传输时，这种格式很有用。 有关详细信息，请参阅绝对和自我相对安全描述符。
CSecurityDesc::MakeSelfRelative
调用此方法可将安全描述符转换为自我相对格式。
bool MakeSelfRelative() throw(...);
返回值
如果该方法成功，则返回 true，否则返回 false。
备注
采用绝对格式的安全描述符包含指向它所包含的信息的指针，而不是包含信息本身。 采用自我相对格式的安全描述符包含连续内存块中的信息。 在自我相对安全描述符中，SECURITY_DESCRIPTOR 结构始终是信息的开头部分，但安全描述符的其他组成部分能够以任意顺序接在该结构的后面。 安全描述符的组成部分不使用内存地址，而是由安全描述符开头的偏移来标识。 当安全描述符必须存储在磁盘上或通过通信协议传输时，这种格式很有用。 有关详细信息，请参阅绝对和自我相对安全描述符。
CSecurityDesc::operator =
赋值运算符。
CSecurityDesc& operator= (const SECURITY_DESCRIPTOR& rhs) throw(...);
CSecurityDesc& operator= (const CSecurityDesc& rhs) throw(...);
参数
rhs
要分配到 CSecurityDesc 对象的 SECURITY_DESCRIPTOR 结构或 CSecurityDesc 对象。
返回值
返回更新的 CSecurityDesc 对象。
CSecurityDesc::operator const SECURITY_DESCRIPTOR *
将值强制转换为指向 SECURITY_DESCRIPTOR 结构的指针。
operator const SECURITY_DESCRIPTOR *() const throw();
CSecurityDesc::SetControl
设置安全说明符的控制位。
bool SetControl(
SECURITY_DESCRIPTOR_CONTROL ControlBitsOfInterest,
SECURITY_DESCRIPTOR_CONTROL ControlBitsToSet) throw();
参数
ControlBitsOfInterest
指示要设置的控制位的 SECURITY_DESCRIPTOR_CONTROL 掩码。 有关可设置的标志的列表，请参阅 SetSecurityDescriptorControl。
ControlBitsToSet
一个 SECURITY_DESCRIPTOR_CONTROL 掩码，指示 ControlBitsOfInterest 掩码指定的控制位的新值。 此参数可以是为 ControlBitsOfInterest 参数列出的标志的组合。
返回值
如果成功，则返回 true；如果失败，则返回 false。
备注
此方法调用 SetSecurityDescriptorControl。
CSecurityDesc::SetDacl
在自由访问控制列表 (DACL) 中设置信息。 如果安全描述符中已存在一个 DACL，则将其替换。
inline void SetDacl(
bool bPresent = true,
bool bDefaulted = false) throw(...);
inline void SetDacl(
const CDacl& Dacl,
bool bDefaulted = false) throw(...);
参数
Dacl
对 CDacl 对象的引用，该对象指定安全描述符的 DACL。 此参数不能为 NULL。 若要在安全描述符中设置 NULL DACL，应使用该方法的第一种形式并将 bPresent 设置为 false。
bPresent
指定一个标志用于指示安全描述符中是否存在 DACL。 如果此参数为 true，则该方法会在 SECURITY_DESCRIPTOR_CONTROL 结构中设置 SE_DACL_PRESENT 标志，并使用 Dacl 和 bDefaulted 参数中的值。 如果为 false，则该方法会清除 SE_DACL_PRESENT 标志，并忽略 bDefaulted。
bDefaulted
指定一个标志用于指示 DACL 的源。 如果此标志为 true，则已通过某种默认机制检索 DACL。 如果为 false，则 DACL 已由用户显式指定。 该方法将此值存储在 SECURITY_DESCRIPTOR_CONTROL 结构的 SE_DACL_DEFAULTED 标志中。 如果未指定此参数，则会清除 SE_DACL_DEFAULTED 标志。
返回值
如果成功，则返回 true；如果失败，则返回 false。
备注
空的和不存在的 DACL 之间存在一个重要差别。 当 DACL 为空时，它不包含访问控制条目，且未为它显式授予访问权限。 因此会隐式拒绝访问对象。 另一方面，当某个对象没有 DACL 时，将不会为该对象分配保护，并且会授予任何访问请求。
CSecurityDesc::SetGroup
设置绝对格式安全描述符的主要组信息，并替换已存在的任何主要组信息。
bool SetGroup(const CSid& Sid, bool bDefaulted = false) throw(...);
参数
Sid
对安全描述符的新主要组的 CSid 对象的引用。 此参数不能为 NULL。 安全描述符可以标记为没有 DACL 或 SACL，但它必须有一个组和一个所有者，即使它的 SID（具有特殊含义的内置 SID）为 NULL。
bDefaulted
指示主要组信息是否派生自默认机制。 如果此值为 true，则主要组信息是默认信息，该方法会将此值作为 SE_GROUP_DEFAULTED 标志存储在 SECURITY_DESCRIPTOR_CONTROL 结构中。 如果此参数为零，则会清除 SE_GROUP_DEFAULTED 标志。
返回值
如果成功，则返回 true；如果失败，则返回 false。
CSecurityDesc::SetOwner
设置绝对格式安全描述符的所有者信息。 它会替换已存在的任何所有者信息。
bool SetOwner(const CSid& Sid, bool bDefaulted = false) throw(...);
参数
Sid
安全描述符的新主要所有者的 CSid 对象。 此参数不能为 NULL。
bDefaulted
指示所有者信息是否派生自默认机制。 如果此值为 true，则所有者信息为默认信息。 该方法将此值作为 SE_OWNER_DEFAULTED 标志存储在 SECURITY_DESCRIPTOR_CONTROL 结构中。 如果此参数为零，则会清除 SE_OWNER_DEFAULTED 标志。
返回值
如果成功，则返回 true；如果失败，则返回 false。
CSecurityDesc::SetSacl
在系统访问控制列表 (SACL) 中设置信息。 如果安全描述符中已存在一个 SACL，则将其替换。
bool SetSacl(const CSacl& Sacl, bool bDefaulted = false) throw(...);
参数
Sacl
指向用于为安全描述符指定 SACL 的 CSacl 对象的指针。 此参数不能为 NULL，并且必须是 CSacl 对象。 与 DACL 不同，NULL 和空 SACL 之间没有差别，因为 SACL 对象不指定访问权限，而只指定审核信息。
bDefaulted
指定一个标志用于指示 SACL 的源。 如果此标志为 true，则已通过某种默认机制检索 SACL。 如果为 false，则 SACL 已由用户显式指定。 该方法将此值存储在 SECURITY_DESCRIPTOR_CONTROL 结构的 SE_SACL_DEFAULTED 标志中。 如果未指定此参数，则会清除 SE_SACL_DEFAULTED 标志。
返回值
如果成功，则返回 true；如果失败，则返回 false。
CSecurityDesc::ToString
将安全描述符转换为字符串格式。
bool ToString(
CString* pstr, SECURITY_INFORMATION si = OWNER_SECURITY_INFORMATION |
GROUP_SECURITY_INFORMATION | DACL_SECURITY_INFORMATION |
SACL_SECURITY_INFORMATION) const throw(...);
参数
pstr
指向以 null 结尾的字符串的指针，该字符串将接收字符串格式安全描述符。
si
指定 SECURITY_INFORMATION 位标志的组合，指示要包含在输出字符串中的安全描述符的组成部分。
返回值
如果成功，则返回 true；如果失败，则返回 false。
备注
安全描述符采用字符串格式后，可以更方便地存储或传输它。 使用 CSecurityDesc::FromString 方法将字符串转换回安全描述符。
si 参数可包含以下 SECURITY_INFORMATION 标志：
| 值 | 含义 |
|---|---|
| OWNER_SECURITY_INFORMATION | 包括所有者。 |
| GROUP_SECURITY_INFORMATION | 包括主要组。 |
| DACL_SECURITY_INFORMATION | 包括 DACL。 |
| SACL_SECURITY_INFORMATION | 包括 SACL。 |
如果 DACL 为 NULL 并且在输入安全描述符中设置了 SE_DACL_PRESENT 控制位，则该方法将会失败。
如果 DACL 为 NULL 并且未在输入安全描述符中设置 SE_DACL_PRESENT 控制位，则生成的安全描述符字符串没有 D: 组成部分。 有关更多详细信息，请参阅安全描述符字符串格式。
此方法调用 ConvertStringSecurityDescriptorToSecurityDescriptor。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈