NetServerEnum 函数 (lmserver.h)
NetServerEnum 函数列出在域中可见的指定类型的所有服务器。
语法
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
);
参数
[in, optional] servername
保留;必须为 NULL。
[in] level
请求的数据的信息级别。 此参数的取值可为下列值之一：
| 值 | 含义 |
|---|---|
|
返回服务器名称和平台信息。 bufptr 参数指向SERVER_INFO_100结构的数组。 |
|
返回服务器名称、类型和关联的数据。 bufptr 参数指向SERVER_INFO_101结构的数组。 |
[out] bufptr
指向接收数据的缓冲区的指针。 此数据的格式取决于 级别 参数的值。 此缓冲区由系统分配，必须使用 NetApiBufferFree 函数释放。 请注意，即使函数失败并出现ERROR_MORE_DATA，也必须释放缓冲区。
[in] prefmaxlen
返回数据的首选最大长度（以字节为单位）。 如果指定MAX_PREFERRED_LENGTH，函数将分配数据所需的内存量。 如果在此参数中指定另一个值，它可以限制函数返回的字节数。 如果缓冲区大小不足以容纳所有条目，则函数将返回ERROR_MORE_DATA。 有关详细信息，请参阅 网络管理功能缓冲区 和 网络管理功能缓冲区长度。
[out] entriesread
指向接收实际枚举的元素计数的值的指针。
[out] totalentries
指向一个值的指针，该值接收网络上可见服务器和工作站的总数。 请注意，应用程序应仅将此值视为提示。
[in] servertype
一个 值，用于筛选要从 枚举返回的服务器条目。 此参数可以是 Lmserver.h 头文件中定义的以下值的组合。
[in, optional] domain
指向常量字符串的指针，该字符串指定要为其返回服务器列表的域的名称。 域名必须是 NetBIOS 域名 (例如 microsoft) 。 NetServerEnum 函数不支持 DNS 样式的名称 (例如 microsoft.com) 。
如果此参数为 NULL，则隐含主域。
[in, out, optional] resume_handle
保留;必须设置为零。
返回值
如果函数成功，则返回值NERR_Success。
如果函数失败，则返回值可能是以下错误代码之一：
| 返回代码/值 | 说明 |
|---|---|
|
访问被拒绝。 |
|
参数不正确。 |
|
有更多条目可用。 指定一个足够大的缓冲区来接收所有条目。 |
|
找不到浏览器服务器。 |
|
不支持该请求。 |
|
发生远程错误，服务器未返回任何数据。 |
|
服务器服务未启动。 |
|
该服务尚未启动。 |
|
工作站服务尚未启动。 本地工作站服务用于与下层远程服务器通信。 |
注解
NetServerEnum 函数用于列出在域中可见的指定类型的所有服务器。 例如，应用程序可以调用 NetServerEnum 来仅列出所有域控制器或仅运行 SQL Server 实例的所有服务器。
应用程序在 servertype 参数中组合各种服务器类型的位掩码以列出多个类型。 例如，值为 SV_TYPE_WORKSTATION |SVTYPE_SERVER (0x00000003) 合并了SV_TYPE_WORKSTATION (0x00000001) 和SV_TYPE_SERVER (0x00000002) 的位掩码。
如果需要特定服务器的详细信息，请调用 WNetEnumResource 函数。
无需特殊的组成员身份即可成功执行 NetServerEnum 函数。
如果指定值 SV_TYPE_LOCAL_LIST_ONLY，NetServerEnum 函数将返回浏览器在内部维护的服务器列表。 这仅在主浏览器 (或在过去) 中一直是主浏览器的计算机上有意义。 主浏览器是当前有权确定哪些计算机可以是网络上的服务器或工作站的计算机。
如果没有找到与 servertype 参数中指定的类型匹配的服务器，NetServerEnum 函数将返回 bufptr 参数，因为 entriesread 和 totalentries 参数指向的 NULL 和 DWORD 值设置为零。
NetServerEnum 函数取决于正在安装和运行的浏览器服务。 如果未找到浏览器服务器，则 NetServerEnum 会失败并ERROR_NO_BROWSER_SERVERS_FOUND。
如果要对 Active Directory 进行编程，则可以调用某些 Active Directory 服务接口 (ADSI) 方法，以实现通过调用网络管理服务器函数可实现的相同功能。 有关详细信息，请参阅 IADsComputer。
示例
以下代码示例演示如何列出通过调用 NetServerEnum 函数在域中可见的所有服务器。 此示例调用 NetServerEnum，指定信息级别 101 ( SERVER_INFO_101) 。 如果找到任何服务器，示例代码将遍历条目并打印检索到的数据。 如果服务器是域控制器，则会将服务器标识为 PDC) (主域控制器或 BDC) (备份域控制器。 该示例还打印了可用条目总数和有关实际枚举的条目数的提示，如果未枚举所有条目，则向用户发出警告。 最后，该示例释放为信息缓冲区分配的内存。
#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;
}
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
| 最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | lmserver.h (包括 Lm.h) |
| Library | Netapi32.lib |
| DLL | Netapi32.dll |