Export (0) Print
Expand All
Expand Minimize

NetServerEnum

Windows Server 2003

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.


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

Parameters

servername
[in]

Reserved; must be NULL.

level
[in]

Specifies the information level of the data. 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]

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]

Specifies 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]

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

totalentries
[out]

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]

Specifies 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 have the server service running

SV_TYPE_SQLSERVER

Any server running with Microsoft SQL Server

SV_TYPE_DOMAIN_CTRL

Primary domain controller

SV_TYPE_DOMAIN_BAKCTRL

Backup domain controller

SV_TYPE_TIME_SOURCE

Server running the Timesource service

SV_TYPE_AFP

Apple File Protocol servers

SV_TYPE_NOVELL

Novell servers

SV_TYPE_DOMAIN_MEMBER

LAN Manager 2.x domain member

SV_TYPE_LOCAL_LIST_ONLY

Servers maintained by the browser. See the following Remarks section.

SV_TYPE_PRINTQ_SERVER

Server sharing print queue

SV_TYPE_DIALIN_SERVER

Server running dial-in service

SV_TYPE_XENIX_SERVER

Xenix server

SV_TYPE_SERVER_MFPN

Microsoft File and Print for NetWare

SV_TYPE_NT

Windows NT workstation or server

SV_TYPE_WFW

Server running Windows for Workgroups

SV_TYPE_SERVER_NT

Server that is not a domain controller

SV_TYPE_POTENTIAL_BROWSER

Server that can run the browser service

SV_TYPE_BACKUP_BROWSER

Server running a browser service as backup

SV_TYPE_MASTER_BROWSER

Server running the master browser service

SV_TYPE_DOMAIN_MASTER

Server running the domain master browser

SV_TYPE_DOMAIN_ENUM

Primary domain

SV_TYPE_WINDOWS

Windows 95 or later

SV_TYPE_ALL

All servers

SV_TYPE_TERMINALSERVER

Terminal Server

SV_TYPE_CLUSTER_NT

Server clusters available in the domain

SV_TYPE_CLUSTER_VS_NT

Cluster virtual servers available in the domain.

Windows 2000/NT:  This value is not supported.
domain
[in]

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). NetServerEnum does not support DNS-style names (for example, microsoft.com). If this parameter is NULL, the primary domain is implied.

resume_handle

Reserved; must be set to zero.

Return Values

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:

Return code Description
ERROR_NO_BROWSER_SERVERS_FOUND

No browser servers found.

ERROR_MORE_DATA

More entries are available. Specify a large enough buffer to receive all entries.

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 you are programming for Active Directory, you may be able to call certain Active Directory Service Interface (ADSI) methods to achieve the same functionality you can achieve by calling the network management server functions. For more information, see IADsComputer.

Example Code

The following code sample demonstrates how to list all servers that are visible in the primary domain with a call to the NetServerEnum function. The sample calls NetServerEnum, specifying information level 101 ( SERVER_INFO_101). 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

#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;
   LPTSTR pszServerName = NULL;
   DWORD i;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = 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,
                           NULL,
                           &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
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

Requirements

ClientRequires Windows Vista™, Windows XP, Windows 2000 Professional, or Windows NT Workstation.
ServerRequires Windows Server 2008 operating system, Windows Server 2003, Windows 2000 Server, or Windows NT Server.
Header

Declared in Lmserver.h; include Lm.h.

Library

Link to Netapi32.lib.

DLLRequires Netapi32.dll.

See Also

Network Management Overview, Network Management Functions, Server Functions, NetServerDiskEnum, NetQueryDisplayInformation, SERVER_INFO_100, SERVER_INFO_101

Show:
© 2014 Microsoft