Função TreeResetNamedSecurityInfoW (aclapi.h)

Artigo
11/20/2024

A função TreeResetNamedSecurityInfo redefine informações de segurança especificadas no descritor de segurança de uma árvore de objetos especificada. Essa função permite que uma lista de controle de acesso discricionário especificada (DACL) ou quaisquer elementos na lista de controle de acesso do sistema (SACL) seja propagada 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 TreeResetNamedSecurityInfoW(
  [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]           BOOL                 KeepExplicit,
  [in, optional] FN_PROGRESS          fnProgress,
  [in]           PROG_INVOKE_SETTING  ProgressInvokeSetting,
  [in, optional] PVOID                Args
);

Parâmetros

[in] pObjectName

Ponteiro para um cadeia de caracteresterminada nula 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 redefinidas. Esse parâmetro pode ser uma combinação dos sinalizadores de bits SECURITY_INFORMATION.

[in, optional] pOwner

Um ponteiro para um SID estrutura 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 proprietário, esse parâmetro poderá ser NULL.

[in, optional] pGroup

Um ponteiro para um SID estrutura 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 (ACL) de 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 acesso READ_CONTROL e WRITE_DAC 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 o novo 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 de SE_SECURITY_NAME habilitado. Se você não estiver definindo o SACL, esse parâmetro poderá ser NULL.

[in] KeepExplicit

Valor booliano que define se as ACEs definidas explicitamente são mantidas ou excluídas para a subárvore. Se KeepExplicit for VERDADEIRO, as ACEs definidas explicitamente serão mantidas para cada DACL e SACL de subárvore e as ACEs herdadas serão substituídas pelas ACEs herdadas de pDacl e pSacl. Se KeepExplicit for FALSE, as ACEs definidas explicitamente para cada DACL e SACL de subárvore serão excluídas antes que as ACEs herdadas sejam substituídas pelas ACEs herdadas de pDacl e pSacl.

[in, optional] fnProgress

Um ponteiro para a função usada para acompanhar o progresso da função TreeResetNamedSecurityInfo. O protótipo da função de progresso é:

#include <windows.h>
#include <Aclapi.h>

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 fnProgresse, durante a operação de árvore, TreeResetNamedSecurityInfo passa o nome do último objeto processado, o status de erro 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 para NULL.

[in] ProgressInvokeSetting

Um valor da enumeração PROG_INVOKE_SETTING que especifica a configuração inicial da função de progresso.

[in, optional] Args

Um ponteiro para um VOID para argumentos de função de progresso especificados pelo chamador.

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 definido em WinError.h.

Observações

Não há suporte para definir um proprietário, grupo, DACL ou SACL de NULL.

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 é semelhante à função TreeSetNamedSecurityInfo:

Se o parâmetro KeepExplicit de TreeResetNamedSecurityInfo for definido como TRUE, a função será equivalente a TreeSetNamedSecurityInfo com o parâmetro dwAction definido como TREE_SEC_INFO_RESET_KEEP_EXPLICIT.
Se o parâmetro KeepExplicit de TreeResetNamedSecurityInfo for definido como FALSE, a função será equivalente a TreeSetNamedSecurityInfo com o parâmetro dwAction definido como TREE_SEC_INFO_RESET.

Nota

O cabeçalho aclapi.h define TreeResetNamedSecurityInfo 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 [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	aclapi.h
biblioteca	Advapi32.lib
de DLL	Advapi32.dll

Compartilhar via