Функция 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.
Если функция завершается сбоем, возвращаемое значение может быть одним из следующих кодов ошибок:
| Возвращаемый код/значение | Описание |
|---|---|
|
В доступе было отказано. |
|
Неправильный параметр". |
|
Доступны дополнительные записи. Укажите достаточно большой буфер для получения всех записей. |
|
Серверы браузера не найдены. |
|
Запрос не поддерживается. |
|
Произошла удаленная ошибка без данных, возвращенных сервером. |
|
Служба сервера не запущена. |
|
Служба не запущена. |
|
Служба рабочей станции не запущена. Служба локальной рабочей станции используется для взаимодействия с удаленным сервером нижнего уровня. |
Комментарии
Функция 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 |