Função SetEntriesInAclA (aclapi.h)

Artigo
11/20/2024

A função SetEntriesInAcl cria uma nova lista de controle de acesso (ACL) mesclando novas informações de controle de acesso ou controle de auditoria em uma estrutura 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 de 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.

Valor de retorno

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.

Observações

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 de SID (identificador de segurança), como um identificador de logon ou tipo de logon (por exemplo, um serviço do 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 entradas de controle de acesso (ACEs) em uma lista de controle de acesso discricionário (DACL) ou uma lista de controle de acesso do sistema (SACL). Observe que SetEntriesInAcl não impede que você misture informações de controle de acesso e controle de auditoria no mesmo acl; no entanto, a ACL resultante conterá entradas sem sentido.

Para um DACL, o grfAccessMode membro da estrutura EXPLICIT_ACCESS especifica se os direitos de acesso devem ser permitidos, negados ou revogados 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 pelo acesso no início da lista de ACEs para o novode ACL . Essa função coloca quaisquer novas ACEs permitidas pelo acesso pouco antes de qualquer ACEs existentes permitidas pelo acesso.

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 quaisquer novas 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 tomandode propriedade de objeto.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	aclapi.h
biblioteca	Advapi32.lib
de DLL	Advapi32.dll