AccessCheckByTypeResultListAndAuditAlarmByHandleA 函式 (winbase.h)

發行項
03/13/2024

AccessCheckByTypeResultListAndAuditAlarmByHandle 函式會決定安全性描述元是否授與呼叫線程所模擬用戶端的指定訪問許可權集。此函式與 AccessCheckByTypeResultListAndAuditAlarm 之間的差異在於，此函式允許呼叫線程在模擬用戶端之前執行存取檢查。

函式可以檢查物件的階層存取權，例如物件、其屬性集和屬性。函式會報告授與或拒絕階層中每個物件類型的訪問許可權。如果安全性描述項具有系統訪問控制清單 (SACL) ，且訪問控制專案 (ACE) 套用至用戶端，則函式會在安全性事件記錄檔中產生任何必要的稽核訊息。目前不支援警示。

語法

BOOL AccessCheckByTypeResultListAndAuditAlarmByHandleA(
  [in]                LPCSTR               SubsystemName,
  [in]                LPVOID               HandleId,
  [in]                HANDLE               ClientToken,
  [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]               LPDWORD              AccessStatusList,
  [out]               LPBOOL               pfGenerateOnClose
);

參數

[in] SubsystemName

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

[in] HandleId

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

[in] ClientToken

Token 物件的句柄，表示要求作業的用戶端。此句柄必須透過通訊會話層取得，例如本機命名管道，以防止可能發生的安全策略違規。呼叫端必須具有指定令牌的TOKEN_QUERY存取權。

[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}。如果物件類型清單順序不足， AccessCheckByTypeResultListAndAuditAlarmByHandle 會失敗，而 GetLastError 會傳回ERROR_INVALID_PARAMETER。

[in] ObjectTypeListLength

ObjectTypeList 陣列中的項目數目。

[in] GenericMapping

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

[in] ObjectCreation

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

[out] GrantedAccess

存取遮罩陣列的指標。函式會設定每個存取掩碼，以指出授與物件類型清單中的對應元素的訪問許可權。如果函式失敗，它不會設定存取遮罩。

[out] AccessStatusList

物件類型清單中對應元素的狀態代碼數位指標。函式會將項目設定為零，表示成功或非零值，以指出存取檢查期間的特定錯誤。如果函式失敗，它不會設定陣列中的任何專案。

[out] pfGenerateOnClose

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

傳回值

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

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

備註

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

如同 AccessCheckByTypeResultListAndAuditAlarm，AccessCheckByTypeResultListAndAuditAlarmByHandle 函式是 AccessCheckByTypeResultList 和 AccessCheckAndAuditAlarm 函式的組合。不過， AccessCheckByTypeResultListAndAuditAlarmByHandle 也需要用戶端令牌句柄，才能在用戶端上提供安全性資訊。

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

AccessCheckByTypeResultListAndAuditAlarmByHandle 函式會針對 ObjectTypeList 陣列中列出的物件類型，評估套用至物件本身和物件特定 ACE 的 ACE。函式會忽略 ObjectTypeList 陣列中未列出的物件類型物件特定 ACE。

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

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

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

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

規格需求

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