NetServerEnum function (lmserver.h)
The NetServerEnum function lists all servers of the specified type that are visible in a domain.
Syntax
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
);
Parameters
[in, optional] servername
Reserved; must be NULL.
[in] level
The information level of the data requested. This parameter can be one of the following values.
| Value | Meaning |
|---|---|
|
Return server names and platform information. The bufptr parameter points to an array of SERVER_INFO_100 structures. |
|
Return server names, types, and associated data. The bufptr parameter points to an array of SERVER_INFO_101 structures. |
[out] bufptr
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.
[in] prefmaxlen
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.
[out] entriesread
A pointer to a value that receives the count of elements actually enumerated.
[out] totalentries
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.
[in] servertype
A value that filters the server entries to return from the enumeration. This parameter can be a combination of the following values defined in the Lmserver.h header file.
[in, optional] domain
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.
[in, out, optional] resume_handle
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:
| Return code/value | Description |
|---|---|
|
Access was denied. |
|
The parameter is incorrect. |
|
More entries are available. Specify a large enough buffer to receive all entries. |
|
No browser servers found. |
|
The request is not supported. |
|
A remote error occurred with no data returned by the server. |
|
The server service is not started. |
|
The service has not been started. |
|
The Workstation service has not been started. The local workstation service is used to communicate with a downlevel remote server. |
Remarks
The NetServerEnum function is used to list 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 servers that run instances of SQL server only.
An application combine the bit masks for various server types in the servertype parameter to list several types. For example, a value of SV_TYPE_WORKSTATION | SVTYPE_SERVER (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.
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
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | lmserver.h (include Lm.h) |
| Library | Netapi32.lib |
| DLL | Netapi32.dll |