NetUserGetGroups 函数 (lmaccess.h)

项目
08/24/2023

NetUserGetGroups 函数检索指定用户所属的全局组的列表。

语法

NET_API_STATUS NET_API_FUNCTION NetUserGetGroups(
  [in]  LPCWSTR servername,
  [in]  LPCWSTR username,
  [in]  DWORD   level,
  [out] LPBYTE  *bufptr,
  [in]  DWORD   prefmaxlen,
  [out] LPDWORD entriesread,
  [out] LPDWORD totalentries
);

parameters

[in] servername

指向常量字符串的指针，该字符串指定要对其执行函数的远程服务器的 DNS 或 NetBIOS 名称。如果此参数为 NULL，则使用本地计算机。

[in] username

指向常量字符串的指针，该字符串指定要在每个组帐户中搜索的用户的名称。有关更多信息，请参见下面的“备注”部分。

[in] level

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

值	含义
0	返回用户所属的全局组的名称。 bufptr 参数指向GROUP_USERS_INFO_0结构的数组。
1	使用属性返回用户所属的全局组的名称。 bufptr 参数指向GROUP_USERS_INFO_1结构的数组。

[out] bufptr

指向接收数据的缓冲区的指针。此缓冲区由系统分配，必须使用 NetApiBufferFree 函数释放。请注意，即使函数因ERROR_MORE_DATA而失败，也必须释放缓冲区。

[in] prefmaxlen

返回数据的首选最大长度（以字节为单位）。如果指定了MAX_PREFERRED_LENGTH，函数将分配数据所需的内存量。如果在此参数中指定了另一个值，则可以限制函数返回的字节数。如果缓冲区大小不足以容纳所有条目，则函数将返回ERROR_MORE_DATA。有关详细信息，请参阅网络管理功能缓冲区和网络管理功能缓冲区长度。

[out] entriesread

指向一个值的指针，该值接收实际检索到的元素计数。

[out] totalentries

指向一个值的指针，该值接收可能已检索的条目总数。

返回值

如果函数成功，则返回值NERR_Success。

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

返回代码	说明
ERROR_ACCESS_DENIED	用户对请求的信息没有访问权限。
ERROR_BAD_NETPATH	找不到网络路径。如果找不到 servername 参数，则返回此错误。
ERROR_INVALID_LEVEL	系统调用级别不正确。如果将级别参数指定为 0 或 1 以外的值，则返回此错误。
ERROR_INVALID_NAME	名称语法不正确。如果 servername 参数具有前导空格或尾随空格或包含非法字符，则返回此错误。
ERROR_MORE_DATA	有更多条目可用。指定一个足够大的缓冲区来接收所有条目。
ERROR_NOT_ENOUGH_MEMORY	内存不足，无法完成操作。
NERR_InternalError	发生内部错误。
NERR_UserNotFound	找不到用户。如果找不到用户名，则返回此错误。

注解

如果要对 Active Directory 进行编程，则可以调用某些 Active Directory 服务接口 (ADSI) 方法，以实现通过调用网络管理用户函数实现的相同功能。有关详细信息，请参阅 IADsUser 和 IADsComputer。

如果在运行 Active Directory 的域控制器上调用此函数，则会根据安全对象的访问控制列表 (ACL) 来允许或拒绝访问。默认 ACL 允许所有经过身份验证的用户和“Windows 2000 前兼容访问”组的成员查看信息。如果在成员服务器或工作站上调用此函数，则所有经过身份验证的用户都可以查看信息。有关这些平台上的匿名访问和限制匿名访问的信息，请参阅网络管理功能的安全要求。有关 ACL、ACE 和访问令牌的详细信息，请参阅访问控制模型。

User 对象的安全描述符用于执行此函数的访问检查。

若要检索用户所属的本地组的列表，可以调用 NetUserGetLocalGroups 函数。网络组独立于 Windows NT 系统组。

用户帐户名称限制为 20 个字符，组名限制为 256 个字符。此外，帐户名称不能以句点结尾，并且不能包含逗号或以下任何可打印字符：“，/，，，[，]，：，|， <，，， >+，=，;，？，*。名称也不能包含范围 1-31 中的字符，这些字符不可打印。

示例

下面的代码示例演示如何通过调用 NetUserGetGroups 函数检索用户所属的全局组列表。此示例调用 NetUserGetGroups，将信息级别指定为 0 ( GROUP_USERS_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[])
{
   LPGROUP_USERS_INFO_0 pBuf = NULL;
   DWORD dwLevel = 0;
   DWORD dwPrefMaxLen = MAX_PREFERRED_LENGTH;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   NET_API_STATUS nStatus;

   if (argc != 3)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
      exit(1);
   }
   //
   // Call the NetUserGetGroups function, specifying level 0.
   //
   nStatus = NetUserGetGroups(argv[1],
                              argv[2],
                              dwLevel,
                              (LPBYTE*)&pBuf,
                              dwPrefMaxLen,
                              &dwEntriesRead,
                              &dwTotalEntries);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      LPGROUP_USERS_INFO_0 pTmpBuf;
      DWORD i;
      DWORD dwTotalCount = 0;

      if ((pTmpBuf = pBuf) != NULL)
      {
         fprintf(stderr, "\nGlobal group(s):\n");
         //
         // Loop through the entries; 
         //  print the name of the global groups 
         //  to which the user belongs.
         //
         for (i = 0; i < dwEntriesRead; i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }

            wprintf(L"\t-- %s\n", pTmpBuf->grui0_name);

            pTmpBuf++;
            dwTotalCount++;
         }
      }
      //
      // If all available entries were
      //  not enumerated, print the number actually 
      //  enumerated and the total number available.
      //
      if (dwEntriesRead < dwTotalEntries)
         fprintf(stderr, "\nTotal entries: %d", dwTotalEntries);
      //
      // Otherwise, just print the total.
      //
      printf("\nEntries enumerated: %d\n", dwTotalCount);
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	lmaccess.h (包括 Lm.h)
Library	Netapi32.lib
DLL	Netapi32.dll