Funzione SetEntriesInAclW (aclapi.h)

Articolo
11/20/2024

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

Sintassi

DWORD SetEntriesInAclW(
  [in]           ULONG              cCountOfExplicitEntries,
  [in, optional] PEXPLICIT_ACCESS_W 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 di 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.

Osservazioni

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 usare la funzione di SetEntriesInAcl per modificare l'elenco delle voci di controllo di accesso (ACL) in un elenco di controllo di accesso discrezionale (DACL) o 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 grfAccessMode membro 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 negati dall'accesso all'inizio dell'elenco di ACL per il nuovo ACL. Questa funzione inserisce tutti i nuovi ACL consentiti per l'accesso subito prima degli ACL consentiti dall'accesso esistenti.

Per un sacl, il grfAccessMode membro 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 eventuali nuovi ACL di controllo di sistema all'inizio dell'elenco di ACL per il nuovo ACL.

Esempi

Per un esempio che usa questa funzione, vedere Modifica degli elenchi di controllo di accesso 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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [app desktop \| App UWP]
server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	aclapi.h
libreria	Advapi32.lib
dll	Advapi32.dll