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 |
|---|---|
|
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 . |
|
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 .
[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 |
|---|---|
|
Se denegó el acceso. |
|
El parámetro no es correcto. |
|
Hay más entradas disponibles. Especifique un búfer suficientemente grande para recibir todas las entradas. |
|
No se encontró ningún servidor de explorador. |
|
No se admite la solicitud. |
|
Error remoto sin datos devueltos por el servidor. |
|
El servicio de servidor no se inicia. |
|
El servicio no se ha iniciado. |
|
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
Funciones de administración de redes