Função SetNamedSecurityInfoA (aclapi.h)

Artigo
11/20/2024

A função SetNamedSecurityInfo define informações de segurança especificadas no do 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 um cadeia de caracteresterminada nula 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 nomeado 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 um SID estrutura que identifica o proprietário do objeto. Se o chamador não tiver a constante SeRestorePrivilege (consulte privilege constants), 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 de SE_TAKE_OWNERSHIP_NAME habilitado. Se você não estiver definindo o proprietário SID, 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 acesso WRITE_DAC 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 do 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 de SE_SECURITY_NAME habilitado. Se você não estiver definindo o SACL, esse parâmetro poderá ser NULL.

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

Se você estiver definindo a lista de controle de acesso discricionário (DACL) ou quaisquer elementos na lista de controle de acesso do sistema (SACL) de um objeto, o sistema propagará automaticamente todas as entradas de controle de acesso (ACEs) herdáveis 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 aguardados
Objetos de mapeamento de arquivo
Objetos de serviço de diretório

A função SetNamedSecurityInfo não reordena ACEs permitidos pelo acesso ou negados pelo acesso com base na ordem preferencial. Ao propagar ACEs herdáveis para objetos filho existentes, SetNamedSecurityInfo coloca ACEs herdadas em ordem após todas as ACEs não herdadas nos DACLs dos objetos filho.

Essa função transfere informações em de texto sem formatação. 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 é 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 tomandode propriedade do objeto.

Nota

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. 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