Função AddAccessAllowedAce (securitybaseapi.h)

Artigo
03/01/2024

A função AddAccessAllowedAce adiciona uma ACE ( entrada de controle de acesso ) permitida pelo acesso a uma ACL (lista de controle de acesso ). O acesso é concedido a um SID ( identificador de segurança ) especificado.

Para controlar se o novo ACE pode ser herdado por objetos filho, use a função AddAccessAllowedAceEx .

Sintaxe

BOOL AddAccessAllowedAce(
  [in, out] PACL  pAcl,
  [in]      DWORD dwAceRevision,
  [in]      DWORD AccessMask,
  [in]      PSID  pSid
);

Parâmetros

[in, out] pAcl

Um ponteiro para uma ACL. Essa função adiciona um ACE com permissão de acesso ao final dessa ACL. O ACE está na forma de uma estrutura ACCESS_ALLOWED_ACE .

[in] dwAceRevision

Especifica o nível de revisão da ACL que está sendo modificada.

Esse valor pode ser ACL_REVISION ou ACL_REVISION_DS. Use ACL_REVISION_DS se a ACL contiver ACEs específicas do objeto.

[in] AccessMask

Especifica a máscara de direitos de acesso a ser concedida ao SID especificado.

[in] pSid

Um ponteiro para o SID que representa uma conta de usuário, grupo ou logon que recebe acesso.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError. Veja a seguir valores de erro possíveis.

Código de retorno	Descrição
ERROR_ALLOTTED_SPACE_EXCEEDED	O novo ACE não se encaixa na ACL. Um buffer de ACL maior é necessário.
ERROR_INVALID_ACL	A ACL especificada não é formada corretamente.
ERROR_INVALID_SID	O SID especificado não é estruturalmente válido.
ERROR_REVISION_MISMATCH	A revisão especificada não é conhecida ou é incompatível com a da ACL.
ERROR_SUCCESS	O ACE foi adicionado com êxito.

Comentários

A adição de um ACE permitido pelo acesso a uma ACL é a forma mais comum de modificação de ACL.

As funções AddAccessAllowedAce e AddAccessDeniedAce adicionam um novo ACE ao final da lista de ACEs para a ACL. Essas funções não colocam automaticamente o novo ACE na ordem canônica adequada. É responsabilidade do chamador garantir que a ACL esteja em ordem canônica adicionando ACEs na sequência adequada.

A estrutura ACE_HEADER colocada no ACE pela função AddAccessAllowedAce especifica um tipo e tamanho, mas não fornece herança nem sinalizadores ACE.

Exemplos

Para obter um exemplo que usa essa função, consulte Iniciando um processo de cliente interativo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	securitybaseapi.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll