Função NetServerEnum (lmserver.h)
A função NetServerEnum lista todos os servidores do tipo especificado visíveis em um domínio.
Sintaxe
NET_API_STATUS NET_API_FUNCTION NetServerEnum(
[in, optional] LMCSTR servername,
[in] DWORD level,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in] DWORD servertype,
[in, optional] LMCSTR domain,
[in, out, optional] LPDWORD resume_handle
);
Parâmetros
[in, optional] servername
Reservados; deve ser NULL.
[in] level
O nível de informações dos dados solicitados. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Retornar nomes de servidor e informações de plataforma. O parâmetro bufptr aponta para uma matriz de estruturas SERVER_INFO_100 . |
|
Retornar nomes de servidor, tipos e dados associados. O parâmetro bufptr aponta para uma matriz de estruturas SERVER_INFO_101 . |
[out] bufptr
Um ponteiro para o buffer que recebe os dados. O formato desses dados depende do valor do parâmetro level . Esse buffer é alocado pelo sistema e 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.
[in] prefmaxlen
O comprimento máximo preferencial dos dados retornados, em bytes. Se você especificar MAX_PREFERRED_LENGTH, a função alocará a quantidade de memória necessária para os dados. Se você especificar outro valor nesse parâmetro, ele poderá restringir o número de bytes retornados pela função. Se o tamanho do buffer for insuficiente para manter todas as entradas, a função retornará ERROR_MORE_DATA. Para obter mais informações, consulte Buffers de função de gerenciamento de rede e Comprimentos de buffer de função de gerenciamento de rede.
[out] entriesread
Um ponteiro para um valor que recebe a contagem de elementos realmente enumerados.
[out] totalentries
Um ponteiro para um valor que recebe o número total de servidores e estações de trabalho visíveis na rede. Observe que os aplicativos devem considerar esse valor apenas como uma dica.
[in] servertype
Um valor que filtra as entradas do servidor a serem retornadas da enumeração . Esse parâmetro pode ser uma combinação dos valores a seguir definidos no arquivo de cabeçalho Lmserver.h .
[in, optional] domain
Um ponteiro para uma cadeia de caracteres constante que especifica o nome do domínio para o qual uma lista de servidores deve ser retornada. O nome de domínio deve ser um nome de domínio NetBIOS (por exemplo, microsoft). A função NetServerEnum não dá suporte a nomes de estilo DNS (por exemplo, microsoft.com).
Se esse parâmetro for NULL, o domínio primário estará implícito.
[in, out, optional] resume_handle
Reservados; deve ser definido como zero.
Retornar valor
Se a função for bem-sucedida, o valor retornado será NERR_Success.
Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de erro:
| Valor/código retornado | Descrição |
|---|---|
|
O acesso foi negado. |
|
O parâmetro está incorreto. |
|
Mais entradas estão disponíveis. Especifique um buffer grande o suficiente para receber todas as entradas. |
|
Nenhum servidor de navegador encontrado. |
|
A solicitação não terá suporte. |
|
Ocorreu um erro remoto sem dados retornados pelo servidor. |
|
O serviço de servidor não foi iniciado. |
|
O serviço não foi iniciado. |
|
O serviço estação de trabalho não foi iniciado. O serviço de estação de trabalho local é usado para se comunicar com um servidor remoto de nível inferior. |
Comentários
A função NetServerEnum é usada para listar todos os servidores do tipo especificado que estão visíveis em um domínio. Por exemplo, um aplicativo pode chamar NetServerEnum para listar apenas todos os controladores de domínio ou todos os servidores que executam instâncias do SQL Server apenas.
Um aplicativo combina as máscaras de bits para vários tipos de servidor no parâmetro servertype para listar vários tipos. Por exemplo, um valor de SV_TYPE_WORKSTATION | SVTYPE_SERVER (0x00000003) combina as máscaras de bits para SV_TYPE_WORKSTATION (0x00000001) e SV_TYPE_SERVER (0x00000002).
Se você precisar de mais informações para um servidor específico, chame a função WNetEnumResource .
Nenhuma associação de grupo especial é necessária para executar com êxito a função NetServerEnum .
Se você especificar o valor SV_TYPE_LOCAL_LIST_ONLY, a função NetServerEnum retornará a lista de servidores que o navegador mantém internamente. Isso significa apenas no navegador master (ou em um computador que foi o navegador master no passado). O navegador master é o computador que atualmente tem direitos para determinar quais computadores podem ser servidores ou estações de trabalho na rede.
Se não houver servidores que correspondam aos tipos especificados no parâmetro servertype , a função NetServerEnum retornará o parâmetro bufptr como valores NULL e DWORD apontados pelos parâmetros entriesread e totalentries serão definidos como zero.
A função NetServerEnum depende do serviço de navegador que está sendo instalado e em execução. Se nenhum servidor de navegador for encontrado, o NetServerEnum falhará com ERROR_NO_BROWSER_SERVERS_FOUND.
Se você estiver programando para o Active Directory, poderá chamar determinados métodos ADSI (Active Directory Service Interface) para obter a mesma função que você pode obter chamando as funções do servidor de gerenciamento de rede. Para obter mais informações, consulte IADsComputer.
Exemplos
O exemplo de código a seguir demonstra como listar todos os servidores visíveis em um domínio com uma chamada para a função NetServerEnum . O exemplo chama NetServerEnum, especificando o nível de informações 101 ( SERVER_INFO_101). Se algum servidor for encontrado, o código de exemplo executará um loop nas entradas e imprimirá os dados recuperados. Se o servidor for um controlador de domínio, ele identificará o servidor como um controlador de domínio primário (PDC) ou um BDC (controlador de domínio de backup). O exemplo também imprime o número total de entradas disponíveis e uma dica sobre o número de entradas realmente enumeradas, avisando o usuário se todas as entradas não foram enumeradas. Por fim, o exemplo libera a memória alocada para o buffer de informações.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")
#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>
int wmain(int argc, wchar_t * argv[])
{
LPSERVER_INFO_101 pBuf = NULL;
LPSERVER_INFO_101 pTmpBuf;
DWORD dwLevel = 101;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwTotalCount = 0;
DWORD dwServerType = SV_TYPE_SERVER; // all servers
DWORD dwResumeHandle = 0;
NET_API_STATUS nStatus;
LPWSTR pszServerName = NULL;
LPWSTR pszDomainName = NULL;
DWORD i;
if (argc > 2)
{
fwprintf(stderr, L"Usage: %s [DomainName]\n", argv[0]);
exit(1);
}
// The request is not for the primary domain.
//
if (argc == 2)
pszDomainName = argv[1];
//
// Call the NetServerEnum function to retrieve information
// for all servers, specifying information level 101.
//
nStatus = NetServerEnum(pszServerName,
dwLevel,
(LPBYTE *) & pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
dwServerType,
pszDomainName,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA)) {
if ((pTmpBuf = pBuf) != NULL) {
//
// Loop through the entries and
// print the data for all server types.
//
for (i = 0; i < dwEntriesRead; i++) {
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL) {
fprintf(stderr, "An access violation has occurred\n");
break;
}
printf("\tPlatform: %d\n", pTmpBuf->sv101_platform_id);
wprintf(L"\tName: %s\n", pTmpBuf->sv101_name);
printf("\tVersion: %d.%d\n",
pTmpBuf->sv101_version_major,
pTmpBuf->sv101_version_minor);
printf("\tType: %d", pTmpBuf->sv101_type);
//
// Check to see if the server is a domain controller;
// if so, identify it as a PDC or a BDC.
//
if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_CTRL)
wprintf(L" (PDC)");
else if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_BAKCTRL)
wprintf(L" (BDC)");
printf("\n");
//
// Also print the comment associated with the server.
//
wprintf(L"\tComment: %s\n\n", pTmpBuf->sv101_comment);
pTmpBuf++;
dwTotalCount++;
}
// Display a warning if all available entries were
// not enumerated, print the number actually
// enumerated, and the total number available.
if (nStatus == ERROR_MORE_DATA) {
fprintf(stderr, "\nMore entries available!!!\n");
fprintf(stderr, "Total entries: %d", dwTotalEntries);
}
printf("\nEntries enumerated: %d\n", dwTotalCount);
} else {
printf("No servers were found\n");
printf("The buffer (bufptr) returned was NULL\n");
printf(" entriesread: %d\n", dwEntriesRead);
printf(" totalentries: %d\n", dwEntriesRead);
}
} else
fprintf(stderr, "NetServerEnum failed with error: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
return 0;
}
Requisitos
| Requisito | Valor |
|---|---|
| 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 | lmserver.h (inclua Lm.h) |
| Biblioteca | Netapi32.lib |
| DLL | Netapi32.dll |
Confira também
Funções de gerenciamento de rede