Função SetEntriesInAclA (aclapi.h)

Artigo
02/26/2024

A função SetEntriesInAcl cria uma nova ACL ( lista de controle de acesso ) mesclando novas informações de controle de acesso ou controle de auditoria em uma estrutura de ACL existente.

Sintaxe

DWORD SetEntriesInAclA(
  [in]           ULONG              cCountOfExplicitEntries,
  [in, optional] PEXPLICIT_ACCESS_A pListOfExplicitEntries,
  [in, optional] PACL               OldAcl,
  [out]          PACL               *NewAcl
);

Parâmetros

[in] cCountOfExplicitEntries

O número de estruturas EXPLICIT_ACCESS na matriz pListOfExplicitEntries .

[in, optional] pListOfExplicitEntries

Um ponteiro para uma matriz de estruturas de EXPLICIT_ACCESS que descrevem as informações de controle de acesso a serem mescladas na ACL existente.

[in, optional] OldAcl

Um ponteiro para a ACL existente. Esse parâmetro pode ser NULL, nesse caso, a função cria uma nova ACL com base nas entradas EXPLICIT_ACCESS .

[out] NewAcl

Um ponteiro para uma variável que recebe um ponteiro para a nova ACL. Se a função for bem-sucedida, você deverá chamar a função LocalFree para liberar o buffer retornado.

Retornar valor

Se a função for bem-sucedida, a função retornará ERROR_SUCCESS.

Se a função falhar, ela retornará um código de erro diferente de zero definido em WinError.h.

Comentários

Cada entrada na matriz de estruturas de EXPLICIT_ACCESS especifica informações de controle de acesso ou controle de auditoria para um administrador especificado. Um administrador pode ser um usuário, um grupo ou outro valor sid ( identificador de segurança ), como um identificador de logon ou um tipo de logon (por exemplo, um serviço windows ou trabalho em lote). Você pode usar um nome ou um SID para identificar um administrador.

Você pode usar a função SetEntriesInAcl para modificar a lista de ACEs ( entradas de controle de acesso ) em uma DACL ( lista de controle de acesso discricionário ) ou uma SACL ( lista de controle de acesso do sistema ). Observe que SetEntriesInAcl não impede que você misture informações de controle de acesso e controle de auditoria na mesma ACL; no entanto, a ACL resultante conterá entradas sem sentido.

Para uma DACL, o membro grfAccessMode da estrutura EXPLICIT_ACCESS especifica se deseja permitir, negar ou revogar direitos de acesso para o administrador. Esse membro pode especificar um dos seguintes valores:

GRANT_ACCESS
SET_ACCESS
DENY_ACCESS
REVOKE_ACCESS

Para obter informações sobre esses valores, consulte ACCESS_MODE.

A função SetEntriesInAcl coloca quaisquer novos ACEs negados por acesso no início da lista de ACEs para a nova ACL. Essa função coloca todos os novos ACEs permitidos pelo acesso pouco antes de qualquer ACEs permitidos para acesso existentes.

Para um SACL, o membro grfAccessMode da estrutura EXPLICIT_ACCESS pode especificar os seguintes valores:

REVOKE_ACCESS
SET_AUDIT_FAILURE
SET_AUDIT_SUCCESS

SET_AUDIT_FAILURE e SET_AUDIT_SUCCESS podem ser combinados. Para obter informações sobre esses valores, consulte ACCESS_MODE.

A função SetEntriesInAcl coloca todos os novos ACEs de auditoria do sistema no início da lista de ACEs para a nova ACL.

Exemplos

Para obter um exemplo que usa essa função, consulte Modificando as ACLs de um objeto ou Criando um descritor de segurança para um novo objeto ou Tomando a propriedade do objeto.

Observação

O cabeçalho aclapi.h define SetEntriesInAcl como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

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	aclapi.h
Biblioteca	Advapi32.lib
DLL	Advapi32.dll