Função TreeSetNamedSecurityInfoW (aclapi.h)
A função TreeSetNamedSecurityInfo define informações de segurança especificadas no descritor de segurança de uma árvore de objetos especificada. Essa função permite que uma DACL ( lista de controle de acesso discricionário ) especificada ou quaisquer elementos na SACL ( lista de controle de acesso do sistema ) sejam propagados em toda uma árvore. Essa função dá suporte a uma função de retorno de chamada para acompanhar o progresso da operação de árvore.
Sintaxe
DWORD TreeSetNamedSecurityInfoW(
[in] LPWSTR pObjectName,
[in] SE_OBJECT_TYPE ObjectType,
[in] SECURITY_INFORMATION SecurityInfo,
[in, optional] PSID pOwner,
[in, optional] PSID pGroup,
[in, optional] PACL pDacl,
[in, optional] PACL pSacl,
[in] DWORD dwAction,
[in] FN_PROGRESS fnProgress,
[in] PROG_INVOKE_SETTING ProgressInvokeSetting,
[in, optional] PVOID Args
);
Parâmetros
[in] pObjectName
Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do objeto de nó raiz para os objetos que devem receber informações de segurança atualizadas. Os objetos com suporte são chaves do Registro e objetos de arquivo. 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 . Os valores com suporte são SE_REGISTRY_KEY e SE_FILE_OBJECT, para chaves do Registro e objetos de arquivo, respectivamente.
[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 SECURITY_INFORMATION bits.
[in, optional] pOwner
Um ponteiro para uma estrutura SID que identifica o proprietário do objeto. O SID deve ser aquele que pode ser atribuído como o SID proprietário de um descritor de segurança. O parâmetro SecurityInfo deve incluir o sinalizador OWNER_SECURITY_INFORMATION. Para definir o proprietário, o chamador deve ter WRITE_OWNER acesso a cada objeto, incluindo o objeto raiz. Se você não estiver definindo o SID do proprietário, esse parâmetro poderá ser NULL.
[in, optional] pGroup
Um ponteiro para uma estrutura SID que identifica o grupo primário do objeto. O parâmetro SecurityInfo deve incluir o sinalizador GROUP_SECURITY_INFORMATION. Para definir o grupo, o chamador deve ter WRITE_OWNER acesso a cada objeto, incluindo o objeto raiz. Se você não estiver definindo o SID do grupo primário, esse parâmetro poderá ser NULL.
[in, optional] pDacl
Um ponteiro para uma estrutura de ACL ( lista de controle de acesso ) que representa a nova DACL para os objetos que estão sendo redefinidos. O parâmetro SecurityInfo deve incluir o sinalizador DACL_SECURITY_INFORMATION. O chamador deve ter READ_CONTROL e WRITE_DAC acesso a cada objeto, incluindo o objeto raiz. Se você não estiver definindo a DACL, esse parâmetro poderá ser NULL.
[in, optional] pSacl
Um ponteiro para uma estrutura de ACL que representa a nova SACL para os objetos que estão sendo redefinidos. 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 a SACL, esse parâmetro poderá ser NULL.
[in] dwAction
Especifica o comportamento dessa função. Isso deve ser definido como um dos valores a seguir, definidos em AccCtrl.h.
[in] fnProgress
Um ponteiro para a função usada para acompanhar o progresso da função TreeSetNamedSecurityInfo . O protótipo da função de progresso é:
#include <windows.h>
#include <Aclapi.h>
#pragma comment(lib, "Advapi32.lib")
typedef VOID (*FN_PROGRESS) (
IN LPWSTR pObjectName, // Name of object just processed
IN DWORD Status, // Status of operation on object
IN OUT PPROG_INVOKE_SETTING
pInvokeSetting, // When to set
IN PVOID Args, // Caller specific data
IN BOOL SecuritySet // Whether security was set
);
A função de progresso fornece ao chamador informações de progresso e erro quando os nós são processados. O chamador especifica a função de progresso em fnProgress e, durante a operação de árvore, TreeSetNamedSecurityInfo passa o nome do último objeto processado, o erro status dessa operação e o valor PROG_INVOKE_SETTING atual. O chamador pode alterar o valor PROG_INVOKE_SETTING usando pInvokeSetting.
Se nenhuma função de progresso for usada, defina esse parâmetro como NULL.
[in] ProgressInvokeSetting
Um valor da enumeração PROG_INVOKE_SETTING que especifica a configuração inicial para a função de progresso.
[in, optional] Args
Um ponteiro para um VOID para argumentos de função de progresso especificados pelo chamador.
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 definido em WinError.h.
Comentários
Não há suporte para a configuração de um proprietário, grupo, DACL ou SACL NULL nessa função.
Se o chamador não contiver os privilégios e permissões adequados para dar suporte às atualizações de proprietário, grupo, DACL e SACL solicitadas, nenhuma das atualizações será executada.
Essa função fornece a mesma funcionalidade que a função SetNamedSecurityInfo quando o valor do parâmetro dwAction é definido como TREE_SEC_INFO_SET, o valor do parâmetro ProgressInvokeSetting é definido como ProgressInvokePrePostError e a função apontada pelo parâmetro fnProgress define o valor do parâmetro pInvokeSetting como ProgressInvokePrePostError.
Essa função é semelhante à função TreeResetNamedSecurityInfo :
- Se o parâmetro dwAction de TreeSetNamedSecurityInfo estiver definido como TREE_SEC_INFO_RESET_KEEP_EXPLICIT, a função será equivalente a TreeResetNamedSecurityInfo com o parâmetro KeepExplicit definido como TRUE.
- Se o parâmetro dwAction de TreeSetNamedSecurityInfo estiver definido como TREE_SEC_INFO_RESET, a função será equivalente a TreeResetNamedSecurityInfo com o parâmetro KeepExplicit definido como FALSE.
Observação
O cabeçalho aclapi.h define TreeSetNamedSecurityInfo 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 Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | aclapi.h |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de