The NetServerEnum function lists all servers of the specified type that are visible in a domain. For example, an application can call NetServerEnum to list all domain controllers only or all SQL servers only.

You can combine bit masks to list several types. For example, a value of 0x00000003 combines the bit masks for SV_TYPE_WORKSTATION (0x00000001) and SV_TYPE_SERVER (0x00000002).

If you require more information for a specific server, call the WNetEnumResource function.

Syntax

NET_API_STATUS NetServerEnum(
  __in_opt     LPCWSTR servername,
  __in         DWORD level,
  __out        LPBYTE *bufptr,
  __in         DWORD prefmaxlen,
  __out        LPDWORD entriesread,
  __out        LPDWORD totalentries,
  __in         DWORD servertype,
  __in_opt     LPCWSTR domain,
  __inout_opt  LPDWORD resume_handle
);

Parameters

servername [in, optional]

Reserved; must be NULL.

level [in]

The information level of the data requested. This parameter can be one of the following values.

Value	Meaning
100	Return server names and platform information. The bufptr parameter points to an array of SERVER_INFO_100 structures.
101	Return server names, types, and associated software. The bufptr parameter points to an array of SERVER_INFO_101 structures.

 

bufptr [out]

A pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.

prefmaxlen [in]

The preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.

entriesread [out]

A pointer to a value that receives the count of elements actually enumerated.

totalentries [out]

A pointer to a value that receives the total number of visible servers and workstations on the network. Note that applications should consider this value only as a hint.

servertype [in]

A value that filters the server entries to return from the enumeration. This parameter can be one or more of the following values.

Value	Meaning
SV_TYPE_WORKSTATION	All workstations.
SV_TYPE_SERVER	All computers that run the Server service.
SV_TYPE_SQLSERVER	Any server that runs Microsoft SQL Server.
SV_TYPE_DOMAIN_CTRL	A server that is primary domain controller.
SV_TYPE_DOMAIN_BAKCTRL	Any server that is a backup domain controller.
SV_TYPE_TIME_SOURCE	Any server that runs the Timesource service.
SV_TYPE_AFP	Any server that runs the Apple Filing Protocol (AFP) file service.
SV_TYPE_NOVELL	Any server that is a Novell server.
SV_TYPE_DOMAIN_MEMBER	Any computer that is LAN Manager 2.x domain member.
SV_TYPE_LOCAL_LIST_ONLY	Any computer maintained in a list by the browser. See the following Remarks section.
SV_TYPE_PRINTQ_SERVER	Any computer that shares a print queue.
SV_TYPE_DIALIN_SERVER	Any server that runs a dial-in service.
SV_TYPE_XENIX_SERVER	Any server that is a Xenix server.
SV_TYPE_SERVER_MFPN	Any server that runs the Microsoft File and Print for NetWare service.
SV_TYPE_NT	A workstation or server.
SV_TYPE_WFW	Any computer that runs Windows for Workgroups.
SV_TYPE_SERVER_NT	Any server that is not a domain controller.
SV_TYPE_POTENTIAL_BROWSER	Any computer that can run the browser service.
SV_TYPE_BACKUP_BROWSER	A computer that runs a browser service as backup.
SV_TYPE_MASTER_BROWSER	A computer that runs the master browser service.
SV_TYPE_DOMAIN_MASTER	A computer that runs the domain master browser.
SV_TYPE_DOMAIN_ENUM	The primary domain.
SV_TYPE_WINDOWS	A computer that runs Windows.
SV_TYPE_ALL	All servers.
SV_TYPE_TERMINALSERVER	A server running the Terminal Server service.
SV_TYPE_CLUSTER_NT	Server clusters available in the domain.
SV_TYPE_CLUSTER_VS_NT	Cluster virtual servers available in the domain. Windows 2000:  This value is not supported.

 

domain [in, optional]

A pointer to a constant string that specifies the name of the domain for which a list of servers is to be returned. The domain name must be a NetBIOS domain name (for example, microsoft). The NetServerEnum function does not support DNS-style names (for example, microsoft.com).

If this parameter is NULL, the primary domain is implied.

resume_handle [in, out, optional]

Reserved; must be set to zero.

Return Value

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes:

Remarks

No special group membership is required to successfully execute the NetServerEnum function.

If you specify the value SV_TYPE_LOCAL_LIST_ONLY, the NetServerEnum function returns the list of servers that the browser maintains internally. This has meaning only on the master browser (or on a computer that has been the master browser in the past). The master browser is the computer that currently has rights to determine which computers can be servers or workstations on the network.

If there are no servers found that match the types specified in the servertype parameter, the NetServerEnum function returns the bufptr parameter as NULL and DWORD values pointed to by the entriesread and totalentries parameters are set to zero.

The NetServerEnum function depends on the browser service being installed and running. If no browser servers are found, then NetServerEnum fails with ERROR_NO_BROWSER_SERVERS_FOUND.

If you are programming for Active Directory, you may be able to call certain Active Directory Service Interface (ADSI) methods to achieve the same function you can achieve by calling the network management server functions. For more information, see IADsComputer.

Examples

The following code sample demonstrates how to list all servers that are visible in a domain with a call to the NetServerEnum function. The sample calls NetServerEnum, specifying information level 101 ( SERVER_INFO_101). If any servers are found, the sample code loops through the entries and prints the retrieved data. If the server is a domain controller, it identifies the server as either a primary domain controller (PDC) or a backup domain controller (BDC). The sample also prints the total number of entries available and a hint about the number of entries actually enumerated, warning the user if all entries were not enumerated. Finally, the sample frees the memory allocated for the information buffer.

#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;
}

Requirements

See Also

Network Management Overview

Network Management Functions

Server Functions

NetServerDiskEnum

NetQueryDisplayInformation

SERVER_INFO_100

SERVER_INFO_101

Send comments about this topic to Microsoft

Build date: 9/17/2009