Função LookupSecurityDescriptorPartsA (aclapi.h)

Artigo
02/28/2024

A função LookupSecurityDescriptorParts recupera informações de segurança de um descritor de segurança auto-relativo.

Sintaxe

DWORD LookupSecurityDescriptorPartsA(
  [out, optional] PTRUSTEE_A           *ppOwner,
  [out, optional] PTRUSTEE_A           *ppGroup,
  [out, optional] PULONG               pcCountOfAccessEntries,
  [out, optional] PEXPLICIT_ACCESS_A   *ppListOfAccessEntries,
  [out, optional] PULONG               pcCountOfAuditEntries,
  [out, optional] PEXPLICIT_ACCESS_A   *ppListOfAuditEntries,
  [in]            PSECURITY_DESCRIPTOR pSD
);

Parâmetros

[out, optional] ppOwner

Um ponteiro para uma variável que recebe um ponteiro para uma estrutura TRUSTEE . A função pesquisa o nome associado ao SID (identificador de segurança) do proprietário no descritor de segurançapSD e retorna um ponteiro para o nome no membro ptstrName da estrutura TRUSTEE. A função define o membro TrusteeForm como TRUSTEE_IS_NAME.

Esse parâmetro poderá ser NULL se você não estiver interessado no nome do proprietário.

[out, optional] ppGroup

Um ponteiro para uma variável que recebe um ponteiro para uma estrutura TRUSTEE . A função pesquisa o nome associado ao SID do grupo primário do descritor de segurança e retorna um ponteiro para o nome no membro ptstrName da estrutura TRUSTEE . A função define o membro TrusteeForm como TRUSTEE_IS_NAME.

Esse parâmetro poderá ser NULL se você não estiver interessado no nome do grupo.

[out, optional] pcCountOfAccessEntries

Um ponteiro para um ULONG que recebe o número de estruturas EXPLICIT_ACCESS retornadas na matriz pListOfAccessEntries . Esse parâmetro só poderá ser NULL se o parâmetro pListOfAccessEntries também for NULL.

[out, optional] ppListOfAccessEntries

Um ponteiro para uma variável que recebe um ponteiro para uma matriz de estruturas EXPLICIT_ACCESS que descrevem as ACEs ( entradas de controle de acesso ) na DACL (lista de controle de acesso discricionário ) do descritor de segurança. A estrutura TRUSTEE nessas estruturas EXPLICIT_ACCESS usa o formulário TRUSTEE_IS_NAME. Para obter uma descrição de como uma matriz de estruturas EXPLICIT_ACCESS descreve as ACEs em uma ACL ( lista de controle de acesso ), consulte a função GetExplicitEntriesFromAcl . Se esse parâmetro for NULL, o parâmetro cCountOfAccessEntries também deverá ser NULL.

[out, optional] pcCountOfAuditEntries

Um ponteiro para um ULONG que recebe o número de estruturas EXPLICIT_ACCESS retornadas na matriz pListOfAuditEntries . Esse parâmetro só poderá ser NULL se o parâmetro pListOfAuditEntries também for NULL.

[out, optional] ppListOfAuditEntries

Um ponteiro para uma variável que recebe um ponteiro para uma matriz de estruturas EXPLICIT_ACCESS que descrevem as ACEs na SACL ( lista de controle de acesso do sistema ) do descritor de segurança. A estrutura TRUSTEE nessas estruturas EXPLICIT_ACCESS usa o formulário TRUSTEE_IS_NAME. Se esse parâmetro for NULL, o parâmetro cCountOfAuditEntries também deverá ser NULL.

[in] pSD

Um ponteiro para um descritor de segurança auto-relativo existente do qual a função recupera informações de segurança.

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 diferente de zero definido em WinError.h.

Comentários

A função LookupSecurityDescriptorParts recupera os nomes do proprietário e do grupo primário do descritor de segurança. Essa função também retorna descrições das ACEs nas entradas DACL e audit-control na SACL do descritor de segurança.

Os parâmetros diferentes de pSD poderão ser NULL se você não estiver interessado nas informações. Se você não quiser informações sobre a DACL, pListOfAccessEntries e cCountOfAuditEntries deverão ser NULL. Se você não quiser informações sobre a SACL, pListOfAuditEntries e cCountOfAuditEntries deverão ser NULL. Da mesma forma, se você quiser informações DACL ou SACL, ambos os parâmetros correspondentes não deverão ser NULL.

Quando você terminar de usar qualquer um dos buffers retornados pelos parâmetros pOwner, pGroup, pListOfAccessEntries ou pListOfAuditEntries , libere-os chamando a função LocalFree .

A função LookupSecurityDescriptorParts destina-se a servidores confiáveis que implementam ou expõem a segurança em seus próprios objetos. A função funciona com um descritor de segurança auto-relativo adequado para serialização em um fluxo e armazenamento em disco, como um servidor confiável pode exigir.

Observação

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