Compartilhar via


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
100
Retornar nomes de servidor e informações de plataforma. O parâmetro bufptr aponta para uma matriz de estruturas SERVER_INFO_100 .
101
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 .

Valor Significado
SV_TYPE_WORKSTATION
0x00000001
Todas as estações de trabalho.
SV_TYPE_SERVER
0x00000002
Todos os computadores que executam o serviço Servidor.
SV_TYPE_SQLSERVER
0x00000004
Qualquer servidor que executa uma instância do Microsoft SQL Server.
SV_TYPE_DOMAIN_CTRL
0x00000008
Um servidor que é o controlador de domínio primário.
SV_TYPE_DOMAIN_BAKCTRL
0x00000010
Qualquer servidor que seja um controlador de domínio de backup.
SV_TYPE_TIME_SOURCE
0x00000020
Qualquer servidor que executa o serviço Timesource.
SV_TYPE_AFP
0x00000040
Qualquer servidor que execute o serviço de arquivo AFP (Apple Filing Protocol).
SV_TYPE_NOVELL
0x00000080
Qualquer servidor que seja um servidor Novell.
SV_TYPE_DOMAIN_MEMBER
0x00000100
Qualquer computador que seja membro de domínio do LAN Manager 2.x.
SV_TYPE_PRINTQ_SERVER
0x00000200
Qualquer computador que compartilhe uma fila de impressão.
SV_TYPE_DIALIN_SERVER
0x00000400
Qualquer servidor que executa um serviço de discagem.
SV_TYPE_XENIX_SERVER
0x00000800
Qualquer servidor que seja um servidor Xenix.
SV_TYPE_SERVER_UNIX
0x00000800
Qualquer servidor que seja um servidor UNIX. Isso é o mesmo que o SV_TYPE_XENIX_SERVER.
SV_TYPE_NT
0x00001000
Uma estação de trabalho ou um servidor.
SV_TYPE_WFW
0x00002000
Qualquer computador que execute o Windows para Grupos de Trabalho.
SV_TYPE_SERVER_MFPN
0x00004000
Qualquer servidor que execute o serviço Arquivo e Impressão da Microsoft para NetWare.
SV_TYPE_SERVER_NT
0x00008000
Qualquer servidor que não seja um controlador de domínio.
SV_TYPE_POTENTIAL_BROWSER
0x00010000
Qualquer computador que possa executar o serviço do navegador.
SV_TYPE_BACKUP_BROWSER
0x00020000
Um computador que executa um serviço de navegador como backup.
SV_TYPE_MASTER_BROWSER
0x00040000
Um computador que executa o serviço de navegador master.
SV_TYPE_DOMAIN_MASTER
0x00080000
Um computador que executa o domínio master navegador.
SV_TYPE_SERVER_OSF
0x00100000
Um computador que executa o OSF/1.
SV_TYPE_SERVER_VMS
0x00200000
Um computador que executa o VMS (Open Virtual Memory System).
SV_TYPE_WINDOWS
0x00400000
Um computador que executa o Windows.
SV_TYPE_DFS
0x00800000
Um computador que é a raiz da árvore DFS (Sistema de Arquivos Distribuído).
SV_TYPE_CLUSTER_NT
0x01000000
Clusters de servidores disponíveis no domínio.
SV_TYPE_TERMINALSERVER
0x02000000
Um servidor que executa o serviço Servidor de Terminal.
SV_TYPE_CLUSTER_VS_NT
0x04000000
Servidores virtuais de cluster disponíveis no domínio.

Windows 2000: Não há suporte para esse valor.

SV_TYPE_DCE
0x10000000
Um computador que executa o DSS (Ibm Directory and Security Services) ou equivalente.
SV_TYPE_ALTERNATE_XPORT
0x20000000
Um computador que está em um transporte alternativo.
SV_TYPE_LOCAL_LIST_ONLY
0x40000000
Qualquer computador mantido em uma lista pelo navegador. Consulte a seção Comentários a seguir.
SV_TYPE_DOMAIN_ENUM
0x80000000
O domínio primário.
SV_TYPE_ALL
0xFFFFFFFF
Todos os servidores. Essa é uma conveniência que retornará todos os servidores possíveis.

[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
ERROR_ACCESS_DENIED
5
O acesso foi negado.
ERROR_INVALID_PARAMETER
87
O parâmetro está incorreto.
ERROR_MORE_DATA
234
Mais entradas estão disponíveis. Especifique um buffer grande o suficiente para receber todas as entradas.
ERROR_NO_BROWSER_SERVERS_FOUND
6118
Nenhum servidor de navegador encontrado.
ERROR_NOT_SUPPORTED
50
A solicitação não terá suporte.
NERR_RemoteErr
2127
Ocorreu um erro remoto sem dados retornados pelo servidor.
NERR_ServerNotStarted
2114
O serviço de servidor não foi iniciado.
NERR_ServiceNotInstalled
2184
O serviço não foi iniciado.
NERR_WkstaNotStarted
2138
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

NetQueryDisplayInformation

NetServerDiskEnum

Funções de gerenciamento de rede

Visão geral do gerenciamento de rede

SERVER_INFO_100

SERVER_INFO_101

Funções de servidor