Função GetNamedSecurityInfoA (aclapi.h)

Artigo
11/20/2024

A função GetNamedSecurityInfo recupera uma cópia do do descritor de segurança para um objeto especificado pelo nome.

Sintaxe

DWORD GetNamedSecurityInfoA(
  [in]            LPCSTR               pObjectName,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

Parâmetros

[in] pObjectName

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do objeto do qual recuperar informações de segurança. Para obter descrições dos formatos de cadeia de caracteres para os diferentes tipos de objeto, consulte SE_OBJECT_TYPE.

[in] ObjectType

Especifica um valor da enumeração SE_OBJECT_TYPE que indica o tipo de objeto nomeado pelo parâmetro pObjectName .

[in] SecurityInfo

Um conjunto de sinalizadores de bits que indicam o tipo de informações de segurança a serem recuperadas. Esse parâmetro pode ser uma combinação dos sinalizadores de bits SECURITY_INFORMATION.

[out, optional] ppsidOwner

Um ponteiro para uma variável que recebe um ponteiro para o SID proprietário no descritor de segurança retornado em ppSecurityDescriptor ou NULL se o descritor de segurança não tiver sid proprietário. O ponteiro retornado será válido somente se você definir o sinalizador de OWNER_SECURITY_INFORMATION. Além disso, esse parâmetro pode ser NULL se você não precisar do SID do proprietário.

[out, optional] ppsidGroup

Um ponteiro para uma variável que recebe um ponteiro para o SID do grupo primário no descritor de segurança retornado ou NULL se o descritor de segurança não tiver SID de grupo. O ponteiro retornado será válido somente se você definir o sinalizador de GROUP_SECURITY_INFORMATION. Além disso, esse parâmetro pode ser NULL se você não precisar do SID do grupo.

[out, optional] ppDacl

Um ponteiro para uma variável que recebe um ponteiro para a DACL no descritor de segurança retornado ou NULL se o descritor de segurança não tiver DACL. O ponteiro retornado será válido somente se você definir o sinalizador de DACL_SECURITY_INFORMATION. Além disso, esse parâmetro pode ser NULL se você não precisar da DACL.

[out, optional] ppSacl

Um ponteiro para uma variável que recebe um ponteiro para o SACL no descritor de segurança retornado ou NULL se o descritor de segurança não tiver SACL. O ponteiro retornado será válido somente se você definir o sinalizador de SACL_SECURITY_INFORMATION. Além disso, esse parâmetro pode ser NULL se você não precisar do SACL.

[out, optional] ppSecurityDescriptor

Um ponteiro para uma variável que recebe um ponteiro para o descritor de segurança do objeto. Quando terminar de usar o ponteiro, libere o buffer retornado chamando a função LocalFree.

Esse parâmetro será necessário se qualquer um dos parâmetros ppsidOwner, ppsidGroup, ppDaclou ppSacl não for NULL.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado será um código de erro diferente de zero definido em WinError.h.

Observações

Se qualquer um dos parâmetros ppsidOwner, ppsidGroup, ppDaclou ppSacl forem nãoNULL e o parâmetro SecurityInfo especifica que eles serão recuperados do objeto, esses parâmetros apontarão para os parâmetros correspondentes no descritor de segurança retornado em ppSecurityDescriptor. Se o descritor de segurança não contiver as informações solicitadas, o parâmetro correspondente será definido como NULL.

Para ler o proprietário, grupo ou DACL do descritor de segurança do objeto, a DACL do objeto deve conceder READ_CONTROL acesso ao chamador ou o chamador deve ser o proprietário do objeto.

Para ler a lista de controle de acesso do sistema do objeto, o privilégio SE_SECURITY_NAME deve ser habilitado para o processo de chamada. Para obter informações sobre as implicações de segurança da habilitação de privilégios, consulte Em execução com privilégios especiais.

Você pode usar a função GetNamedSecurityInfo com os seguintes tipos de objetos:

Arquivos ou diretórios locais ou remotos em um sistema de arquivos NTFS
Impressoras locais ou remotas
Serviços locais ou remotos do Windows
Compartilhamentos de rede
Chaves do Registro
Semáforos, eventos, mutexes e temporizadores aguardados
Objetos de mapeamento de arquivo
Objetos de serviço de diretório

Essa função não lida com condições de corrida. Se o thread chamar essa função no momento aproximado em que outro thread alterar o descritor de segurança do objeto, essa função poderá falhar.

Essa função transfere informações em texto sem formatação. As informações transferidas por essa função são assinadas, a menos que a assinatura tenha sido desativada para o sistema, mas nenhuma criptografia é executada.

Para obter mais informações sobre como controlar o acesso a objetos por meio de contas de usuário, contas de grupo ou sessões de logon, consulte Como os DACLs controlam o acesso a um objeto.

Exemplos

Para obter um exemplo que usa GetNamedSecurityInfo, consulte Modificando as ACLs de um objeto.

Nota

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