Função GetNamedSecurityInfoA (aclapi.h)

Artigo
02/23/2024

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