Функция NetUserEnum (lmaccess.h)
Функция NetUserEnum извлекает сведения обо всех учетных записях пользователей на сервере.
Синтаксис
NET_API_STATUS NET_API_FUNCTION NetUserEnum(
[in] LPCWSTR servername,
[in] DWORD level,
[in] DWORD filter,
[out] LPBYTE *bufptr,
[in] DWORD prefmaxlen,
[out] LPDWORD entriesread,
[out] LPDWORD totalentries,
[in, out] PDWORD resume_handle
);
Параметры
[in] servername
Указатель на константную строку, указывающую DNS- или NetBIOS-имя удаленного сервера, на котором выполняется функция. Если этот параметр имеет значение NULL, используется локальный компьютер.
[in] level
Указывает уровень информации о данных. Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Возвращает имена учетных записей пользователей. Параметр bufptr указывает на массив USER_INFO_0 структур. |
|
Возвращает подробные сведения об учетных записях пользователей. Параметр bufptr указывает на массив USER_INFO_1 структур. |
|
Возвращает подробные сведения об учетных записях пользователей, включая уровни авторизации и сведения о входе в систему. Параметр bufptr указывает на массив USER_INFO_2 структур. |
|
Возвращает подробные сведения об учетных записях пользователей, включая уровни авторизации, сведения о входе в систему, идентификаторы идентификаторов для пользователя и основной группы, а также сведения о профиле. Параметр bufptr указывает на массив USER_INFO_3 структур. |
|
Возвращает имена пользователей и учетных записей и комментарии. Параметр bufptr указывает на массив USER_INFO_10 структур. |
|
Возвращает подробные сведения об учетных записях пользователей. Параметр bufptr указывает на массив USER_INFO_11 структур. |
|
Возвращает имя и идентификатор пользователя, а также различные атрибуты учетной записи. Параметр bufptr указывает на массив USER_INFO_20 структур. Обратите внимание, что в Windows XP и более поздних версиях рекомендуется использовать USER_INFO_23 . |
[in] filter
Значение типа , указывающее типы учетных записей пользователей, которые будут включены в перечисление. Значение , равное нулю, указывает, что должны быть включены все обычные данные пользователя, доверия и данные учетной записи компьютера.
Этот параметр также может быть сочетанием следующих значений.
[out] bufptr
Указатель на буфер, который получает данные. Формат этих данных зависит от значения параметра level .
Буфер для этих данных выделяется системой, и приложение должно вызвать функцию NetApiBufferFree , чтобы освободить выделенную память, когда возвращаемые данные больше не нужны. Обратите внимание, что буфер необходимо освободить, даже если функция NetUserEnum завершается сбоем с ERROR_MORE_DATA.
[in] prefmaxlen
Предпочтительная максимальная длина возвращаемых данных в байтах. Если указать MAX_PREFERRED_LENGTH, функция NetUserEnum выделяет объем памяти, необходимый для данных. Если указать другое значение в этом параметре, это может ограничить количество байтов, возвращаемых функцией. Если размер буфера недостаточен для хранения всех записей, функция возвращает ERROR_MORE_DATA. Дополнительные сведения см. в разделах Буферы функций управления сетью и Длина буфера функции управления сетью.
[out] entriesread
Указатель на значение, которое получает количество фактически перечисляемых элементов.
[out] totalentries
Указатель на значение, которое получает общее количество записей, которые можно было бы перечислить из текущей позиции резюме. Обратите внимание, что приложения должны рассматривать это значение только как подсказку. Если приложение взаимодействует с контроллером домена Windows 2000 или более поздней версии, рекомендуется использовать поставщик LDAP ADSI для более эффективного получения данных этого типа. Поставщик LDAP ADSI реализует набор объектов ADSI, поддерживающих различные интерфейсы ADSI. Дополнительные сведения см. в разделе Поставщики услуг ADSI.
Диспетчер локальной сети: Если вызов выполняется на компьютер, на котором запущен диспетчер локальной сети 2. x, параметр totalentries всегда будет отражать общее количество записей в базе данных независимо от того, где она находится в последовательности резюме.
[in, out] resume_handle
Указатель на значение, содержащее дескриптор возобновления, который используется для продолжения поиска существующего пользователя. Дескриптор должен быть равен нулю при первом вызове и оставить без изменений для последующих вызовов. Если этот параметр имеет значение NULL, дескриптор возобновления не сохраняется.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет NERR_Success.
Если функция завершается сбоем, возвращаемое значение может быть одним из следующих кодов ошибок.
| Код возврата | Описание |
|---|---|
|
У пользователя нет доступа к запрошенной информации. |
|
Неправильный уровень системного вызова. Эта ошибка возвращается, если для параметра level задано значение, которое не поддерживается. |
|
Буфер слишком мал, чтобы содержать запись. Никакие сведения не записаны в буфер. |
|
Недопустимое имя компьютера. |
|
Доступны дополнительные записи. Укажите достаточно большой буфер для получения всех записей. |
Комментарии
Функция NetUserEnum извлекает сведения обо всех учетных записях пользователей на указанном удаленном сервере или локальном компьютере.
Функцию NetQueryDisplayInformation можно использовать для быстрого перечисления сведений об учетной записи пользователя, компьютера или глобальной группы для отображения в пользовательских интерфейсах .
При программировании для Active Directory вы можете вызвать определенные методы интерфейса службы Active Directory (ADSI) для достижения той же функциональности, которую можно достичь, вызвав пользовательские функции управления сетью. Дополнительные сведения см. в разделах IADsUser и IADsComputer.
При вызове функции NetUserEnum на контроллере домена под управлением Active Directory доступ будет разрешен или запрещен на основе списка управления доступом (ACL) для защищаемого объекта. Список управления доступом по умолчанию позволяет просматривать сведения всем пользователям, прошедшим проверку подлинности, и членам группы "Доступ, совместимый с Windows 2000". Если вы вызываете эту функцию на рядовом сервере или рабочей станции, все пользователи, прошедшие проверку подлинности, смогут просматривать сведения. Сведения об анонимном доступе и ограничении анонимного доступа на этих платформах см. в разделе Требования к безопасности для функций управления сетью. Дополнительные сведения о списках управления доступом, ACE и маркерах доступа см. в разделе модель контроль доступа.
Функция NetUserEnum возвращает только сведения, к которым вызывающий объект имеет доступ на чтение. Вызывающий объект должен иметь доступ List Contents к объекту Domain и Перечислить полный доступ к домену SAM для объекта SAM Server, расположенного в контейнере System.
Функцию LsaEnumerateTrustedDomains или LsaEnumerateTrustedDomainsEx можно использовать для получения имен и идентификаторов безопасности доменов, доверенных объектом политики локального центра безопасности (LSA).
Функция NetUserEnum не возвращает всех системных пользователей. Он возвращает только тех пользователей, которые были добавлены с помощью вызова функции NetUserAdd . Нет никакой гарантии, что список пользователей будет возвращен в отсортированном порядке.
Если вызвать функцию NetUserEnum и указать уровень сведений 1, 2 или 3 для параметра level , элемент пароля каждой полученной структуры будет иметь значение NULL для обеспечения безопасности пароля.
Имена учетных записей пользователей ограничены 20 символами, а имена групп — 256 символами. Кроме того, имена учетных записей не могут быть завершены точкой и не могут содержать запятые или какие-либо из следующих печатных символов: ", /, , [, ], :, |, <, >, +, =, ;, ?, *. Имена также не могут содержать символы в диапазоне от 1 до 31, которые не могут быть печатными.
Функция NetUserEnum не поддерживает параметр уровня 4 и структуру USER_INFO_4 . Функция NetUserGetInfo поддерживает параметр уровня 4 и структуру USER_INFO_4 .
Примеры
В следующем примере кода показано, как получить сведения об учетных записях пользователей на сервере с помощью вызова функции NetUserEnum . Пример вызывает NetUserEnum, указывая уровень информации 0 (USER_INFO_0) для перечисления только глобальных учетных записей пользователей. Если вызов завершается успешно, код циклически перебирает записи и выводит имя каждой учетной записи пользователя. Наконец, в примере кода освобождается память, выделенная для информационного буфера, и выводится общее число пользователей.
#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[])
{
LPUSER_INFO_0 pBuf = NULL;
LPUSER_INFO_0 pTmpBuf;
DWORD dwLevel = 0;
DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
DWORD dwEntriesRead = 0;
DWORD dwTotalEntries = 0;
DWORD dwResumeHandle = 0;
DWORD i;
DWORD dwTotalCount = 0;
NET_API_STATUS nStatus;
LPTSTR pszServerName = NULL;
if (argc > 2)
{
fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
exit(1);
}
// The server is not the default local computer.
//
if (argc == 2)
pszServerName = (LPTSTR) argv[1];
wprintf(L"\nUser account on %s: \n", pszServerName);
//
// Call the NetUserEnum function, specifying level 0;
// enumerate global user account types only.
//
do // begin do
{
nStatus = NetUserEnum((LPCWSTR) pszServerName,
dwLevel,
FILTER_NORMAL_ACCOUNT, // global users
(LPBYTE*)&pBuf,
dwPrefMaxLen,
&dwEntriesRead,
&dwTotalEntries,
&dwResumeHandle);
//
// If the call succeeds,
//
if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
{
if ((pTmpBuf = pBuf) != NULL)
{
//
// Loop through the entries.
//
for (i = 0; (i < dwEntriesRead); i++)
{
assert(pTmpBuf != NULL);
if (pTmpBuf == NULL)
{
fprintf(stderr, "An access violation has occurred\n");
break;
}
//
// Print the name of the user account.
//
wprintf(L"\t-- %s\n", pTmpBuf->usri0_name);
pTmpBuf++;
dwTotalCount++;
}
}
}
//
// Otherwise, print the system error.
//
else
fprintf(stderr, "A system error has occurred: %d\n", nStatus);
//
// Free the allocated buffer.
//
if (pBuf != NULL)
{
NetApiBufferFree(pBuf);
pBuf = NULL;
}
}
// Continue to call NetUserEnum while
// there are more entries.
//
while (nStatus == ERROR_MORE_DATA); // end do
//
// Check again for allocated memory.
//
if (pBuf != NULL)
NetApiBufferFree(pBuf);
//
// Print the final count of users enumerated.
//
fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);
return 0;
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | lmaccess.h (включая Lm.h) |
| Библиотека | Netapi32.lib |
| DLL | Netapi32.dll |