AccessCheckByTypeAndAuditAlarmW 函式 (securitybaseapi.h)

發行項
03/01/2024

AccessCheckByTypeAndAuditAlarm 函式會決定安全性描述元是否授與呼叫線程所模擬用戶端的指定訪問許可權集。函式可以檢查客戶端對物件階層的存取權，例如物件、其屬性集和屬性。函式會授與或拒絕整個階層的存取權。如果安全性描述項具有系統訪問控制清單 (SACL) ，且訪問控制專案 (ACE) 套用至用戶端，則函式會在安全性事件記錄檔中產生任何必要的稽核訊息。

目前不支援警示。

語法

BOOL AccessCheckByTypeAndAuditAlarmW(
  [in]                LPCWSTR              SubsystemName,
  [in]                LPVOID               HandleId,
  [in]                LPCWSTR              ObjectTypeName,
  [in, optional]      LPCWSTR              ObjectName,
  [in]                PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                DWORD                DesiredAccess,
  [in]                AUDIT_EVENT_TYPE     AuditType,
  [in]                DWORD                Flags,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [in]                BOOL                 ObjectCreation,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPBOOL               AccessStatus,
  [out]               LPBOOL               pfGenerateOnClose
);

參數

[in] SubsystemName

指定呼叫函式之子系統名稱之 Null 終止字串的指標。此字串會出現在函式產生的任何稽核訊息中。

[in] HandleId

表示物件之用戶端句柄的唯一值指標。如果拒絕存取，系統會忽略此值。

[in] ObjectTypeName

Null 終止字串的指標，指定所建立或存取的物件類型。此字串會出現在函式產生的任何稽核訊息中。

[in, optional] ObjectName

Null 終止字串的指標，指定所建立或存取之對象的名稱。此字串會出現在函式產生的任何稽核訊息中。

[in] SecurityDescriptor

檢查存取權的 SECURITY_DESCRIPTOR 結構的指標。

[in, optional] PrincipalSelfSid

安全性標識碼的指標 (SID) 。如果安全性描述元與代表主體 (的對象相關聯，例如，用戶物件 ) ，PrincipalSelfSid 參數應該是物件的SID。評估存取權時，此 SID 會以邏輯方式取代任何 ACE 中的 SID，其中包含已知PRINCIPAL_SELF SID (S-1-5-10) 。如需已知 SID 的相關信息，請參閱已知的 SID。

如果受保護的物件不代表主體，請將此參數設定為 NULL。

[in] DesiredAccess

指定要檢查之訪問許可權的存取遮罩。 MapGenericMask 函式必須已對應此遮罩，才能不包含泛型訪問許可權。

如果此參數MAXIMUM_ALLOWED，函式會設定 GrantedAccess 存取遮罩，以指出安全性描述元允許用戶端的最大訪問許可權。

[in] AuditType

要產生的稽核類型。這可以是 AUDIT_EVENT_TYPE 列舉類型的其中一個值。

[in] Flags

如果呼叫進程未啟用SE_AUDIT_NAME許可權，則為控制函式行為的旗標。如果已設定AUDIT_ALLOW_NO_PRIVILEGE旗標，則函式會在未啟用許可權時執行存取檢查，而不會產生稽核訊息。如果此參數為零，則如果未啟用許可權，則函式會失敗。

[in, out, optional] ObjectTypeList

OBJECT_TYPE_LIST 結構的陣列指標，可識別要檢查存取的物件類型階層。數位中的每個元素都會指定 GUID，識別物件類型，以及指出物件類型階層中物件型別層級的值。數位不應該有兩個具有相同 GUID 的專案。

陣列必須至少有一個專案。陣列中的第一個項目必須是層級零，並識別物件本身。陣列只能有一個層級零元素。第二個元素是子物件，例如層級 1 的屬性集。遵循每個層級 1 專案是層級 2 到 4 個子物件的次級專案。因此，陣列中元素的層級可能是 {0、1、2、2、1、2、3}。如果對象類型清單順序不足， AccessCheckByTypeAndAuditAlarm 會失敗，而且 GetLastError 會傳回ERROR_INVALID_PARAMETER。

[in] ObjectTypeListLength

ObjectTypeList 陣列中的項目數目。

[in] GenericMapping

與正在檢查存取的對象相關聯的 GENERIC_MAPPING 結構指標。

[in] ObjectCreation

旗標，判斷呼叫端應用程式是否會在授與存取權時建立新的物件。 TRUE 值表示應用程式會建立新的物件。 FALSE 值表示應用程式會開啟現有的物件。

[out] GrantedAccess

接收授與訪問許可權之存取遮罩的指標。如果 AccessStatus 設定為 FALSE，函式會將存取掩碼設定為零。如果函式失敗，它不會設定存取掩碼。

[out] AccessStatus

接收存取檢查結果之變數的指標。如果安全性描述項允許對用戶端的要求訪問許可權， AccessStatus 會設定為 TRUE。否則， AccessStatus 會設定為 FALSE ，您可以呼叫 GetLastError 以取得延伸的錯誤資訊。

[out] pfGenerateOnClose

函式傳回時，稽核產生例程所設定之旗標的指標。關閉物件句柄時，將此旗標傳遞至 ObjectCloseAuditAlarm 函式。

傳回值

如果函式成功，函式會傳回非零。

如果函式失敗，它會傳回零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

如需詳細資訊，請參閱 AccessCheck 的運作方式概觀。

如果 PrincipalSelfSid 和 ObjectTypeList 參數為 NULL，AuditType 參數為 AuditEventObjectAccess，而 Flags 參數為零，AccessCheckByTypeAndAuditAlarm 會以與 AccessCheckAndAuditAlarm 函式相同的方式執行。

ObjectTypeList 陣列不一定代表整個定義的物件。相反地，它代表要檢查存取權的物件子集。例如，若要檢查屬性集中兩個屬性的存取權，請指定具有四個元素的物件類型清單：層級為零的物件本身、在層級 1 設定的屬性，以及層級 2 的兩個屬性。

AccessCheckByTypeAndAuditAlarm 函式會針對 ObjectTypeList 陣列中列出的物件類型評估套用至物件本身和物件特定 ACE 的 ACE。函式會忽略 ObjectTypeList 陣列中未列出的物件類型物件特定 ACE。因此， AccessStatus 參數中傳回的結果會指出允許存取 ObjectTypeList 參數所定義之物件的子集，而不是整個物件。

如需 ACE 階層如何控制物件及其子物件的存取權的詳細資訊，請參閱 ACE 來控制物件屬性的存取。

若要在安全性事件記錄檔中產生稽核訊息，呼叫進程必須啟用SE_AUDIT_NAME許可權。系統會在呼叫進程的主要令牌中檢查此許可權，而不是線程的模擬令牌。如果 Flags 參數包含AUDIT_ALLOW_NO_PRIVILEGE旗標，則函式會在未啟用許可權時執行存取檢查，而不會產生稽核訊息。

如果呼叫線程未模擬用戶端， AccessCheckByTypeAndAuditAlarm 函式就會失敗。

如果安全性描述項不包含擁有者和群組 SID，AccessCheckByTypeAndAuditAlarm 會失敗並ERROR_INVALID_SECURITY_DESCR。

規格需求

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

另請參閱

AUDIT_EVENT_TYPE
AccessCheck
AccessCheckAndAuditAlarm
AccessCheckByType
AccessCheckByTypeResultList
AccessCheckByTypeResultListAndAuditAlarm
用戶端/伺服器存取控制
 用戶端/伺服器存取控制函式
 GENERIC_MAPPING
AccessCheck 的運作方式
 MakeAbsoluteSD
MapGenericMask
OBJECT_TYPE_LIST
ObjectCloseAuditAlarm
PRIVILEGE_SET
SECURITY_DESCRIPTOR

共用方式為

AccessCheckByTypeAndAuditAlarmW 函式 (securitybaseapi.h)

語法

參數

傳回值

備註

規格需求

另請參閱

意見反應

其他資源