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结构的数组。 |
|
返回有关用户帐户的详细信息，包括授权级别、登录信息、用户和主要组的 RID 以及配置文件信息。 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
指向接收数据的缓冲区的指针。 此数据的格式取决于 级别 参数的值。
此数据的缓冲区由系统分配，应用程序必须调用 NetApiBufferFree 函数，以便在不再需要返回的数据时释放分配的内存。 请注意，即使 NetUserEnum 函数因ERROR_MORE_DATA失败，也必须释放缓冲区。
[in] prefmaxlen
返回数据的首选最大长度（以字节为单位）。 如果指定 MAX_PREFERRED_LENGTH，NetUserEnum 函数将分配数据所需的内存量。 如果在此参数中指定另一个值，它可以限制函数返回的字节数。 如果缓冲区大小不足以容纳所有条目，则函数将返回ERROR_MORE_DATA。 有关详细信息，请参阅 网络管理功能缓冲区 和 网络管理功能缓冲区长度。
[out] entriesread
指向一个值的指针，该值接收实际枚举的元素计数。
[out] totalentries
指向一个值的指针，该值接收可能从当前恢复位置枚举的条目总数。 请注意，应用程序应仅将此值视为提示。 如果应用程序正在与 Windows 2000 或更高版本的域控制器通信，则应考虑使用 ADSI LDAP 提供程序 更高效地检索此类数据。 ADSI LDAP 提供程序实现一组支持各种 ADSI 接口的 ADSI 对象。 有关详细信息，请参阅 ADSI 服务提供程序。
LAN 管理器： 如果调用的是运行 LAN Manager 2 的计算机。x， totalentries 参数将始终反映数据库中的条目总数，无论它在恢复序列中的哪个位置。
[in, out] resume_handle
指向一个值的指针，该值包含用于继续现有用户搜索的恢复句柄。 第一次调用时，句柄应为零，后续调用应保持不变。 如果此参数为 NULL，则不存储任何恢复句柄。
返回值
如果函数成功，则返回值NERR_Success。
如果函数失败，则返回值可能是以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
用户无权访问请求的信息。 |
|
系统调用级别不正确。 如果 级别 参数设置为不支持的值，则返回此错误。 |
|
缓冲区太小，无法包含条目。 尚未将任何信息写入缓冲区。 |
|
计算机名称无效。 |
|
有更多条目可用。 指定一个足够大的缓冲区来接收所有条目。 |
注解
NetUserEnum 函数检索有关指定远程服务器或本地计算机上的所有用户帐户的信息。
NetQueryDisplayInformation 函数可用于快速枚举用户、计算机或全局组帐户信息，以便在用户界面 中显示。
如果要对 Active Directory 进行编程，则可以调用某些 Active Directory 服务接口 (ADSI) 方法，以实现通过调用网络管理用户函数实现的相同功能。 有关详细信息，请参阅 IADsUser 和 IADsComputer。
如果在运行 Active Directory 的域控制器上调用 NetUserEnum 函数，则会根据 安全对象的访问控制列表 (ACL) 允许或拒绝访问。 默认 ACL 允许所有经过身份验证的用户和“Windows 2000 前兼容访问”组的成员查看信息。 如果在成员服务器或工作站上调用此函数，则所有经过身份验证的用户都可以查看信息。 有关这些平台上的匿名访问和限制匿名访问的信息，请参阅 网络管理功能的安全要求。 有关 ACL、ACE 和访问令牌的详细信息，请参阅访问控制模型。
NetUserEnum 函数仅返回调用方具有读取访问权限的信息。 调用方必须具有对 Domain 对象的 List Contents 访问权限，并枚举位于系统容器中的 SAM Server 对象上的整个 SAM 域访问权限。
LsaEnumerateTrustedDomains 或 LsaEnumerateTrustedDomainsEx 函数可用于检索本地安全机构信任的域的名称和 SID (LSA) 策略对象。
NetUserEnum 函数不会返回所有系统用户。 它仅返回通过调用 NetUserAdd 函数添加的用户。 无法保证将按排序顺序返回用户列表。
如果调用 NetUserEnum 函数并为 级别 参数指定信息级别 1、2 或 3，则检索到的每个结构的密码成员将设置为 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 |
| 标头 | lmaccess.h (包括 Lm.h) |
| Library | Netapi32.lib |
| DLL | Netapi32.dll |