Função TreeSetNamedSecurityInfoA (aclapi.h)

Artigo
11/20/2024

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 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 definidas. 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] dwAction

Especifica o comportamento dessa função. Isso deve ser definido como um dos seguintes valores, 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 a árvore de objetos filho desse objeto. Se as ACLs forem especificadas no pDacl ou parâmetros de 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 a á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 a á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 fnProgresse, durante a operação de árvore, TreeSetNamedSecurityInfo 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 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 ProgressInvokePrePostErrore a função apontada pelo parâmetro fnProgress define o valor de seu parâmetro pInvokeSetting para 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 VERDADEIRO.
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.

Nota

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

Compartilhar via