NetQueryDisplayInformation 函数 (lmaccess.h)
NetQueryDisplayInformation 函数返回用户帐户、计算机或组帐户信息。 调用此函数可快速枚举帐户信息，以便在用户界面中显示。
语法
NET_API_STATUS NET_API_FUNCTION NetQueryDisplayInformation(
[in] LPCWSTR ServerName,
[in] DWORD Level,
[in] DWORD Index,
[in] DWORD EntriesRequested,
[in] DWORD PreferredMaximumLength,
[out] LPDWORD ReturnedEntryCount,
[out] PVOID *SortedBuffer
);
parameters
[in] ServerName
指向常量字符串的指针，该常量字符串指定要在其中执行函数的远程服务器的 DNS 或 NetBIOS 名称。 如果此参数为 NULL，则使用本地计算机。
[in] Level
指定数据的信息级别。 此参数的取值可为下列值之一：
| 值 | 含义 |
|---|---|
|
返回用户帐户信息。 SortedBuffer 参数指向NET_DISPLAY_USER结构的数组。 |
|
返回单个计算机信息。 SortedBuffer 参数指向NET_DISPLAY_MACHINE结构的数组。 |
|
返回组帐户信息。 SortedBuffer 参数指向NET_DISPLAY_GROUP结构的数组。 |
[in] Index
指定要检索其信息的第一个条目的索引。 指定零以从第一个显示信息条目开始检索帐户信息。 有关更多信息，请参见下面的“备注”部分。
[in] EntriesRequested
指定要检索其信息的最大条目数。 在 Windows 2000 及更高版本中，每次调用 NetQueryDisplayInformation 最多返回 100 个对象。
[in] PreferredMaximumLength
指定 SortedBuffer 参数中返回的系统分配缓冲区的首选最大大小（以字节为单位）。 建议将此参数设置为 MAX_PREFERRED_LENGTH。
[out] ReturnedEntryCount
指向一个值的指针，该值接收 SortedBuffer 参数中返回的缓冲区中的条目数。 如果此参数为零，则索引没有与指定的索引大小一样大的条目。 当函数的返回值NERR_Success或ERROR_MORE_DATA时，可能会返回条目。
[out] SortedBuffer
指向缓冲区的指针，该缓冲区接收指向系统分配的缓冲区的指针，该缓冲区指定所请求信息的排序列表。 此数据的格式取决于 Level 参数的值。 由于此缓冲区由系统分配，因此必须使用 NetApiBufferFree 函数将其释放。 请注意，即使函数失败并出现ERROR_MORE_DATA，也必须释放缓冲区。 有关详细信息，请参阅以下返回值部分，以及主题 网络管理功能缓冲区 和 网络管理功能缓冲区长度。
返回值
如果函数成功，则返回值NERR_Success。
如果函数失败，则返回值为以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
用户无权访问请求的信息。 |
|
Level 参数指定的值无效。 |
|
有更多条目可用。 也就是说， SortedBuffer 参数中返回的最后一个条目不是最后一个可用条目。 若要检索其他条目，请再次调用 NetQueryDisplayInformation，并将 Index 参数设置为 SortedBuffer 中最后一个条目的 next_index 成员中返回的值。 请注意，除了通过对 NetQueryDisplayInformation 的其他调用检索更多数据之外，不应将 next_index 成员的值用于任何目的。 |
注解
如果在运行 Active Directory 的域控制器上调用此函数，则会根据 安全对象的访问控制列表 (ACL) 允许或拒绝访问。 默认 ACL 允许所有经过身份验证的用户和“Pre-Windows 2000 兼容访问”组的成员查看信息。 如果在成员服务器或工作站上调用此函数，则所有经过身份验证的用户都可以查看信息。 有关这些平台上的匿名访问和限制匿名访问的信息，请参阅 网络管理功能的安全要求。 有关 ACL、ACE 和访问令牌的详细信息，请参阅访问控制模型。
NetQueryDisplayInformation 函数仅返回调用方具有读取访问权限的信息。 调用方必须具有对 Domain 对象的 List Contents 访问权限，并且对位于系统容器中的 SAM 服务器对象枚举整个 SAM 域访问权限。
NetQueryDisplayInformation 和 NetGetDisplayInformationIndex 函数提供了一种用于枚举用户和组帐户的有效机制。 如果可能，请使用这些函数，而不是 NetUserEnum 函数或 NetGroupEnum 函数。
若要枚举信任域或成员计算机帐户，请调用 NetUserEnum，指定相应的筛选器值以获取所需的帐户信息。 若要枚举受信任的域，请调用 LsaEnumerateTrustedDomains 或 LsaEnumerateTrustedDomainsEx 函数。
此函数返回的条目数取决于根域对象上的安全描述符。 API 将返回域中的前 100 个条目或整个条目集，具体取决于用户的访问权限。 用于控制此行为的 ACE 是“SAM-Enumerate-Entire-Domain”，默认情况下授予经过身份验证的用户。 管理员可以修改此设置，以允许用户枚举整个域。
每次调用 NetQueryDisplayInformation 最多返回 100 个对象。 调用 NetQueryDisplayInformation 函数来枚举域帐户信息可能会降低性能成本。 如果要对 Active Directory 进行编程，则可以使用 IDirectorySearch 接口上的方法针对域进行分页查询。 有关详细信息，请参阅 IDirectorySearch：：SetSearchPreference 和 IDirectorySearch：：ExecuteSearch。 若要枚举受信任的域，请调用 LsaEnumerateTrustedDomainsEx 函数。
示例
下面的代码示例演示如何使用调用 NetQueryDisplayInformation 函数返回组帐户信息。 如果用户指定服务器名称，则示例首先调用 MultiByteToWideChar 函数，以将该名称转换为 Unicode。 此示例调用 NetQueryDisplayInformation，指定信息级别 3 (NET_DISPLAY_GROUP) 来检索组帐户信息。 如果有要返回的条目，示例将返回数据并打印组信息。 最后，代码示例释放为信息缓冲区分配的内存。
#ifndef UNICODE
#define UNICODE
#endif
#include <windows.h>
#include <stdio.h>
#include <lm.h>
#pragma comment(lib, "netapi32.lib")
void main( int argc, char *argv[ ] )
{
PNET_DISPLAY_GROUP pBuff, p;
DWORD res, dwRec, i = 0;
//
// You can pass a NULL or empty string
// to retrieve the local information.
//
TCHAR szServer[255]=TEXT("");
if(argc > 1)
//
// Check to see if a server name was passed;
// if so, convert it to Unicode.
//
MultiByteToWideChar(CP_ACP, 0, argv[1], -1, szServer, 255);
do // begin do
{
//
// Call the NetQueryDisplayInformation function;
// specify information level 3 (group account information).
//
res = NetQueryDisplayInformation(szServer, 3, i, 1000, MAX_PREFERRED_LENGTH, &dwRec, (PVOID*) &pBuff);
//
// If the call succeeds,
//
if((res==ERROR_SUCCESS) || (res==ERROR_MORE_DATA))
{
p = pBuff;
for(;dwRec>0;dwRec--)
{
//
// Print the retrieved group information.
//
printf("Name: %S\n"
"Comment: %S\n"
"Group ID: %u\n"
"Attributes: %u\n"
"--------------------------------\n",
p->grpi3_name,
p->grpi3_comment,
p->grpi3_group_id,
p->grpi3_attributes);
//
// If there is more data, set the index.
//
i = p->grpi3_next_index;
p++;
}
//
// Free the allocated memory.
//
NetApiBufferFree(pBuff);
}
else
printf("Error: %u\n", res);
//
// Continue while there is more data.
//
} while (res==ERROR_MORE_DATA); // end do
return;
}
要求
| 最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
| 最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | lmaccess.h (包括 Lm.h) |
| Library | Netapi32.lib |
| DLL | Netapi32.dll |