Função GetNamedSecurityInfoA (aclapi.h)

A função GetNamedSecurityInfo recupera uma cópia 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 chamado 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 SECURITY_INFORMATION bits.

[out, optional] ppsidOwner

Um ponteiro para uma variável que recebe um ponteiro para o SID do 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 OWNER_SECURITY_INFORMATION. Além disso, esse parâmetro poderá 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 GROUP_SECURITY_INFORMATION. Além disso, esse parâmetro poderá 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 DACL_SECURITY_INFORMATION. Além disso, esse parâmetro poderá ser NULL se você não precisar da DACL.

[out, optional] ppSacl

Um ponteiro para uma variável que recebe um ponteiro para a 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 SACL_SECURITY_INFORMATION. Além disso, esse parâmetro poderá ser NULL se você não precisar da 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, ppDacl ou ppSacl não for NULL.

Retornar valor

Se a função obtiver êxito, 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.

Comentários

Se qualquer um dos parâmetros ppsidOwner, ppsidGroup, ppDacl ou ppSacl não for NULL e o parâmetro SecurityInfo especificar 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, o grupo ou a 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 Executando 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 de espera
  • 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 não criptografado. 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 seja 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.

Observação

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

Confira também

ACL

Controle de acesso

Funções básicas de Controle de Acesso

GetSecurityInfo

Localfree

Constantes de privilégio

SECURITY_DESCRIPTOR

SECURITY_INFORMATION

SE_OBJECT_TYPE

SID

SetNamedSecurityInfo

SetSecurityInfo