Поделиться через


Функция 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 (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 для рабочих групп.
SV_TYPE_SERVER_MFPN
0x00004000
Любой сервер, на котором выполняется служба Microsoft File and Print for NetWare.
SV_TYPE_SERVER_NT
0x00008000
Любой сервер, который не является контроллером домена.
SV_TYPE_POTENTIAL_BROWSER
0x00010000
Любой компьютер, на который может запускаться служба браузера.
SV_TYPE_BACKUP_BROWSER
0x00020000
Компьютер, на котором выполняется служба браузера в качестве резервной копии.
SV_TYPE_MASTER_BROWSER
0x00040000
Компьютер, на котором выполняется служба браузера master.
SV_TYPE_DOMAIN_MASTER
0x00080000
Компьютер, на котором выполняется домен master браузере.
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 and Security Services (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.

Если функция завершается сбоем, возвращаемое значение может быть одним из следующих кодов ошибок:

Возвращаемый код/значение Описание
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 возвращает список серверов, обслуживаемых браузером. Это значение имеет значение только в браузере master (или на компьютере, который был master браузером в прошлом). Браузер master — это компьютер, который в настоящее время имеет права на определение компьютеров, которые могут быть серверами или рабочими станциями в сети.

Если не найдено серверов, соответствующих типам, указанным в параметре servertype , функция NetServerEnum возвращает параметр bufptr , так как значения NULL и DWORD, на которые указывают параметры entriesread и totalentries , равны нулю.

Функция 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
Header lmserver.h (включая Lm.h)
Библиотека Netapi32.lib
DLL Netapi32.dll

См. также раздел

NetQueryDisplayInformation

NetServerDiskEnum

Функции управления сетью

Общие сведения об управлении сетью

SERVER_INFO_100

SERVER_INFO_101

Функции сервера