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.

[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 .

[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:

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

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