AccessCheckByTypeAndAuditAlarmA 函式 (winbase.h)
AccessCheckByTypeAndAuditAlarm函式會決定安全性描述元是否授與呼叫執行緒所模擬用戶端的指定存取權限集。 函式可以檢查用戶端對物件階層的存取權，例如物件、其屬性集和屬性。 函式會授與或拒絕整個階層的存取權。 如果安全性描述項具有 系統存取控制清單 (SACL) ，且存取控制 專案 (ACE) 套用至用戶端，則函式會在安全性事件記錄檔中產生任何必要的稽核訊息。
目前不支援警示。
語法
BOOL AccessCheckByTypeAndAuditAlarmA(
[in] LPCSTR SubsystemName,
[in] LPVOID HandleId,
[in] LPCSTR ObjectTypeName,
[in, optional] LPCSTR 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 |
| 標頭 | winbase.h (包含 Windows.h) |
| 程式庫 | Advapi32.lib |
| Dll | Advapi32.dll |