NetQueryDisplayInformation 函数 (lmaccess.h)

项目
08/24/2023

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

指定数据的信息级别。此参数的取值可为下列值之一：

值	含义
1	返回用户帐户信息。 SortedBuffer 参数指向NET_DISPLAY_USER结构的数组。
2	返回单个计算机信息。 SortedBuffer 参数指向NET_DISPLAY_MACHINE结构的数组。
3	返回组帐户信息。 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。

如果函数失败，则返回值为以下错误代码之一。

返回代码	说明
ERROR_ACCESS_DENIED	用户无权访问请求的信息。
ERROR_INVALID_LEVEL	Level 参数指定的值无效。
ERROR_MORE_DATA	有更多条目可用。也就是说， 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