AccessCheckByType 函式 (securitybaseapi.h)

發行項
03/05/2024

AccessCheckByType 函式會判斷安全性描述元是否授與存取令牌所識別之用戶端的指定訪問許可權集。函式可以檢查客戶端對物件階層的存取權，例如物件、其屬性集和屬性。函式會授與或拒絕整體階層的存取權。一般而言，伺服器應用程式會使用此函式來檢查私用物件的存取權。

語法

BOOL AccessCheckByType(
  [in]                PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in, optional]      PSID                 PrincipalSelfSid,
  [in]                HANDLE               ClientToken,
  [in]                DWORD                DesiredAccess,
  [in, out, optional] POBJECT_TYPE_LIST    ObjectTypeList,
  [in]                DWORD                ObjectTypeListLength,
  [in]                PGENERIC_MAPPING     GenericMapping,
  [out, optional]     PPRIVILEGE_SET       PrivilegeSet,
  [in, out]           LPDWORD              PrivilegeSetLength,
  [out]               LPDWORD              GrantedAccess,
  [out]               LPBOOL               AccessStatus
);

參數

[in] pSecurityDescriptor

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

[in, optional] PrincipalSelfSid

安全性標識碼的指標 (SID) 。如果安全性描述項與代表主體 (的對象相關聯，例如，用戶物件 ) ，PrincipalSelfSid 參數應該是物件的 SID。評估存取權時，此 SID 會以邏輯方式取代任何包含已知PRINCIPAL_SELF SID (S-1-5-10) 之存取控制專案中的 SID。如需已知 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}。如果物件類型清單順序錯亂， AccessCheckByType 會失敗，而且 GetLastError 會傳回ERROR_INVALID_PARAMETER。

如果 ObjectTypeList 為 NULL，AccessCheckByType 與 AccessCheck 函式相同。

[in] ObjectTypeListLength

指定 ObjectTypeList 陣列中的項目數目。

[in] GenericMapping

與正在檢查存取的對象相關聯的 GENERIC_MAPPING 結構的指標。 GENERIC_MAPPING 結構的 GenericAll 成員應該包含資源管理員可以授與的所有存取許可權，包括STANDARD_RIGHTS_ALL和 GenericRead、GenericWrite 和 GenericExecute 成員中設定的所有許可權。

[out, optional] PrivilegeSet

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

[in, out] PrivilegeSetLength

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

[out] GrantedAccess

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

[out] AccessStatus

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

傳回值

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

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

備註

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

AccessCheckByType 函式會比較指定的安全描述符與指定的存取令牌，並在 AccessStatus 參數中指出是否授與或拒絕存取。

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

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

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

如果安全性描述項的 DACL 為 NULL，AccessStatus 參數會傳回 TRUE，表示用戶端具有要求的存取權。

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

規格需求

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