Platform SDK: Network Management

NetServerEnum

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.

Security Requirements

No special group membership is required to successfully execute the NetServerEnum 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 DWORD value that receives the count of elements actually enumerated.

totalentries

[out] Pointer to a DWORD value that receives the total number of visible servers and workstations on the network.

servertype

[in] Specifies a DWORD 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 servers
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/Windows 2000 workstation or server
SV_TYPE_WFW	Server running Windows for Workgroups
SV_TYPE_SERVER_NT	Windows NT/Windows 2000 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

domain

[in] Pointer to a constant Unicode string specifying 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:

Value	Meaning
ERROR_ACCESS_DENIED	The user does not have access to the requested information.
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

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 machine that currently has rights to determine which machines can be servers or workstations on the network.

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 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 = -1;
   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;
}

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.

Requirements