Funzione AddAccessAllowedObjectAce (securitybaseapi.h)

Articolo
08/25/2023

La funzione AddAccessAllowedObjectAce aggiunge una voce di controllo di accesso consentita per l'accesso (ACE) alla fine di un elenco di controllo di accesso discrezionale (DACL). Il nuovo ACE può concedere l'accesso a un oggetto o a un set di proprietà o a una proprietà in un oggetto. È anche possibile usare AddAccessAllowedObjectAce per aggiungere un ACE che può ereditare solo un tipo specificato di oggetto figlio.

Sintassi

BOOL AddAccessAllowedObjectAce(
  [in, out]      PACL  pAcl,
  [in]           DWORD dwAceRevision,
  [in]           DWORD AceFlags,
  [in]           DWORD AccessMask,
  [in, optional] GUID  *ObjectTypeGuid,
  [in, optional] GUID  *InheritedObjectTypeGuid,
  [in]           PSID  pSid
);

Parametri

[in, out] pAcl

Puntatore a un elenco di controllo livello dati. La funzione AddAccessAllowedObjectAce aggiunge un ACE consentito per l'accesso alla fine di questa daCL. L'ACE è sotto forma di una struttura ACCESS_ALLOWED_OBJECT_ACE .

[in] dwAceRevision

Specifica il livello di revisione dell'elenco dati da modificare. Questo valore deve essere ACL_REVISION_DS. Se il livello di revisione dell'elenco dati è inferiore a ACL_REVISION_DS, la funzione viene modificata in ACL_REVISION_DS.

[in] AceFlags

Set di flag di bit che controllano l'ereditarietà ACE. La funzione imposta questi flag nel membro AceFlags della struttura ACE_HEADER del nuovo ACE. Questo parametro può essere una combinazione dei valori seguenti.

Valore	Significato
CONTAINER_INHERIT_ACE	L'ACE viene ereditato dagli oggetti contenitore.
INHERIT_ONLY_ACE	L'ACE non si applica all'oggetto a cui viene assegnato l'elenco di controllo di accesso , ma può essere ereditato dagli oggetti figlio.
INHERITED_ACE	Indica un ACE ereditato. Questo flag consente alle operazioni che modificano la sicurezza in un albero di oggetti per modificare gli ACL ereditati, senza modificare gli ACL applicati direttamente all'oggetto.
NO_PROPAGATE_INHERIT_ACE	I bit di OBJECT_INHERIT_ACE e CONTAINER_INHERIT_ACE non vengono propagati a un ACE ereditato.
OBJECT_INHERIT_ACE	L'ACE viene ereditato da oggetti noncontainer.

[in] AccessMask

Set di flag di bit che usano il formato ACCESS_MASK . Questi flag specificano i diritti di accesso che il nuovo ACE consente l'identificatore di sicurezza (SID) specificato.

[in, optional] ObjectTypeGuid

Puntatore a una struttura GUID che identifica il tipo di oggetto, il set di proprietà o la proprietà protetta dal nuovo ACE. Se questo parametro è NULL, il nuovo ACE protegge l'oggetto a cui viene assegnato l'elenco dati.

[in, optional] InheritedObjectTypeGuid

Puntatore a una struttura GUID che identifica il tipo di oggetto che può ereditare il nuovo ACE. Se questo parametro non è NULL, solo il tipo di oggetto specificato può ereditare l'ACE. Se NULL, qualsiasi tipo di oggetto figlio può ereditare l'ACE. In entrambi i casi, l'ereditarietà è controllata anche dal valore del parametro AceFlags , nonché da qualsiasi protezione contro l'ereditarietà inserita negli oggetti figlio.

[in] pSid

Puntatore a un SID che identifica la sessione utente, gruppo o accesso a cui il nuovo ACE consente l'accesso.

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 valori di errore possibili.

Codice restituito	Descrizione
ERROR_ALLOTTED_SPACE_EXCEEDED	Il nuovo ACE non rientra nell'ACL. È necessario un buffer ACL più grande.
ERROR_INVALID_ACL	L'elenco di controllo di accesso specificato non è formato correttamente.
ERROR_INVALID_FLAGS	Il parametro AceFlags non è valido.
ERROR_INVALID_SID	Il SID specificato non è valido in modo strutturale.
ERROR_REVISION_MISMATCH	La revisione specificata non è nota o non è compatibile con quella dell'ACL.
ERROR_SUCCESS	L'ACE è stato aggiunto correttamente.

Commenti

Se sia ObjectTypeGuid che InheritedObjectTypeGuid sono NULL, usare la funzione AddAccessAllowedAceEx anziché AddAccessAllowedObjectAce. Questo è suggerito perché un ACCESS_ALLOWED_ACE è più piccolo e più efficiente di un ACCESS_ALLOWED_OBJECT_ACE.

Il chiamante deve assicurarsi che gli ACL vengano aggiunti all'elenco di controllo livello dati nell'ordine corretto. Per altre informazioni, vedere Order of ACEs in a DACL.For more information, see Order of ACEs in a DACL.

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