Função NetQueryDisplayInformation (lmaccess.h)
A função NetQueryDisplayInformation retorna informações de conta de usuário, computador ou conta de grupo. Chame essa função para enumerar rapidamente as informações da conta para exibição em interfaces do usuário.
Sintaxe
NET_API_STATUS NET_API_FUNCTION NetQueryDisplayInformation(
[in] LPCWSTR ServerName,
[in] DWORD Level,
[in] DWORD Index,
[in] DWORD EntriesRequested,
[in] DWORD PreferredMaximumLength,
[out] LPDWORD ReturnedEntryCount,
[out] PVOID *SortedBuffer
);
Parâmetros
[in] ServerName
Ponteiro para uma cadeia de caracteres constante que especifica o nome DNS ou NetBIOS do servidor remoto no qual a função deve ser executada. Se esse parâmetro for NULL, o computador local será usado.
[in] Level
Especifica o nível de informações dos dados. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Retornar informações da conta de usuário. O parâmetro SortedBuffer aponta para uma matriz de estruturas de NET_DISPLAY_USER . |
|
Retornar informações individuais do computador. O parâmetro SortedBuffer aponta para uma matriz de estruturas NET_DISPLAY_MACHINE . |
|
Retornar informações da conta do grupo. O parâmetro SortedBuffer aponta para uma matriz de estruturas de NET_DISPLAY_GROUP . |
[in] Index
Especifica o índice da primeira entrada para a qual recuperar informações. Especifique zero para recuperar informações da conta começando com a primeira entrada de informações de exibição. Para obter mais informações, consulte a seção Comentários a seguir.
[in] EntriesRequested
Especifica o número máximo de entradas para as quais recuperar informações. No Windows 2000 e posterior, cada chamada para NetQueryDisplayInformation retorna no máximo 100 objetos.
[in] PreferredMaximumLength
Especifica o tamanho máximo preferencial, em bytes, do buffer alocado pelo sistema retornado no parâmetro SortedBuffer . É recomendável que você defina esse parâmetro como MAX_PREFERRED_LENGTH.
[out] ReturnedEntryCount
Ponteiro para um valor que recebe o número de entradas no buffer retornado no parâmetro SortedBuffer . Se esse parâmetro for zero, não haverá entradas com um índice tão grande quanto o especificado. As entradas podem ser retornadas quando o valor retornado da função é NERR_Success ou ERROR_MORE_DATA.
[out] SortedBuffer
Ponteiro para um buffer que recebe um ponteiro para um buffer alocado pelo sistema que especifica uma lista classificada das informações solicitadas. O formato desses dados depende do valor do parâmetro Level . Como esse buffer é alocado pelo sistema, ele deve ser liberado usando a função NetApiBufferFree . Observe que você deve liberar o buffer mesmo que a função falhe com ERROR_MORE_DATA. Para obter mais informações, consulte a seção Valores retornados a seguir e os tópicos Buffers de Função de Gerenciamento de Rede e Comprimentos do Buffer de Função de Gerenciamento de Rede.
Valor retornado
Se a função for bem-sucedida, o valor retornado será NERR_Success.
Se a função falhar, o valor retornado será um dos seguintes códigos de erro.
| Código de retorno | Descrição |
|---|---|
|
O usuário não tem acesso às informações solicitadas. |
|
O parâmetro Level especifica um valor inválido. |
|
Mais entradas estão disponíveis. Ou seja, a última entrada retornada no parâmetro SortedBuffer não é a última entrada disponível. Para recuperar entradas adicionais, chame NetQueryDisplayInformation novamente com o parâmetro Index definido como o valor retornado no membro next_index da última entrada em SortedBuffer. Observe que você não deve usar o valor do membro next_index para qualquer finalidade, exceto para recuperar mais dados com chamadas adicionais para NetQueryDisplayInformation. |
Comentários
Se você chamar essa função em um controlador de domínio que está executando o Active Directory, o acesso será permitido ou negado com base na ACL (lista de controle de acesso) do objeto protegível. A ACL padrão permite que todos os usuários autenticados e membros do grupo "Acesso compatível com o Pré-Windows 2000" exibam as informações. Se você chamar essa função em um servidor membro ou estação de trabalho, todos os usuários autenticados poderão exibir as informações. Para obter informações sobre acesso anônimo e restrição de acesso anônimo nessas plataformas, consulte Requisitos de segurança para as funções de gerenciamento de rede. Para obter mais informações sobre ACLs, ACEs e tokens de acesso, consulte Controle de Acesso Model.
A função NetQueryDisplayInformation retorna apenas informações às quais o chamador tem acesso de leitura. O chamador deve ter acesso de Conteúdo de Lista ao objeto Domain e enumerar todo o acesso ao domínio SAM no objeto sam server localizado no contêiner Do sistema.
As funções NetQueryDisplayInformation e NetGetDisplayInformationIndex fornecem um mecanismo eficiente para enumerar contas de usuário e grupo. Quando possível, use essas funções em vez da função NetUserEnum ou da função NetGroupEnum .
Para enumerar domínios confiáveis ou contas de computador membro, chame NetUserEnum, especificando o valor de filtro apropriado para obter as informações de conta necessárias. Para enumerar domínios confiáveis, chame a função LsaEnumerateTrustedDomains ou LsaEnumerateTrustedDomainsEx .
O número de entradas retornadas por essa função depende do descritor de segurança localizado no objeto de domínio raiz. A API retornará as primeiras 100 entradas ou todo o conjunto de entradas no domínio, dependendo dos privilégios de acesso do usuário. O ACE usado para controlar esse comportamento é "SAM-Enumerate-Entire-Domain" e é concedido a Usuários Autenticados por padrão. Os administradores podem modificar essa configuração para permitir que os usuários enumerem todo o domínio.
Cada chamada para NetQueryDisplayInformation retorna no máximo 100 objetos. Chamar a função NetQueryDisplayInformation para enumerar informações da conta de domínio pode ser caro em termos de desempenho. Se você estiver programando para o Active Directory, poderá usar métodos na interface IDirectorySearch para fazer consultas paginadas no domínio. Para obter mais informações, consulte IDirectorySearch::SetSearchPreference e IDirectorySearch::ExecuteSearch. Para enumerar domínios confiáveis, chame a função LsaEnumerateTrustedDomainsEx .
Exemplos
O exemplo de código a seguir demonstra como retornar informações de conta de grupo usando uma chamada para a função NetQueryDisplayInformation . Se o usuário especificar um nome de servidor, o exemplo primeiro chamará a função MultiByteToWideChar para converter o nome em Unicode. O exemplo chama NetQueryDisplayInformation, especificando o nível de informações 3 (NET_DISPLAY_GROUP) para recuperar informações da conta de grupo. Se houver entradas a serem retornadas, o exemplo retornará os dados e imprimirá as informações do grupo. Por fim, o exemplo de código libera a memória alocada para o buffer de informações.
#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <stdio.h>
#include <lm.h>
#pragma comment(lib, "netapi32.lib")
void main( int argc, char *argv[ ] )
{
PNET_DISPLAY_GROUP pBuff, p;
DWORD res, dwRec, i = 0;
//
// You can pass a NULL or empty string
// to retrieve the local information.
//
TCHAR szServer[255]=TEXT("");
if(argc > 1)
//
// Check to see if a server name was passed;
// if so, convert it to Unicode.
//
MultiByteToWideChar(CP_ACP, 0, argv[1], -1, szServer, 255);
do // begin do
{
//
// Call the NetQueryDisplayInformation function;
// specify information level 3 (group account information).
//
res = NetQueryDisplayInformation(szServer, 3, i, 1000, MAX_PREFERRED_LENGTH, &dwRec, (PVOID*) &pBuff);
//
// If the call succeeds,
//
if((res==ERROR_SUCCESS) || (res==ERROR_MORE_DATA))
{
p = pBuff;
for(;dwRec>0;dwRec--)
{
//
// Print the retrieved group information.
//
printf("Name: %S\n"
"Comment: %S\n"
"Group ID: %u\n"
"Attributes: %u\n"
"--------------------------------\n",
p->grpi3_name,
p->grpi3_comment,
p->grpi3_group_id,
p->grpi3_attributes);
//
// If there is more data, set the index.
//
i = p->grpi3_next_index;
p++;
}
//
// Free the allocated memory.
//
NetApiBufferFree(pBuff);
}
else
printf("Error: %u\n", res);
//
// Continue while there is more data.
//
} while (res==ERROR_MORE_DATA); // end do
return;
}
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | lmaccess.h (inclua Lm.h) |
| Biblioteca | Netapi32.lib |
| DLL | Netapi32.dll |