NetUserGetGroups 函数 (lmaccess.h)
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
请求的数据的信息级别。 此参数的取值可为下列值之一：
| 值 | 含义 |
|---|---|
|
返回用户所属的全局组的名称。 bufptr 参数指向GROUP_USERS_INFO_0结构的数组。 |
|
使用属性返回用户所属的全局组的名称。 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。
如果函数失败，则返回值可能是以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
用户对请求的信息没有访问权限。 |
|
找不到网络路径。 如果找不到 servername 参数，则返回此错误。 |
|
系统调用级别不正确。 如果将 级别 参数指定为 0 或 1 以外的值，则返回此错误。 |
|
名称语法不正确。 如果 servername 参数具有前导空格或尾随空格或包含非法字符，则返回此错误。 |
|
有更多条目可用。 指定一个足够大的缓冲区来接收所有条目。 |
|
内存不足，无法完成操作。 |
|
发生内部错误。 |
|
找不到用户。 如果找不到 用户名 ，则返回此错误。 |
注解
如果要对 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 |