NetUserGetLocalGroups 函数 (lmaccess.h)

  • 项目

NetUserGetLocalGroups 函数检索指定用户所属的本地组列表。

语法

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

parameters

[in] servername

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

[in] username

指向常量字符串的指针，该字符串指定要为其返回本地组成员身份信息的用户的名称。 如果字符串的格式为 DomainName\UserName ，则用户应在该域上找到用户名。 如果字符串的格式为 UserName，则应在 servername 参数指定的服务器上找到用户名。 有关详细信息，请参见“备注”部分。

[in] level

数据的信息级别。 此参数可以是以下值。

值 含义
0
 返回用户所属的本地组的名称。 bufptr 参数指向LOCALGROUP_USERS_INFO_0结构的数组。

[in] flags

影响操作的标志的位掩码。 目前，只有定义的值 LG_INCLUDE_INDIRECT。 如果设置此位，函数还会返回本地组的名称，用户在其中间接成为成员 (即，用户在全局组中具有成员身份，而全局组本身是一个或多个本地组的成员) 。

[out] bufptr

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

[in] prefmaxlen

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

[out] entriesread

指向一个值的指针，该值接收实际枚举的元素计数。

[out] totalentries

指向一个值的指针，该值接收可能枚举的条目总数。

返回值

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

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

返回代码 说明
ERROR_ACCESS_DENIED
 用户对请求的信息没有访问权限。 如果 servername 参数的尾随空白，也会返回此错误。
ERROR_INVALID_LEVEL
 系统调用级别不正确。 如果未将 级别 参数指定为 0，则返回此错误。
ERROR_INVALID_PARAMETER
 参数不正确。 如果 flags 参数包含 除 LG_INCLUDE_INDIRECT 以外的值，则返回此错误。
ERROR_MORE_DATA
 有更多条目可用。 指定一个足够大的缓冲区来接收所有条目。
ERROR_NOT_ENOUGH_MEMORY
 内存不足，无法完成操作。
NERR_DCNotFound
 找不到域控制器。
NERR_UserNotFound
 找不到用户。 如果找不到 用户名 ，则返回此错误。
RPC_S_SERVER_UNAVAILABLE
 RPC 服务器不可用。 如果找不到 servername 参数，则返回此错误。

注解

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

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

Domain 对象的安全描述符用于执行此函数的访问检查。 调用方必须对 Domain 对象具有读取属性权限。

若要检索指定用户所属的全局组的列表，可以调用 NetUserGetGroups 函数。

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

示例

以下代码示例演示如何通过调用 NetUserGetLocalGroups 函数检索用户所属的本地组的列表。 此示例调用 NetUserGetLocalGroups，将信息级别指定为 0 (LOCALGROUP_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[])
{
   LPLOCALGROUP_USERS_INFO_0 pBuf = NULL;
   DWORD dwLevel = 0;
   DWORD dwFlags = LG_INCLUDE_INDIRECT ;
   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 NetUserGetLocalGroups function 
   //  specifying information level 0.
   //
   //  The LG_INCLUDE_INDIRECT flag specifies that the 
   //   function should also return the names of the local 
   //   groups in which the user is indirectly a member.
   //
   nStatus = NetUserGetLocalGroups(argv[1],
                                   argv[2],
                                   dwLevel,
                                   dwFlags,
                                   (LPBYTE *) &pBuf,
                                   dwPrefMaxLen,
                                   &dwEntriesRead,
                                   &dwTotalEntries);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      LPLOCALGROUP_USERS_INFO_0 pTmpBuf;
      DWORD i;
      DWORD dwTotalCount = 0;

      if ((pTmpBuf = pBuf) != NULL)
      {
         fprintf(stderr, "\nLocal group(s):\n");
         //
         // Loop through the entries and 
         //  print the names of the local 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->lgrui0_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 memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

要求

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

另请参阅

LOCALGROUP_USERS_INFO_0

NetUserGetGroups

网络管理功能

网络管理概述

用户函数