NetLocalGroupEnum 函数 (lmaccess.h)

项目
08/24/2023

NetLocalGroupEnum 函数返回有关指定服务器上的每个本地组帐户的信息。

语法

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

parameters

[in] servername

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

[in] level

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

值	含义
0	返回本地组名称。 bufptr 参数指向LOCALGROUP_INFO_0结构的数组。
1	返回本地组名称和与每个组关联的注释。 bufptr 参数指向LOCALGROUP_INFO_1结构的数组。

[out] bufptr

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

[in] prefmaxlen

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

[out] entriesread

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

[out] totalentries

指向一个值的指针，该值接收可能从当前恢复位置枚举的大致总条目数。条目总数只是一个提示。有关确定确切条目数的详细信息，请参阅以下“备注”部分。

[in, out] resumehandle

指向一个值的指针，该值包含用于继续现有本地组搜索的恢复句柄。第一次调用时，句柄应为零，后续调用应保持不变。如果此参数为 NULL，则不存储任何恢复句柄。有关更多信息，请参见下面的“备注”部分。

返回值

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

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

返回代码	说明
ERROR_ACCESS_DENIED	用户无权访问请求的信息。
ERROR_MORE_DATA	有更多条目可用。指定一个足够大的缓冲区来接收所有条目。
NERR_InvalidComputer	计算机名称无效。
NERR_BufTooSmall	返回缓冲区太小。

注解

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

函数仅返回调用方具有读取访问权限的信息。调用方必须具有对 Domain 对象的 List Contents 访问权限，并枚举位于系统容器中的 SAM Server 对象上的整个 SAM 域访问权限。

若要确定本地组的确切总数，必须枚举整个树，这可能代价高昂。若要枚举整个树，请使用 resumehandle 参数继续枚举连续调用，并使用 entriesread 参数累积本地组的总数。如果应用程序正在与域控制器通信，应考虑使用 ADSI LDAP 提供程序更高效地检索此类数据。 ADSI LDAP 提供程序实现一组支持各种 ADSI 接口的 ADSI 对象。有关详细信息，请参阅 ADSI 服务提供程序。

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

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

要求


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