Функция 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

Уровень информации запрашиваемых данных. Этот параметр может принимать одно из указанных ниже значений.

[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.

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

Комментарии

Функция 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;
}

Требования

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

NetQueryDisplayInformation

NetServerDiskEnum

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

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

SERVER_INFO_100

SERVER_INFO_101

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