Funzione AddAce (securitybaseapi.h)

Articolo
03/01/2024

La funzione AddAce aggiunge una o più voci di controllo di accesso (ACL) a un elenco di controllo di accesso (ACL) specificato.

Sintassi

BOOL AddAce(
  [in, out] PACL   pAcl,
  [in]      DWORD  dwAceRevision,
  [in]      DWORD  dwStartingAceIndex,
  [in]      LPVOID pAceList,
  [in]      DWORD  nAceListLength
);

Parametri

[in, out] pAcl

Puntatore a un elenco di controllo di accesso. Questa funzione aggiunge un ace a questo elenco di controllo di accesso.

[in] dwAceRevision

Specifica il livello di revisione dell'ACL da modificare.

Questo valore può essere ACL_REVISION o ACL_REVISION_DS. Usare ACL_REVISION_DS se l'ACL contiene ACL specifici dell'oggetto. Questo valore deve essere compatibile con il campo AceType di tutti gli ACL in pAceList. In caso contrario, la funzione avrà esito negativo e imposterà l'ultimo errore su ERROR_INVALID_PARAMETER.

[in] dwStartingAceIndex

Specifica la posizione nell'elenco di ACL di ACL in cui aggiungere nuovi ACL. Il valore zero inserisce gli ACL all'inizio dell'elenco. Il valore MAXDWORD aggiunge gli ACL alla fine dell'elenco.

[in] pAceList

Puntatore a un elenco di uno o più ACL da aggiungere all'elenco di controllo di accesso specificato. Gli ACL nell'elenco devono essere archiviati in modo contiguo.

[in] nAceListLength

Specifica le dimensioni, in byte, del buffer di input a cui punta il parametro pAceList .

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. Di seguito sono riportati i possibili valori di errore.

Codice restituito	Descrizione
ERROR_INSUFFICIENT_BUFFER	La nuova ace non rientra nell'elenco di controllo di accesso. È necessario un buffer ACL più grande.
ERROR_INVALID_PARAMETER	L'elenco di controllo di accesso specificato non è formato correttamente.
ERROR_SUCCESS	L'ace è stato aggiunto correttamente.

Commenti

Le applicazioni usano spesso le funzioni FindFirstFreeAce e GetAce quando si usa la funzione AddAce per modificare un ACL. Inoltre, la struttura ACL_SIZE_INFORMATION recuperata dalla funzione GetAclInformation contiene le dimensioni dell'ACL e il numero di ACL che contiene.

Esempio

Per un esempio che usa questa funzione, vedere Avvio di un processo client interattivo.

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	securitybaseapi.h (include Windows.h)
Libreria	Advapi32.lib
DLL	Advapi32.dll