Funzione SetEntriesInAclA (aclapi.h)

Articolo
03/14/2023

La funzione SetEntriesInAcl crea un nuovo elenco di controllo di accesso (ACL) unendo nuove informazioni di controllo di accesso o controllo in una struttura ACL esistente.

Sintassi

DWORD SetEntriesInAclA(
  [in]           ULONG              cCountOfExplicitEntries,
  [in, optional] PEXPLICIT_ACCESS_A pListOfExplicitEntries,
  [in, optional] PACL               OldAcl,
  [out]          PACL               *NewAcl
);

Parametri

[in] cCountOfExplicitEntries

Numero di strutture EXPLICIT_ACCESS nella matrice pListOfExplicitEntries .

[in, optional] pListOfExplicitEntries

Puntatore a una matrice di strutture EXPLICIT_ACCESS che descrivono le informazioni sul controllo di accesso da unire nell'ACL esistente.

[in, optional] OldAcl

Puntatore all'ACL esistente. Questo parametro può essere NULL, nel qual caso la funzione crea un nuovo ACL in base alle voci EXPLICIT_ACCESS .

[out] NewAcl

Puntatore a una variabile che riceve un puntatore al nuovo ACL. Se la funzione ha esito positivo, è necessario chiamare la funzione LocalFree per liberare il buffer restituito.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce ERROR_SUCCESS.

Se la funzione ha esito negativo, restituisce un codice di errore diverso da zero definito in WinError.h.

Commenti

Ogni voce nella matrice di strutture EXPLICIT_ACCESS specifica le informazioni di controllo di accesso o controllo per un trustee specificato. Un trustee può essere un utente, un gruppo o un altro valore dell'identificatore di sicurezza (SID), ad esempio un identificatore di accesso o un tipo di accesso (ad esempio, un servizio Windows o un processo batch). È possibile usare un nome o un SID per identificare un trustee.

È possibile utilizzare la funzione SetEntriesInAcl per modificare l'elenco di voci di controllo di accesso (ACL) in un elenco di controllo di accesso discrezionale (DACL) o in un elenco di controllo di accesso di sistema (SACL). Si noti che SetEntriesInAcl non impedisce di combinare le informazioni di controllo di accesso e controllo nello stesso ACL; Tuttavia, l'ACL risultante conterrà voci senza significato.

Per un DACL, il membro grfAccessMode della struttura EXPLICIT_ACCESS specifica se consentire, negare o revocare i diritti di accesso per il trustee. Questo membro può specificare uno dei valori seguenti:

GRANT_ACCESS
SET_ACCESS
DENY_ACCESS
REVOKE_ACCESS

Per informazioni su questi valori, vedere ACCESS_MODE.

La funzione SetEntriesInAcl inserisce eventuali nuovi ACL non autorizzati all'accesso all'inizio dell'elenco di ACL per il nuovo ACL. Questa funzione inserisce tutti i nuovi ACL consentiti per l'accesso subito prima di tutti gli ACL consentiti per l'accesso esistenti.

Per un sacl, il membro grfAccessMode della struttura EXPLICIT_ACCESS può specificare i valori seguenti:

REVOKE_ACCESS
SET_AUDIT_FAILURE
SET_AUDIT_SUCCESS

SET_AUDIT_FAILURE e SET_AUDIT_SUCCESS possono essere combinati. Per informazioni su questi valori, vedere ACCESS_MODE.

La funzione SetEntriesInAcl inserisce tutti i nuovi ACL di controllo di sistema all'inizio dell'elenco di ACL per il nuovo ACL.

Esempio

Per un esempio che usa questa funzione, vedere Modifica degli ACL di un oggetto o Creazione di un descrittore di sicurezza per un nuovo oggetto o Acquisizione della proprietà dell'oggetto.

Nota

L'intestazione aclapi.h definisce SetEntriesInAcl come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	aclapi.h
Libreria	Advapi32.lib
DLL	Advapi32.dll