AccessCheckByTypeResultList 函式 (securitybaseapi.h)

發行項
03/05/2024

AccessCheckByTypeResultList 函式會決定安全性描述元是否授與存取令牌所識別之用戶端的指定訪問許可權集。函式可以檢查客戶端對物件階層的存取權，例如物件、其屬性集和屬性。函式會報告授與或拒絕階層中每個物件類型的訪問許可權。伺服器應用程式通常會使用此函式來檢查私人物件的存取權。

語法

BOOL AccessCheckByTypeResultList(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [out]               PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccessList,
  [out]               LPDWORD              AccessStatusList
);

參數

[in] pSecurityDescriptor

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

[in, optional] PrincipalSelfSid

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

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

[in] ClientToken

模擬令牌的句柄，表示嘗試取得存取權的用戶端。句柄必須具有令牌的TOKEN_QUERY存取權;否則，函式會因為ERROR_ACCESS_DENIED而失敗。

[in] DesiredAccess

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

如果此參數MAXIMUM_ALLOWED，此函式會設定 GrantedAccess 陣列中的存取遮罩，以指出客戶端對物件類型清單中每個元素的存取權上限。

[in, out, optional] ObjectTypeList

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

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

[in] ObjectTypeListLength

ObjectTypeList 陣列中的項目數目。這也是 GrantedAccessList 和 AccessStatusList 參數所指向之陣列中的元素數目。

[out] GenericMapping

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

[out, optional] PrivilegeSet

接收用來執行存取驗證之許可權之PRIVILEGE_SET結構的指標。如果未使用任何許可權，函式會將 PrivilegeCount 成員設定為零。

[in, out] PrivilegeSetLength

PrivilegeSet 參數所指向之緩衝區的大小，以位元組為單位。

[out] GrantedAccessList

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

[out] AccessStatusList

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

傳回值

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

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

備註

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

AccessCheckByTypeResultList 函式會比較指定的安全性描述元與指定的存取令牌，並在 AccessStatusList 參數中，針對對象類型清單中的每個元素授與或拒絕存取權。

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

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

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

如果安全性描述項的任意訪問控制清單 (DACL) 為 NULL，則函式會將要求存取權授與物件類型清單中的所有元素。

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

規格需求

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