Função LookupSecurityDescriptorPartsW (aclapi.h)

Artigo
07/16/2024

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

Sintaxe

DWORD LookupSecurityDescriptorPartsW(
  [out, optional] PTRUSTEE_W           *ppOwner,
  [out, optional] PTRUSTEE_W           *ppGroup,
  [out, optional] PULONG               pcCountOfAccessEntries,
  [out, optional] PEXPLICIT_ACCESS_W   *ppListOfAccessEntries,
  [out, optional] PULONG               pcCountOfAuditEntries,
  [out, optional] PEXPLICIT_ACCESS_W   *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 proprietário SID ( identificador de segurança) no do descritor de segurança depSD e retorna um ponteiro para o nome no ptstrName membro da estrutura TRUSTEE. A função define o membro TrusteeForm como TRUSTEE_IS_NAME.

Esse parâmetro pode 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 ptstrName membro da estrutura TRUSTEE. A função define o membro TrusteeForm como TRUSTEE_IS_NAME.

Esse parâmetro pode 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 de pListOfAccessEntries . Esse parâmetro pode ser NULL somente se o parâmetro pListOfAccessEntries também estiver NULL.

[out, optional] ppListOfAccessEntries

Um ponteiro para uma variável que recebe um ponteiro para uma matriz de estruturas de EXPLICIT_ACCESS que descrevem as entradas de controle de acesso (ACEs) na lista de controle de acesso discricionário (DACL) do descritor de segurança. A estrutura TRUSTEE nessas estruturas de EXPLICIT_ACCESS usa o formulário TRUSTEE_IS_NAME. Para obter uma descrição de como uma matriz de estruturas de EXPLICIT_ACCESS descreve as ACEs em uma lista de controle de acesso (ACL), 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 de pListOfAuditEntries . Esse parâmetro poderá ser NULL somente se o parâmetro pListOfAuditEntries também estiver NULL.

[out, optional] ppListOfAuditEntries

Um ponteiro para uma variável que recebe um ponteiro para uma matriz de estruturas de EXPLICIT_ACCESS que descrevem as ACEs na lista de controle de acesso do sistema (SACL) do descritor de segurança. A estrutura TRUSTEE nessas estruturas de 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.

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

Observações

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 dos ACEs nas entradas DACL e de controle de auditoria no SACL do descritor de segurança.

Os parâmetros diferentes de pSD podem 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 o 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 terminar de usar qualquer um dos buffers retornados pelo pOwner, pGroup, pListOfAccessEntriesou pListOfAuditEntries parâmetros, 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 serializar em um fluxo e armazenar em disco, como um servidor confiável pode exigir.

Nota

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 do 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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	aclapi.h
biblioteca	Advapi32.lib
de DLL	Advapi32.dll