NetUserSetGroups 函数 (lmaccess.h)

项目
08/24/2023

NetUserSetGroups 函数设置指定用户帐户的全局组成员身份。

语法

NET_API_STATUS NET_API_FUNCTION NetUserSetGroups(
  [in] LPCWSTR servername,
  [in] LPCWSTR username,
  [in] DWORD   level,
  [in] LPBYTE  buf,
  [in] DWORD   num_entries
);

parameters

[in] servername

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

[in] username

指向常量字符串的指针，该字符串指定要为其设置全局组成员身份的用户的名称。有关详细信息，请参见“备注”部分。

[in] level

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

值	含义
0	buf 参数指向指定全局组名称的GROUP_USERS_INFO_0结构的数组。
1	buf 参数指向GROUP_USERS_INFO_1结构的数组，这些结构指定具有属性的全局组名称。

[in] buf

指向指定数据的缓冲区的指针。有关详细信息，请参阅网络管理功能缓冲区。

[in] num_entries

buf 参数指向的数组中包含的条目数。

返回值

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

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

返回代码	说明
ERROR_ACCESS_DENIED	用户无权访问请求的信息。
ERROR_INVALID_LEVEL	系统调用级别不正确。如果将级别参数指定为 0 或 1 以外的值，则返回此错误。
ERROR_INVALID_PARAMETER	传递的参数无效。如果 num_entries 参数无效，则返回此错误。
ERROR_NOT_ENOUGH_MEMORY	内存不足，无法完成操作。
NERR_InvalidComputer	计算机名称无效。
NERR_NotPrimary	仅允许在域的主域控制器上执行此操作。
NERR_GroupNotFound	buf 参数指向的GROUP_USERS_INFO_0 GROUP_USERS_INFO_1结构中的grui0_name或grui1_name成员指定的组名称不存在。
NERR_InternalError	发生内部错误。
NERR_UserNotFound	找不到用户名。

注解

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

如果在运行 Active Directory 的域控制器上调用此函数，则会根据安全对象的访问控制列表 (ACL) 来允许或拒绝访问。默认 ACL 仅允许域管理员和帐户操作员调用此函数。在成员服务器或工作站上，只有管理员和 Power Users 才能调用此函数。有关详细信息，请参阅网络管理功能的安全要求。有关 ACL、ACE 和访问令牌的详细信息，请参阅访问控制模型。

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

若要在一个现有全局组中授予用户成员身份，可以调用 NetGroupAddUser 函数。

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

示例

以下代码示例演示如何通过调用 NetUserSetGroups 函数为用户帐户设置全局组成员身份。代码示例填充 GROUP_USERS_INFO_0 结构的 grui0_name 成员，并调用 NetUserSetGroups，并指定信息级别 0。

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "netapi32.lib")

#include <stdio.h>
#include <windows.h> 
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 0;
   GROUP_USERS_INFO_0 gi;
   NET_API_STATUS nStatus;

   if (argc != 4)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName GroupName\n", argv[0]);
      exit(1);
   }
   //
   // Fill in the GROUP_USERS_INFO_0 structure member.
   //
   gi.grui0_name = argv[3];
   //
   // Call the NetUserSetGroups function; specify level 0.
   //
   nStatus = NetUserSetGroups(argv[1],
                              argv[2],
                              dwLevel,
                              (LPBYTE)&gi,
                              1);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"Group membership has been successful for %s\n", argv[2]);
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

要求


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