Função TreeResetNamedSecurityInfoA (aclapi.h)

Não há suporte para esta versão dessa função. Há suporte para a versão de caractere largo dessa função, TreeResetNamedSecurityInfoW.

Sintaxe

DWORD TreeResetNamedSecurityInfoA(
  [in]           LPSTR                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 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 chamado 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 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 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 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 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 aces definidos explicitamente são mantidos ou excluídos para a subárvore. Se KeepExplicit for TRUE, as ACEs explicitamente definidas serão mantidas para cada DACL e SACL de subárvore e as ACEs herdadas serão substituídas pelos ACEs herdados de pDacl e pSacl. Se KeepExplicit for FALSE, os ACEs definidos explicitamente para cada DACL e SACL de subárvore serão excluídos antes que os ACEs herdados sejam substituídos pelos ACEs herdados 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 fnProgress e, durante a operação de árvore, TreeResetNamedSecurityInfo 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 da 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 é semelhante à função TreeSetNamedSecurityInfo :

• Se o parâmetro KeepExplicit de TreeResetNamedSecurityInfo estiver 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 estiver definido como FALSE, a função será equivalente a TreeSetNamedSecurityInfo com o parâmetro dwAction definido como TREE_SEC_INFO_RESET.

Observação

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