CSecurityDesc 類別

這個類別是 結構的 SECURITY_DESCRIPTOR 包裝函式。

重要

這個類別及其成員不能用於在 Windows 執行階段 中執行的應用程式。

語法

class CSecurityDesc

成員

公用建構函式

名稱	描述
CSecurityDesc：：CSecurityDesc	建構函式。
CSecurityDesc：：~CSecurityDesc	解構函式。

公用方法

名稱	描述
CSecurityDesc：：FromString	將字串格式的安全性描述元轉換成有效的功能安全性描述元。
CSecurityDesc：：GetControl	從安全性描述項擷取控制資訊。
CSecurityDesc：：GetDacl	從安全性描述元擷取任意訪問控制清單 （DACL） 資訊。
CSecurityDesc：：GetGroup	從安全性描述項擷取主要群組資訊。
CSecurityDesc：：GetOwner	從安全性描述項擷取擁有者資訊。
CSecurityDesc：：GetPSECURITY_DESCRIPTOR	傳回 結構的 SECURITY_DESCRIPTOR 指標。
CSecurityDesc：：GetSacl	從安全性描述項擷取系統存取控制清單 （SACL） 資訊。
CSecurityDesc：：IsDaclAutoInherited	判斷 DACL 是否設定為支援自動傳播。
CSecurityDesc：：IsDaclDefaulted	判斷是否使用預設 DACL 設定安全性描述元。
CSecurityDesc：：IsDaclPresent	判斷安全性描述元是否包含 DACL。
CSecurityDesc：：IsDaclProtected	判斷 DACL 是否已設定為防止修改。
CSecurityDesc：：IsGroupDefaulted	判斷安全性描述元的群組安全組識別碼 （SID） 是否預設設定。
CSecurityDesc：：IsOwnerDefaulted	判斷安全性描述元的擁有者 SID 是否預設設定。
CSecurityDesc：：IsSaclAutoInherited	判斷 SACL 是否設定為支援自動傳播。
CSecurityDesc：：IsSaclDefaulted	判斷是否使用預設 SACL 設定安全性描述元。
CSecurityDesc：：IsSaclPresent	判斷安全性描述元是否包含 SACL。
CSecurityDesc：：IsSaclProtected	判斷 SACL 是否已設定為防止修改。
CSecurityDesc：：IsSelfRelative	判斷安全性描述元是否為自我相對格式。
CSecurityDesc：：MakeAbsolute	呼叫這個方法，將安全性描述元轉換成絕對格式。
CSecurityDesc：：MakeSelfRelative	呼叫此方法，將安全性描述元轉換成自我相對格式。
CSecurityDesc：：SetControl	設定安全性描述元的控制位元。
CSecurityDesc：：SetDacl	設定 DACL 中的資訊。 如果 DACL 已存在於安全性描述元中，則會加以取代。
CSecurityDesc：：SetGroup	設定絕對格式安全性描述元的主要群組資訊，並取代任何已經存在的主要群組資訊。
CSecurityDesc：：SetOwner	設定絕對格式安全性描述元的擁有者資訊，並取代任何已經存在的擁有者資訊。
CSecurityDesc：：SetSacl	設定 SACL 中的資訊。 如果 SACL 已存在於安全性描述元中，則會加以取代。
CSecurityDesc：：ToString	將安全性描述元轉換為字串格式。

公用運算子

名稱	描述
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結構。

備註

CSecurityDesc您可以使用 結構或先前定義的 CSecurityDesc 對象，選擇性地建立 SECURITY_DESCRIPTOR 物件。

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
結構指標 CDacl ，在其中儲存安全性描述元 DACL 的複本。 如果存在任意 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
CSid （安全性標識子） 的指標，該標識符會接收儲存在 CDacl 中的群組複本。

pbDefaulted
當方法傳回時，旗標的指標會設定為 結構中 SECURITY_DESCRIPTOR_CONTROL SE_GROUP_DEFAULTED旗標的值。

傳回值

如果方法成功，則傳回 true，如果失敗則傳回 false。

CSecurityDesc：：GetOwner

從安全性描述項擷取擁有者資訊。

bool GetOwner(
    CSid* pSid,
    bool* pbDefaulted = NULL) const throw(...);

參數

pSid
CSid （安全性標識子） 的指標，該標識符會接收儲存在 CDacl 中的群組複本。

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
CSacl結構指標，在其中儲存安全性描述元 SACL 的複本。 如果系統 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();

傳回值

如果安全性描述項包含 DACL，則會傳回 true，此 DACL 設定為支援將可繼承的訪問控制專案自動傳播至現有的子物件。 否則會傳回 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 設定為防止可繼承的訪問控制專案修改安全性描述元，則會傳回 true。 否則會傳回 false。

備註

若要設定此旗標，請使用 CSecurityDesc：：SetDacl 方法。

此方法支援可繼承 ACE 的自動傳播。

CSecurityDesc：：IsGroupDefaulted

判斷安全性描述元的群組安全組識別碼 （SID） 是否預設設定。

bool IsGroupDefaulted() const throw();

傳回值

如果默認機制，而不是安全性描述元的原始提供者，則傳回 true，前提是安全性描述元的群組 SID。 否則會傳回 false。

備註

若要設定此旗標，請使用 CSecurityDesc：：SetGroup 方法。

CSecurityDesc：：IsOwnerDefaulted

判斷安全性描述元的擁有者安全性識別碼 （SID） 是否預設設定。

bool IsOwnerDefaulted() const throw();

傳回值

如果默認機制，而不是安全性描述元的原始提供者，則傳回 true，前提是安全性描述元的擁有者 SID。 否則會傳回 false。

備註

若要設定此旗標，請使用 CSecurityDesc：：SetOwner 方法。

CSecurityDesc：：IsSaclAutoInherited

判斷系統存取控制清單 （SACL） 是否已設定為支援自動傳播。

bool IsSaclAutoInherited() const throw();

傳回值

如果安全性描述項包含 SACL，則會傳回 true，此 SACL 設定為支援將可繼承訪問控制專案 （ACE） 自動傳播至現有的子物件。 否則會傳回 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 設定為防止可繼承的訪問控制專案修改安全性描述項，則會傳回 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
要SECURITY_DESCRIPTOR指派給 CSecurityDesc 對象的結構或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 已由用戶明確指定。 方法會將此值儲存在 結構的 SE_DACL_DEFAULTED 旗標中 SECURITY_DESCRIPTOR_CONTROL 。 如果未指定此參數，則會清除SE_DACL_DEFAULTED旗標。

傳回值

如果成功則傳回 true，失敗則傳回 false。

備註

空白與不存在的 DACL 之間有一個重要的差異。 當 DACL 是空的時，它不會包含任何存取控制專案，也沒有明確授與訪問許可權。 因此，隱含拒絕對物件的存取。 當對象沒有 DACL 時，另一方面，不會將任何保護指派給物件，而且會授與任何存取要求。

CSecurityDesc：：SetGroup

設定絕對格式安全性描述元的主要群組資訊，並取代任何已經存在的主要群組資訊。

bool SetGroup(const CSid& Sid, bool bDefaulted = false) throw(...);

參數

Sid
安全性描述元新主要群組之 CSid 對象的參考。 此參數不得為 NULL。 安全性描述元可以標示為沒有 DACL 或 SACL，但它必須有群組和擁有者，即使是 NULL SID（這是具有特殊意義的內建 SID）。

bDefaulted
指出主要群組資訊是否衍生自默認機制。 如果此值為 true，則為預設資訊，而且方法會將此值儲存為 結構中的 SECURITY_DESCRIPTOR_CONTROL SE_GROUP_DEFAULTED旗標。 如果此參數為零，則會清除SE_GROUP_DEFAULTED旗標。

傳回值

如果成功則傳回 true，失敗則傳回 false。

CSecurityDesc：：SetOwner

設定絕對格式安全性描述元的擁有者資訊。 它會取代任何已經存在的擁有者資訊。

bool SetOwner(const CSid& Sid, bool bDefaulted = false) throw(...);

參數

Sid
安全性描述元之新主要擁有者的 CSid 物件。 此參數不得為 NULL。

bDefaulted
指出擁有者資訊是否衍生自默認機制。 如果此值為 true，則為預設資訊。 方法會將此值儲存為 結構中的 SECURITY_DESCRIPTOR_CONTROL SE_OWNER_DEFAULTED旗標。 如果此參數為零，則會清除SE_OWNER_DEFAULTED旗標。

傳回值

如果成功則傳回 true，失敗則傳回 false。

CSecurityDesc：：SetSacl

在系統訪問控制清單中設定資訊（SACL）。 如果 SACL 已存在於安全性描述元中，則會加以取代。

bool SetSacl(const CSacl& Sacl, bool bDefaulted = false) throw(...);

參數

Sacl
CSacl指定安全性描述元之 SACL 的物件指標。 此參數不得為 NULL，而且必須是 CSacl 物件。 與 DACL 不同，NULL 與空的 SACL 之間沒有任何差異，因為 SACL 物件不會指定訪問許可權，而只會稽核資訊。

bDefaulted
指定旗標，指出 SACL 的來源。 如果此旗標為 true，表示 SACL 已由某些預設機制擷取。 如果為 false，表示 SACL 已由使用者明確指定。 方法會將此值儲存在 結構的 SE_SACL_DEFAULTED 旗標中 SECURITY_DESCRIPTOR_CONTROL 。 如果未指定此參數，則會清除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 終止字串的指標。

四
指定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。

另請參閱

安全性範例
SECURITY_DESCRIPTOR
類別概觀
安全性全域函式