CSecurityDesc Class

 

如需 Visual Studio 2017 的最新文件請參閱 Visual Studio 2017 文件

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

System_CAPS_ICON_important.jpg 重要

這個類別及其成員不能在 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() throw();
CSecurityDesc(const CSecurityDesc& rhs) throw(... );  
CSecurityDesc(const SECURITY_DESCRIPTOR& rhs) throw(...);

參數

rhs
CSecurityDesc物件或SECURITY_DESCRIPTOR結構以指派給新CSecurityDesc物件。

備註

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

解構函式。

virtual ~CSecurityDesc() throw();

備註

解構函式會釋放所有配置的資源。

將字串格式的安全性描述元轉換成有效、 功能安全性描述元。

bool FromString(LPCTSTR pstr) throw(...);

參數

pstr
以 null 終止的字串,其中包含指標字串格式的安全性描述元轉換。

傳回值

如果成功則傳回 true。 失敗時擲回例外狀況。

備註

可以使用建立的字串CSecurityDesc::ToString。 將安全性描述元轉換成字串,可讓您更輕鬆地儲存和傳輸。

這個方法只適用於 Windows 2000 和更新版本因為它會呼叫ConvertStringSecurityDescriptorToSecurityDescriptor

擷取控制從安全性描述元的資訊。

bool GetControl(SECURITY_DESCRIPTOR_CONTROL* psdc) const throw();

參數

psdc
指標SECURITY_DESCRIPTOR_CONTROL接收的安全性描述元控制資訊的結構。

傳回值

如果此方法成功,false 失敗時傳回 true。

備註

這個方法才有意義,當使用 Windows 2000 或更新版本,因為它會呼叫GetSecurityDescriptorControl

擷取安全性描述元的判別存取控制清單 (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
中的 SE_DACL_DEFAULTED 旗標值的一組旗標指標SECURITY_DESCRIPTOR_CONTROL結構如果判別ACL存在的安全性描述元。 如果這個旗標為 true,判別ACL所擷取預設的機制; 如果為 false,判別ACL已由使用者明確指定。

傳回值

如果此方法成功,false 失敗時傳回 true。

擷取安全性描述元中的主要群組資訊。

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

參數

pSid
指標CSid (安全性識別碼),會收到一份儲存 CDacl 中的群組。

pbDefaulted
中的 SE_GROUP_DEFAULTED 旗標值的一組旗標指標SECURITY_DESCRIPTOR_CONTROL結構方法傳回時。

傳回值

如果此方法成功,false 失敗時傳回 true。

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

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

參數

pSid
指標CSid (安全性識別碼),會收到一份儲存 CDacl 中的群組。

pbDefaulted
中的 SE_OWNER_DEFAULTED 旗標值的一組旗標指標SECURITY_DESCRIPTOR_CONTROL結構方法傳回時。

傳回值

如果此方法成功,false 失敗時傳回 true。

傳回的指標SECURITY_DESCRIPTOR結構。

const SECURITY_DESCRIPTOR* GetPSECURITY_DESCRIPTOR() const throw();

傳回值

傳回的指標SECURITY_DESCRIPTOR結構。

擷取安全性描述元的系統存取控制清單 (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
中的 SE_SACL_DEFAULTED 旗標值的一組旗標指標SECURITY_DESCRIPTOR_CONTROL結構,如果系統ACL存在的安全性描述元。

傳回值

如果此方法成功,false 失敗時傳回 true。

決定是否判別存取控制清單 (DACL) 設定為支援自動傳播。

bool IsDaclAutoInherited() const throw();

傳回值

如果安全性描述元包含 DACL,這設定為支援自動傳播到現有的子物件的可繼承的存取控制項目 (Ace),則傳回 true。 否則會傳回 False。

備註

它會執行自動繼承演算法的物件和其現有的子物件時,系統會設定這個位元。

決定是否設定成以預設的判別存取控制清單 (DACL) 的安全性描述元。

bool IsDaclDefaulted() const throw();

傳回值

如果安全性描述元包含預設的 DACL,false 否則會傳回 true。

備註

這個旗標可能會影響系統如何處理 DACL,相對於存取控制項目 (ACE) 繼承。 比方說,如果物件的建立者未指定 DACL,物件會接收預設 DACL 的建立者的存取權杖。 如果未設定 SE_DACL_PRESENT 旗標,系統會忽略此旗標。

這個旗標用來判斷物件的最終 DACL 的計算方式,而且不會儲存實際在安全性實體物件的安全性描述元控制。

若要設定此旗標,使用CSecurityDesc::SetDacl方法。

判斷安全性描述元是否包含判別存取控制清單 (DACL)。

bool IsDaclPresent() const throw();

傳回值

如果安全性描述元包含 DACL,false 否則傳回 true。

備註

如果未設定此旗標,或如果設定此旗標,而 DACL 是 NULL,安全性描述元可讓所有人都能完整存取權。

這個旗標用來保存的安全性描述元的安全性實體物件相關聯之前,呼叫端所指定的安全性資訊。 一旦與安全性實體物件相關聯的安全性描述元,SE_DACL_PRESENT 旗標一定會設定安全性描述元控制項中。

若要設定此旗標,使用CSecurityDesc::SetDacl方法。

決定是否判別存取控制清單 (DACL) 為了避免修改設定。

bool IsDaclProtected() const throw();

傳回值

如果 DACL 設定為防止修改由繼承的存取控制項目 (Ace) 的安全性描述元,則傳回 true。 否則會傳回 False。

備註

若要設定此旗標,使用CSecurityDesc::SetDacl方法。

這個方法才有意義的 Windows 2000 或更新版本中,只有 Windows 2000 支援自動傳播的可繼承的 Ace。

決定是否預設已設定的安全性描述元群組安全性識別碼 (SID)。

bool IsGroupDefaulted() const throw();

傳回值

如果預設的機制,而不是原始的提供者的安全性描述元,提供的安全性描述元,群組 SID,則傳回 true。 否則會傳回 False。

備註

若要設定此旗標,使用CSecurityDesc::SetGroup方法。

決定是否預設已設定的安全性描述元擁有者安全性識別碼 (SID)。

bool IsOwnerDefaulted() const throw();

傳回值

如果預設的機制,而不是原始的提供者的安全性描述元,提供的安全性描述元擁有者 SID,則傳回 true。 否則會傳回 False。

備註

若要設定此旗標,使用CSecurityDesc::SetOwner方法。

決定系統存取控制清單 (SACL) 是否設定為支援自動傳播。

bool IsSaclAutoInherited() const throw();

傳回值

如果安全性描述元包含某個設定以支援自動傳播到現有的子物件的可繼承的存取控制項目 (Ace),則傳回 true。 否則會傳回 False。

備註

它會執行自動繼承演算法的物件和其現有的子物件時,系統會設定這個位元。

決定是否設定成以預設的系統存取控制清單 (SACL) 的安全性描述元。

bool IsSaclDefaulted() const throw();

傳回值

如果安全性描述元包含預設的 SACL,false 否則會傳回 true。

備註

這個旗標可能會影響系統如何處理 SACL,相對於存取控制項目 (ACE) 繼承。 如果未設定 SE_SACL_PRESENT 旗標,系統會忽略此旗標。

若要設定此旗標,使用CSecurityDesc::SetSacl方法。

判斷安全性描述元是否包含系統存取控制清單 (SACL)。

bool IsSaclPresent() const throw();

傳回值

如果安全性描述元包含 SACL,false 否則傳回 true。

備註

若要設定此旗標,使用CSecurityDesc::SetSacl方法。

決定是否設定成以防止修改的系統存取控制清單 (SACL)。

bool IsSaclProtected() const throw();

傳回值

如果 SACL 設定為防止修改由繼承的存取控制項目 (Ace) 的安全性描述元,則傳回 true。 否則會傳回 False。

備註

若要設定此旗標,使用CSecurityDesc::SetSacl方法。

這個方法才有意義的 Windows 2000 或更新版本中,只有 Windows 2000 支援自動傳播的可繼承的 Ace。

決定是否自我相關格式的安全性描述元。

bool IsSelfRelative() const throw();

傳回值

如果安全性描述元中自我相關格式與連續的記憶體區塊中的所有安全性資訊,則傳回 true。 如果安全性描述元是絕對格式,就會傳回 false。 如需詳細資訊,請參閱絕對及 Self-Relative 安全性描述元

呼叫這個方法來將安全性描述元轉換成絕對格式。

bool MakeAbsolute() throw(...);

傳回值

如果此方法成功,false 否則傳回 true。

備註

絕對格式的安全性描述元包含它所包含的資訊,而不是本身的資訊的指標。 自我相關格式的安全性描述元包含連續的記憶體區塊中的資訊。 自我關聯的安全性描述元中SECURITY_DESCRIPTOR結構永遠會啟動的詳細資訊,但安全性描述元的其他元件可以依照任何順序中的結構。 而不是使用的記憶體位址,自我關聯的安全性描述元的元件會識別的安全性描述元開頭的位移。 必須在磁碟上儲存或傳輸通訊協定透過安全性描述元時,此格式會很有用。 如需詳細資訊,請參閱絕對及 Self-Relative 安全性描述元

呼叫這個方法來將安全性描述元轉換成自我關聯的格式。

bool MakeSelfRelative() throw(...);

傳回值

如果此方法成功,false 否則傳回 true。

備註

絕對格式的安全性描述元包含它所包含的資訊,而不是包含資訊本身的指標。 自我相關格式的安全性描述元包含連續的記憶體區塊中的資訊。 自我關聯的安全性描述元中SECURITY_DESCRIPTOR結構永遠會啟動的詳細資訊,但安全性描述元的其他元件可以依照任何順序中的結構。 而不是使用的記憶體位址,從安全性描述元開頭的位移被識別元件的安全性描述元。 必須在磁碟上儲存或傳輸通訊協定透過安全性描述元時,此格式會很有用。 如需詳細資訊,請參閱絕對及 Self-Relative 安全性描述元

指派運算子。

CSecurityDesc& operator= (const SECURITY_DESCRIPTOR& rhs) throw(...);  
CSecurityDesc& operator= (const CSecurityDesc& rhs) throw(...);

參數

rhs
SECURITY_DESCRIPTOR結構或CSecurityDesc物件指派給CSecurityDesc物件。

傳回值

傳回更新CSecurityDesc物件。

將指標值轉換SECURITY_DESCRIPTOR結構。

operator const SECURITY_DESCRIPTOR *() const throw();

設定安全性描述元的控制位元。

bool SetControl(
    SECURITY_DESCRIPTOR_CONTROL ControlBitsOfInterest, 
    SECURITY_DESCRIPTOR_CONTROL ControlBitsToSet) throw();

參數

ControlBitsOfInterest
A SECURITY_DESCRIPTOR_CONTROL指出若要設定之控制位元遮罩。 如需可設定的旗標的清單,請參閱SetSecurityDescriptorControl

ControlBitsToSet
SECURITY_DESCRIPTOR_CONTROL 遮罩,表示 ControlBitsOfInterest 遮罩所指定控制位元的新值。 此參數可以是針對 ControlBitsOfInterest 參數所列出旗標的組合。

傳回值

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

備註

這個方法,便可以只在 Windows 2000 及更新版本,它會呼叫SetSecurityDescriptorControl

判別存取控制清單 (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,則方法會設定 SE_DACL_PRESENT 旗標SECURITY_DESCRIPTOR_CONTROL結構,並使用中的值DaclbDefaulted參數。 如果為 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 時,相反地,沒有任何保護指派給物件,並授與存取權的任何要求。

設定絕對格式安全性描述元,以取代任何現有的主要群組資訊的主要群組資訊。

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

參數

Sid
若要參考CSid的安全性描述元的新主要群組的物件。 此參數不得為 NULL。 安全性描述元可以標示為不具有 DACL 或 SACL,但是它必須擁有群組和擁有者,這些甚至會 NULL SID (這是具有特殊意義的內建 SID)。

bDefaulted
表示主要群組資訊是否衍生自預設機制。 如果此值為 true,它是預設的詳細資訊,而且方法會將這個值儲存為 SE_GROUP_DEFAULTED 旗標SECURITY_DESCRIPTOR_CONTROL結構。 如果此參數為零,則會清除 SE_GROUP_DEFAULTED 旗標。

傳回值

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

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

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。

設定系統存取控制清單 (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。

將安全性描述元轉換成字串格式。

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︰ 元件。 請參閱安全性描述元字串格式如需詳細資訊。

這個方法只適用於 Windows 2000 和更新版本中,因為它會呼叫ConvertStringSecurityDescriptorToSecurityDescriptor

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

顯示: