Funzione AccessCheck (securitybaseapi.h)

Articolo
08/25/2023

La funzione AccessCheck determina se un descrittore di sicurezza concede un set specificato di diritti di accesso al client identificato da un token di accesso. In genere, le applicazioni server usano questa funzione per controllare l'accesso a un oggetto privato.

Sintassi

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
);

Parametri

[in] pSecurityDescriptor

Puntatore a una struttura SECURITY_DESCRIPTOR su cui viene controllato l'accesso.

[in] ClientToken

Handle a un token di rappresentazione che rappresenta il client che tenta di ottenere l'accesso. L'handle deve avere TOKEN_QUERY accesso al token; in caso contrario, la funzione ha esito negativo con ERROR_ACCESS_DENIED.

[in] DesiredAccess

Maschera di accesso che specifica i diritti di accesso da controllare. Questa maschera deve essere stata mappata dalla funzione MapGenericMask per non contenere diritti di accesso generici.

Se questo parametro è MAXIMUM_ALLOWED, la funzione imposta la maschera di accesso GrantedAccess per indicare i diritti di accesso massimo consentiti dal descrittore di sicurezza .

[in] GenericMapping

Puntatore alla struttura GENERIC_MAPPING associata all'oggetto per cui viene controllato l'accesso.

[out, optional] PrivilegeSet

Puntatore a una struttura PRIVILEGE_SET che riceve i privilegi usati per eseguire la convalida dell'accesso. Se non sono stati usati privilegi, la funzione imposta il membro PrivilegeCount su zero.

[in, out] PrivilegeSetLength

Specifica le dimensioni, in byte, del buffer a cui punta il parametro PrivilegeSet .

[out] GrantedAccess

Puntatore a una maschera di accesso che riceve i diritti di accesso concessi. Se AccessStatus è impostato su FALSE, la funzione imposta la maschera di accesso su zero. Se la funzione ha esito negativo, non imposta la maschera di accesso.

[out] AccessStatus

Puntatore a una variabile che riceve i risultati del controllo di accesso. Se il descrittore di sicurezza consente i diritti di accesso richiesti al client identificato dal token di accesso, AccessStatus è impostato su TRUE. In caso contrario, AccessStatus è impostato su FALSE e è possibile chiamare GetLastError per ottenere informazioni di errore estese.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Per altre informazioni, vedere la panoramica su Come AccessCheck Works .

La funzione AccessCheck confronta il descrittore di sicurezza specificato con il token di accesso specificato e indica, nel parametro AccessStatus , se l'accesso viene concesso o negato. Se viene concesso l'accesso, la maschera di accesso richiesta diventa la maschera di accesso concessa all'oggetto.

Se il descrittore di sicurezza daCL è NULL, il parametro AccessStatus restituisce TRUE, che indica che il client ha l'accesso richiesto.

La funzione AccessCheck non riesce con ERROR_INVALID_SECURITY_DESCR se il descrittore di sicurezza non contiene SID proprietario e gruppo.

La funzione AccessCheck non genera un controllo. Se l'applicazione richiede controlli di accesso, usare funzioni come AccessCheckAndAuditAlarm, AccessCheckByTypeAndAuditAlarm, AccessCheckByTypeResultListAndAuditAlarm o AccessCheckByTypeResultListAndAuditAlarm, anziché AccessCheck.

Esempio

Per un esempio che usa questa funzione, vedere Verifica dell'accesso client con elenchi di controllo di accesso client.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	securitybaseapi.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll