Compartir a través de


Función NetServerEnum (lmserver.h)

La función NetServerEnum enumera todos los servidores del tipo especificado que están visibles en un dominio.

Sintaxis

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; debe ser NULL.

[in] level

Nivel de información de los datos solicitados. Este parámetro puede ser uno de los valores siguientes.

Valor Significado
100
Devuelve los nombres de servidor y la información de la plataforma. El parámetro bufptr apunta a una matriz de estructuras de SERVER_INFO_100 .
101
Devuelve nombres de servidor, tipos y datos asociados. El parámetro bufptr apunta a una matriz de estructuras de SERVER_INFO_101 .

[out] bufptr

Puntero al búfer que recibe los datos. El formato de estos datos depende del valor del parámetro level . El sistema asigna este búfer y debe liberarse mediante la función NetApiBufferFree . Tenga en cuenta que debe liberar el búfer incluso si se produce un error en la función con ERROR_MORE_DATA.

[in] prefmaxlen

Longitud máxima preferida de los datos devueltos, en bytes. Si especifica MAX_PREFERRED_LENGTH, la función asigna la cantidad de memoria necesaria para los datos. Si especifica otro valor en este parámetro, puede restringir el número de bytes que devuelve la función. Si el tamaño del búfer no es suficiente para contener todas las entradas, la función devuelve ERROR_MORE_DATA. Para obtener más información, consulte Búferes de funciones de administración de red y longitudes de búfer de funciones de administración de red.

[out] entriesread

Puntero a un valor que recibe el recuento de elementos enumerados realmente.

[out] totalentries

Puntero a un valor que recibe el número total de servidores y estaciones de trabajo visibles en la red. Tenga en cuenta que las aplicaciones solo deben tener en cuenta este valor como sugerencia.

[in] servertype

Valor que filtra las entradas del servidor que se van a devolver de la enumeración. Este parámetro puede ser una combinación de los siguientes valores definidos en el archivo de encabezado Lmserver.h .

Valor Significado
SV_TYPE_WORKSTATION
0x00000001
Todas las estaciones de trabajo.
SV_TYPE_SERVER
0x00000002
Todos los equipos que ejecutan el servicio Server.
SV_TYPE_SQLSERVER
0x00000004
Cualquier servidor que ejecute una instancia de Microsoft SQL Server.
SV_TYPE_DOMAIN_CTRL
0x00000008
Servidor que es el controlador de dominio principal.
SV_TYPE_DOMAIN_BAKCTRL
0x00000010
Cualquier servidor que sea un controlador de dominio de copia de seguridad.
SV_TYPE_TIME_SOURCE
0x00000020
Cualquier servidor que ejecute el servicio Timesource.
SV_TYPE_AFP
0x00000040
Cualquier servidor que ejecute el servicio de archivos del Protocolo de presentación de Apple (FTP).
SV_TYPE_NOVELL
0x00000080
Cualquier servidor que sea un servidor Novell.
SV_TYPE_DOMAIN_MEMBER
0x00000100
Cualquier equipo que sea miembro del dominio LAN Manager 2.x.
SV_TYPE_PRINTQ_SERVER
0x00000200
Cualquier equipo que comparta una cola de impresión.
SV_TYPE_DIALIN_SERVER
0x00000400
Cualquier servidor que ejecute un servicio de acceso telefónico local.
SV_TYPE_XENIX_SERVER
0x00000800
Cualquier servidor que sea un servidor Xenix.
SV_TYPE_SERVER_UNIX
0x00000800
Cualquier servidor que sea un servidor UNIX. Esto es lo mismo que el SV_TYPE_XENIX_SERVER.
SV_TYPE_NT
0x00001000
Estación de trabajo o servidor.
SV_TYPE_WFW
0x00002000
Cualquier equipo que ejecute Windows for Workgroups.
SV_TYPE_SERVER_MFPN
0x00004000
Cualquier servidor que ejecute el servicio Microsoft File and Print for NetWare.
SV_TYPE_SERVER_NT
0x00008000
Cualquier servidor que no sea un controlador de dominio.
SV_TYPE_POTENTIAL_BROWSER
0x00010000
Cualquier equipo que pueda ejecutar el servicio del explorador.
SV_TYPE_BACKUP_BROWSER
0x00020000
Un equipo que ejecuta un servicio de explorador como copia de seguridad.
SV_TYPE_MASTER_BROWSER
0x00040000
Un equipo que ejecuta el servicio del explorador maestro.
SV_TYPE_DOMAIN_MASTER
0x00080000
Un equipo que ejecuta el explorador maestro de dominio.
SV_TYPE_SERVER_OSF
0x00100000
Un equipo que ejecuta OSF/1.
SV_TYPE_SERVER_VMS
0x00200000
Un equipo que ejecuta Open Virtual Memory System (VMS).
SV_TYPE_WINDOWS
0x00400000
Un equipo que ejecuta Windows.
SV_TYPE_DFS
0x00800000
Un equipo que es la raíz del árbol del Sistema de archivos distribuido (DFS).
SV_TYPE_CLUSTER_NT
0x01000000
Clústeres de servidores disponibles en el dominio.
SV_TYPE_TERMINALSERVER
0x02000000
Un servidor que ejecuta el servicio Terminal Server.
SV_TYPE_CLUSTER_VS_NT
0x04000000
Servidores virtuales de clúster disponibles en el dominio.

Windows 2000: Este valor no se admite.

SV_TYPE_DCE
0x10000000
Un equipo que ejecuta IBM Directory and Security Services (DSS) o equivalente.
SV_TYPE_ALTERNATE_XPORT
0x20000000
Un equipo que sobre un transporte alternativo.
SV_TYPE_LOCAL_LIST_ONLY
0x40000000
Cualquier equipo mantenido en una lista por el explorador. Consulte la sección Comentarios siguiente.
SV_TYPE_DOMAIN_ENUM
0x80000000
Dominio principal.
SV_TYPE_ALL
0xffffffff
Todos los servidores. Se trata de una comodidad que devolverá todos los servidores posibles.

[in, optional] domain

Puntero a una cadena constante que especifica el nombre del dominio para el que se va a devolver una lista de servidores. El nombre de dominio debe ser un nombre de dominio NetBIOS (por ejemplo, microsoft). La función NetServerEnum no admite nombres de estilo DNS (por ejemplo, microsoft.com).

Si este parámetro es NULL, el dominio principal está implícito.

[in, out, optional] resume_handle

Reservados; debe establecerse en cero.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto se NERR_Success.

Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de error:

Código o valor devuelto Descripción
ERROR_ACCESS_DENIED
5
Se denegó el acceso.
ERROR_INVALID_PARAMETER
87
El parámetro no es correcto.
ERROR_MORE_DATA
234
Hay más entradas disponibles. Especifique un búfer suficientemente grande para recibir todas las entradas.
ERROR_NO_BROWSER_SERVERS_FOUND
6118
No se encontró ningún servidor de explorador.
ERROR_NOT_SUPPORTED
50
No se admite la solicitud.
NERR_RemoteErr
2127
Error remoto sin datos devueltos por el servidor.
NERR_ServerNotStarted
2114
El servicio de servidor no se inicia.
NERR_ServiceNotInstalled
2184
El servicio no se ha iniciado.
NERR_WkstaNotStarted
2138
No se ha iniciado el servicio Workstation. El servicio de estación de trabajo local se usa para comunicarse con un servidor remoto de nivel inferior.

Comentarios

La función NetServerEnum se usa para enumerar todos los servidores del tipo especificado que están visibles en un dominio. Por ejemplo, una aplicación puede llamar a NetServerEnum para enumerar solo todos los controladores de dominio o todos los servidores que ejecutan instancias de SQL Server.

Una aplicación combina las máscaras de bits para varios tipos de servidor en el parámetro servertype para enumerar varios tipos. Por ejemplo, un valor de SV_TYPE_WORKSTATION | SVTYPE_SERVER (0x00000003) combina las máscaras de bits para SV_TYPE_WORKSTATION (0x00000001) y SV_TYPE_SERVER (0x00000002).

Si necesita más información para un servidor específico, llame a la función WNetEnumResource .

No se requiere ninguna pertenencia especial a grupos para ejecutar correctamente la función NetServerEnum .

Si especifica el valor SV_TYPE_LOCAL_LIST_ONLY, la función NetServerEnum devuelve la lista de servidores que el explorador mantiene internamente. Esto solo tiene significado en el explorador maestro (o en un equipo que ha sido el explorador maestro en el pasado). El explorador maestro es el equipo que actualmente tiene derechos para determinar qué equipos pueden ser servidores o estaciones de trabajo en la red.

Si no se encuentra ningún servidor que coincida con los tipos especificados en el parámetro servertype , la función NetServerEnum devuelve el parámetro bufptr como valores NULL y DWORD a los que apuntan los parámetros de entradasread y totalentries se establecen en cero.

La función NetServerEnum depende del servicio del explorador que se esté instalando y ejecutando. Si no se encuentra ningún servidor de explorador, NetServerEnum produce un error ERROR_NO_BROWSER_SERVERS_FOUND.

Si está programando para Active Directory, puede llamar a determinados métodos de interfaz de servicio de Active Directory (ADSI) para lograr la misma función que puede lograr llamando a las funciones del servidor de administración de red. Para obtener más información, consulte IADsComputer.

Ejemplos

En el ejemplo de código siguiente se muestra cómo enumerar todos los servidores visibles en un dominio con una llamada a la función NetServerEnum . El ejemplo llama a NetServerEnum, especificando el nivel de información 101 ( SERVER_INFO_101). Si se encuentran servidores, el código de ejemplo recorre en bucle las entradas e imprime los datos recuperados. Si el servidor es un controlador de dominio, identifica el servidor como un controlador de dominio principal (PDC) o un controlador de dominio de copia de seguridad (BDC). En el ejemplo también se imprime el número total de entradas disponibles y una sugerencia sobre el número de entradas enumeradas realmente, lo que advierte al usuario si no se enumeraron todas las entradas. Por último, el ejemplo libera la memoria asignada para el búfer de información.

#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 Value
Cliente mínimo compatible Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado lmserver.h (include Lm.h)
Library Netapi32.lib
Archivo DLL Netapi32.dll

Consulte también

NetQueryDisplayInformation

NetServerDiskEnum

Funciones de administración de redes

Introducción a la administración de redes

SERVER_INFO_100

SERVER_INFO_101

Funciones de servidor