共用方式為


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

要求之數據的資訊層級。 此參數可以是下列其中一個值。

意義
100
傳回伺服器名稱和平台資訊。 bufptr 參數指向SERVER_INFO_100 結構的陣列。
101
傳回伺服器名稱、類型和相關聯的數據。 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 頭文件中定義的下列值組合。

意義
SV_TYPE_WORKSTATION
0x00000001
所有工作站。
SV_TYPE_SERVER
0x00000002
執行伺服器服務的所有計算機。
SV_TYPE_SQLSERVER
0x00000004
任何執行 Microsoft SQL Server 實例的伺服器。
SV_TYPE_DOMAIN_CTRL
0x00000008
主域控制站的伺服器。
SV_TYPE_DOMAIN_BAKCTRL
0x00000010
任何屬於備份域控制器的伺服器。
SV_TYPE_TIME_SOURCE
0x00000020
任何執行 Timesource 服務的伺服器。
SV_TYPE_AFP
0x00000040
執行 Apple File Protocol (AFP) 檔案服務的任何伺服器。
SV_TYPE_NOVELL
0x00000080
屬於 Novell 伺服器的任何伺服器。
SV_TYPE_DOMAIN_MEMBER
0x00000100
任何屬於 LAN Manager 2.x 網域成員的電腦。
SV_TYPE_PRINTQ_SERVER
0x00000200
任何共用列印佇列的電腦。
SV_TYPE_DIALIN_SERVER
0x00000400
執行撥入服務的任何伺服器。
SV_TYPE_XENIX_SERVER
0x00000800
任何屬於 Xenix 伺服器的伺服器。
SV_TYPE_SERVER_UNIX
0x00000800
屬於 UNIX 伺服器的任何伺服器。 這與 SV_TYPE_XENIX_SERVER相同。
SV_TYPE_NT
0x00001000
工作站或伺服器。
SV_TYPE_WFW
0x00002000
任何執行 Windows for Workgroups 的電腦。
SV_TYPE_SERVER_MFPN
0x00004000
執行 Microsoft File 和 Print for NetWare 服務的任何伺服器。
SV_TYPE_SERVER_NT
0x00008000
任何不是域控制器的伺服器。
SV_TYPE_POTENTIAL_BROWSER
0x00010000
任何可執行瀏覽器服務的電腦。
SV_TYPE_BACKUP_BROWSER
0x00020000
執行瀏覽器服務做為備份的計算機。
SV_TYPE_MASTER_BROWSER
0x00040000
執行主瀏覽器服務的電腦。
SV_TYPE_DOMAIN_MASTER
0x00080000
執行網域主機瀏覽器的電腦。
SV_TYPE_SERVER_OSF
0x00100000
執行OSF/1的電腦。
SV_TYPE_SERVER_VMS
0x00200000
執行 Open Virtual Memory System (VMS) 的電腦。
SV_TYPE_WINDOWS
0x00400000
執行 Windows 的電腦。
SV_TYPE_DFS
0x00800000
屬於分散式文件系統根目錄的計算機, (DFS) 樹狀結構。
SV_TYPE_CLUSTER_NT
0x01000000
網域中可用的伺服器叢集。
SV_TYPE_TERMINALSERVER
0x02000000
執行終端機伺服器服務的伺服器。
SV_TYPE_CLUSTER_VS_NT
0x04000000
網域中可用的叢集虛擬伺服器。

Windows 2000: 不支援這個值。

SV_TYPE_DCE
0x10000000
執行IBM Directory 和安全性服務的電腦 (DSS) 或對等專案。
SV_TYPE_ALTERNATE_XPORT
0x20000000
透過替代傳輸的電腦。
SV_TYPE_LOCAL_LIST_ONLY
0x40000000
瀏覽器在清單中維護的任何計算機。 請參閱下列一節。
SV_TYPE_DOMAIN_ENUM
0x80000000
主域。
SV_TYPE_ALL
0xFFFFFFFF
所有伺服器。 這是會傳回所有可能伺服器的便利性。

[in, optional] domain

常數位符串的指標,指定要傳回伺服器清單的功能變數名稱。 功能變數名稱必須是 NetBIOS 功能變數名稱 (,例如 microsoft) 。 例如,NetServerEnum 函式不支援 dns 樣式名稱 (microsoft.com) 。

如果此參數為 NULL,則會隱含主域。

[in, out, optional] resume_handle

保留;必須設定為零。

傳回值

如果函式成功,傳回值會NERR_Success。

如果函式失敗,傳回值可以是下列其中一個錯誤碼:

傳回碼/值 Description
ERROR_ACCESS_DENIED
5
拒絕存取。
ERROR_INVALID_PARAMETER
87
參數錯誤。
ERROR_MORE_DATA
234
有更多專案可供使用。 指定夠大的緩衝區來接收所有專案。
ERROR_NO_BROWSER_SERVERS_FOUND
6118
找不到瀏覽器伺服器。
ERROR_NOT_SUPPORTED
50
不支援此要求。
NERR_RemoteErr
2127
發生遠端錯誤,且伺服器未傳回任何數據。
NERR_ServerNotStarted
2114
伺服器服務未啟動。
NERR_ServiceNotInstalled
2184
尚未啟動服務。
NERR_WkstaNotStarted
2138
工作站服務尚未啟動。 本機工作站服務是用來與舊版遠端伺服器通訊。

備註

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 參數傳回為專案readtotalentries 參數所指向的 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

另請參閱

NetQueryDisplayInformation

NetServerDiskEnum

網路管理功能

網路管理概觀

SERVER_INFO_100

SERVER_INFO_101

伺服器函式