AccessCheck 函式 (securitybaseapi.h)

發行項
03/09/2024

AccessCheck 函式會判斷安全性描述元是否授與存取令牌所識別之用戶端的指定訪問許可權集。一般而言，伺服器應用程式會使用此函式來檢查私用物件的存取權。

語法

BOOL AccessCheck(
  [in]            PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]            HANDLE               ClientToken,
  [in]            DWORD                DesiredAccess,
  [in]            PGENERIC_MAPPING     GenericMapping,
  [out, optional] PPRIVILEGE_SET       PrivilegeSet,
  [in, out]       LPDWORD              PrivilegeSetLength,
  [out]           LPDWORD              GrantedAccess,
  [out]           LPBOOL               AccessStatus
);

參數

[in] pSecurityDescriptor

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

[in] ClientToken

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

[in] DesiredAccess

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

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

[in] GenericMapping

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

[out, optional] PrivilegeSet

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

[in, out] PrivilegeSetLength

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

[out] GrantedAccess

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

[out] AccessStatus

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

傳回值

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

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

備註

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

AccessCheck 函式會比較指定的安全性描述元與指定的存取令牌，並指出 AccessStatus 參數中是否授與或拒絕存取。如果授與存取權，要求的存取遮罩會變成物件的授與存取遮罩。

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

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

AccessCheck 函式不會產生稽核。如果您的應用程式需要存取檢查的稽核，請使用 AccessCheckAndAuditAlarm、 AccessCheckByTypeAndAuditAlarm、 AccessCheckByTypeResultListAndAuditAlarm 或 AccessCheckByTypeResultListAndAuditAlarmByHandle 等函式，而不是 AccessCheck。

範例

如需使用此函式的範例，請參閱使用 ACL 驗證用戶端存取。

規格需求

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