Compartilhar via


Função TreeSetNamedSecurityInfoA (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, TreeSetNamedSecurityInfoW.

Sintaxe

DWORD TreeSetNamedSecurityInfoA(
  [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]           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 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 definidas. 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] dwAction

Especifica o comportamento dessa função. Isso deve ser definido como um dos valores a seguir, definidos em AccCtrl.h.

Valor Significado
TREE_SEC_INFO_SET
0x00000001
As informações de segurança são definidas no objeto especificado pelo parâmetro pObjectName e pela árvore de objetos filho desse objeto. Se as ACLs forem especificadas nos parâmetros pDacl ou pSacl , os descritores de segurança serão associados ao objeto . Os descritores de segurança são propagados para a árvore de objetos filho com base em suas propriedades de herança.
TREE_SEC_INFO_RESET
0x00000002
As informações de segurança são redefinidas no objeto especificado pelo parâmetro pObjectName e pela árvore de objetos filho desse objeto. Todas as informações de segurança existentes são removidas de todos os objetos na árvore.

Se qualquer objeto na árvore não conceder permissões apropriadas ao chamador para modificar o descritor de segurança no objeto, a propagação de informações de segurança nesse nó específico da árvore e seus objetos será ignorada. A operação continua no restante da árvore sob o objeto especificado pelo parâmetro pObjectName .

TREE_SEC_INFO_RESET_KEEP_EXPLICIT
0x00000003
As informações de segurança são redefinidas no objeto especificado pelo parâmetro pObjectName e pela árvore de objetos filho desse objeto. Todas as informações de segurança herdadas existentes são removidas de todos os objetos na árvore. As informações de segurança que foram explicitamente definidas em objetos na árvore não são alteradas.

Se qualquer objeto na árvore não conceder permissões apropriadas ao chamador para modificar o descritor de segurança no objeto, a propagação de informações de segurança nesse nó específico da árvore e seus objetos será ignorada. A operação continua no restante da árvore sob o objeto especificado pelo parâmetro pObjectName .

[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 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 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 de seu 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