Função SetNamedSecurityInfoA (aclapi.h)

Artigo
02/23/2024

A função SetNamedSecurityInfo define informações de segurança especificadas no descritor de segurança de um objeto especificado. O chamador identifica o objeto pelo nome.

Sintaxe

DWORD SetNamedSecurityInfoA(
  [in]           LPSTR                pObjectName,
  [in]           SE_OBJECT_TYPE       ObjectType,
  [in]           SECURITY_INFORMATION SecurityInfo,
  [in, optional] PSID                 psidOwner,
  [in, optional] PSID                 psidGroup,
  [in, optional] PACL                 pDacl,
  [in, optional] PACL                 pSacl
);

Parâmetros

[in] pObjectName

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do objeto para o qual definir informações de segurança. Esse pode ser o nome de um arquivo ou diretório local ou remoto em um sistema de arquivos NTFS, compartilhamento de rede, chave do Registro, semáforo, evento, mutex, mapeamento de arquivo ou temporizador de espera.

Para obter descrições dos formatos de cadeia de caracteres para os diferentes tipos de objeto, consulte SE_OBJECT_TYPE.

[in] ObjectType

Um valor da enumeração SE_OBJECT_TYPE que indica o tipo de objeto chamado pelo parâmetro pObjectName .

[in] SecurityInfo

Um conjunto de sinalizadores de bits que indicam o tipo de informações de segurança a serem definidas. Esse parâmetro pode ser uma combinação dos sinalizadores de bits SECURITY_INFORMATION .

[in, optional] psidOwner

Um ponteiro para uma estrutura sid que identifica o proprietário do objeto. Se o chamador não tiver a constante SeRestorePrivilege (consulte Constantes de Privilégio), esse SID deverá estar contido no token do chamador e deverá ter a permissão SE_GROUP_OWNER habilitada. O parâmetro SecurityInfo deve incluir o sinalizador OWNER_SECURITY_INFORMATION. Para definir o proprietário, o chamador deve ter WRITE_OWNER acesso ao objeto ou ter o privilégio SE_TAKE_OWNERSHIP_NAME habilitado. Se você não estiver definindo o SID proprietário, esse parâmetro poderá ser NULL.

[in, optional] psidGroup

Um ponteiro para um SID que identifica o grupo primário do objeto. O parâmetro SecurityInfo deve incluir o sinalizador GROUP_SECURITY_INFORMATION. Se você não estiver definindo o SID do grupo primário, esse parâmetro poderá ser NULL.

[in, optional] pDacl

Um ponteiro para a nova DACL para o objeto . O parâmetro SecurityInfo deve incluir o sinalizador DACL_SECURITY_INFORMATION. O chamador deve ter WRITE_DAC acesso ao objeto ou ser o proprietário do objeto. Se você não estiver definindo a DACL, esse parâmetro poderá ser NULL.

[in, optional] pSacl

Um ponteiro para o novo SACL para o objeto . O parâmetro SecurityInfo deve incluir qualquer um dos seguintes sinalizadores: SACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, SCOPE_SECURITY_INFORMATION ou BACKUP_SECURITY_INFORMATION.

Se a configuração SACL_SECURITY_INFORMATION ou SCOPE_SECURITY_INFORMATION, o chamador deverá ter o privilégio SE_SECURITY_NAME habilitado. Se você não estiver definindo o SACL, esse parâmetro poderá ser NULL.

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

Se você estiver definindo a DACL ( lista de controle de acesso) discricionária ou quaisquer elementos na SACL ( lista de controle de acesso do sistema ) de um objeto, o sistema propagará automaticamente quaisquer ACEs ( entradas de controle de acesso herdadas) para objetos filho existentes, de acordo com as regras de herança.

Você pode usar a função SetNamedSecurityInfo com os seguintes tipos de objetos:

Arquivos ou diretórios locais ou remotos em um NTFS
Impressoras locais ou remotas
Serviços locais ou remotos do Windows
Compartilhamentos de rede
Chaves do Registro
Semáforos, eventos, mutexes e temporizadores de espera
Objetos de mapeamento de arquivo
Objetos de serviço de diretório

A função SetNamedSecurityInfo não reordena ACEs com acesso permitido ou acesso negado com base na ordem preferencial. Ao propagar ACEs herdáveis para objetos filho existentes, SetNamedSecurityInfo coloca ACEs herdados em ordem após todos os ACEs não herdados nos DACLs dos objetos filho.

Essa função transfere informações em texto não criptografado. As informações transferidas por essa função são assinadas, a menos que a assinatura tenha sido desativada para o sistema, mas nenhuma criptografia seja executada.

Quando você atualiza os direitos de acesso de uma pasta indicada por um caminho UNC, por exemplo \Test\TestFolder, o ACE herdado original é removido e o caminho de volume completo não está incluído.

Exemplos

Para obter um exemplo que usa essa função, consulte Modificando as ACLs de um objeto ou tomando a propriedade do objeto.

Observação

O cabeçalho aclapi.h define SetNamedSecurityInfo 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