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
接收數據的緩衝區指標。 此數據的格式取決於 level 參數的值。 此緩衝區是由系統所配置，必須使用 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。
如果函式失敗，傳回值可以是下列其中一個錯誤碼：
| 傳回碼/值 | Description |
|---|---|
|
拒絕存取。 |
|
參數錯誤。 |
|
有更多專案可供使用。 指定夠大的緩衝區來接收所有專案。 |
|
找不到瀏覽器伺服器。 |
|
不支援此要求。 |
|
發生遠端錯誤，且伺服器未傳回任何數據。 |
|
伺服器服務未啟動。 |
|
尚未啟動服務。 |
|
工作站服務尚未啟動。 本機工作站服務是用來與舊版遠端伺服器通訊。 |
備註
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 參數傳回為專案read 和 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) |
| 程式庫 | Netapi32.lib |
| Dll | Netapi32.dll |