Função AddAce (securitybaseapi.h)

Artigo
03/01/2024

A função AddAce adiciona uma ou mais ACEs (entradas de controle de acesso ) a uma ACL ( lista de controle de acesso ) especificada.

Sintaxe

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

Parâmetros

[in, out] pAcl

Um ponteiro para uma ACL. Essa função adiciona um ACE a essa ACL.

[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. Esse valor deve ser compatível com o campo AceType de todos os ACEs em pAceList. Caso contrário, a função falhará e definirá o último erro como ERROR_INVALID_PARAMETER.

[in] dwStartingAceIndex

Especifica a posição na lista de ACEs da ACL na qual adicionar novos ACEs. Um valor zero insere os ACEs no início da lista. Um valor de MAXDWORD acrescenta os ACEs ao final da lista.

[in] pAceList

Um ponteiro para uma lista de um ou mais ACEs a serem adicionados à ACL especificada. Os ACEs na lista devem ser armazenados contíguamente.

[in] nAceListLength

Especifica o tamanho, em bytes, do buffer de entrada apontado pelo parâmetro pAceList .

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_INSUFFICIENT_BUFFER	O novo ACE não se encaixa na ACL. Um buffer de ACL maior é necessário.
ERROR_INVALID_PARAMETER	A ACL especificada não é formada corretamente.
ERROR_SUCCESS	O ACE foi adicionado com êxito.

Comentários

Os aplicativos frequentemente usam as funções FindFirstFreeAce e GetAce ao usar a função AddAce para manipular uma ACL. Além disso, a estrutura ACL_SIZE_INFORMATION recuperada pela função GetAclInformation contém o tamanho da ACL e o número de ACEs que ela contém.

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