AddAuditAccessObjectAce 函式 (securitybaseapi.h)

發行項
03/01/2024

AddAuditAccessObjectAce 函式會將系統稽核訪問控制專案 (ACE) 新增至系統訪問控制清單結尾， (SACL) 。新的 ACE 可以稽核物件的存取權，或是物件上的屬性集或屬性。您也可以使用 AddAuditAccessObjectAce 來新增 ACE，只有指定的子物件類型可以繼承。

語法

BOOL AddAuditAccessObjectAce(
  [in, out]      PACL  pAcl,
  [in]           DWORD dwAceRevision,
  [in]           DWORD AceFlags,
  [in]           DWORD AccessMask,
  [in, optional] GUID  *ObjectTypeGuid,
  [in, optional] GUID  *InheritedObjectTypeGuid,
  [in]           PSID  pSid,
  [in]           BOOL  bAuditSuccess,
  [in]           BOOL  bAuditFailure
);

參數

[in, out] pAcl

SACL 的指標。 AddAuditAccessObjectAce 函式會將系統稽核 ACE 新增至此 SACL 的結尾。 ACE 的格式為 SYSTEM_AUDIT_OBJECT_ACE 結構。

[in] dwAceRevision

指定要修改之 SACL 的修訂層級。此值必須ACL_REVISION_DS。如果 SACL 的修訂層級低於ACL_REVISION_DS，函式會將它變更為ACL_REVISION_DS。

[in] AceFlags

一組位旗標，可控制ACE繼承和存取嘗試稽核的類型。函式會在新 ACE ACE_HEADER 結構的 AceFlags 成員中設定這些旗標。此參數可以是下列值的組合。

值	意義
CONTAINER_INHERIT_ACE	ACE 會由容器對象繼承。
FAILED_ACCESS_ACE_FLAG	如果您為 bAuditFailure 參數設定此旗標或指定 TRUE，則嘗試使用指定的訪問許可權會導致系統在安全性事件記錄檔中產生稽核記錄。
INHERIT_ONLY_ACE	ACE 不適用於指派 ACL) (訪問控制清單的物件，但可由子物件繼承。
INHERITED_ACE	表示繼承的 ACE。此旗標允許變更物件樹狀結構上安全性的作業，以修改繼承的 ACE，但不會變更直接套用至物件的 ACE。
NO_PROPAGATE_INHERIT_ACE	OBJECT_INHERIT_ACE和CONTAINER_INHERIT_ACE位不會傳播至繼承的ACE。
OBJECT_INHERIT_ACE	ACE 是由非容器對象繼承。
SUCCESSFUL_ACCESS_ACE_FLAG	如果您設定此旗標或為 bAuditSuccess 參數指定 TRUE，成功使用指定的訪問許可權會導致系統在安全性事件記錄檔中產生稽核記錄。

[in] AccessMask

ACCESS_MASK，指定新 ACE 針對指定的安全識別碼稽核 (SID) 的訪問許可權。

[in, optional] ObjectTypeGuid

GUID 結構的指標，識別由新 ACE 保護的物件、屬性集或屬性類型。如果此參數為 NULL，新的 ACE 會保護指派 ACL 的物件。

[in, optional] InheritedObjectTypeGuid

GUID 結構的指標，識別可繼承新 ACE 的物件類型。如果此參數不是 NULL，則只有指定的物件類型可以繼承 ACE。如果 為 NULL，則任何類型的子物件都可以繼承 ACE。不論是哪一種情況，繼承也是由 AceFlags 參數的值所控制，以及對子物件上所放置之繼承的任何保護。

[in] pSid

SID 的指標，識別新 ACE 稽核存取的使用者、群組或登入會話。

[in] bAuditSuccess

指定是否成功使用指定的訪問許可權，導致系統在安全性事件記錄檔中產生稽核記錄。如果此旗標為 TRUE ，或 AceFlags 參數指定SUCCESSFUL_ACCESS_ACE_FLAG旗標，則系統會記錄成功的存取嘗試;否則，則不會。

[in] bAuditFailure

指定是否嘗試使用指定的訪問許可權失敗，導致系統在安全性事件記錄檔中產生稽核記錄。如果此旗標為 TRUE ，或 AceFlags 參數指定FAILED_ACCESS_ACE_FLAG旗標，則系統會記錄失敗的存取嘗試;否則，則不會。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。以下是可能的錯誤值。

傳回碼	Description
ERROR_ALLOTTED_SPACE_EXCEEDED	新的 ACE 不符合 ACL。需要較大的 ACL 緩衝區。
ERROR_INVALID_ACL	指定的 ACL 格式不正確。
ERROR_INVALID_FLAGS	AceFlags 參數無效。
ERROR_INVALID_SID	指定的 SID 在結構上無效。
ERROR_REVISION_MISMATCH	指定的修訂未知，或與 ACL 的修訂不相容。
ERROR_SUCCESS	已成功新增 ACE。

備註

如果 ObjectTypeGuid 和 InheritedObjectTypeGuid 都是 NULL，請使用 AddAuditAccessAceEx 函式，而不是 AddAuditAccessObjectAce。這是建議的，因為 SYSTEM_AUDIT_ACE 比 SYSTEM_AUDIT_OBJECT_ACE小且更有效率。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	securitybaseapi.h (包含 Windows.h)
程式庫	Advapi32.lib
Dll	Advapi32.dll