NetUserAdd 函数 (lmaccess.h)

项目
08/24/2023

NetUserAdd 函数添加用户帐户并分配密码和特权级别。

语法

NET_API_STATUS NET_API_FUNCTION NetUserAdd(
  [in]  LPCWSTR servername,
  [in]  DWORD   level,
  [in]  LPBYTE  buf,
  [out] LPDWORD parm_err
);

参数

[in] servername

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

如果定义了 _WIN32_WINNT 或 FORCE_UNICODE ，则此字符串为 Unicode。

[in] level

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

值	含义
1	指定有关用户帐户的信息。 buf 参数指向USER_INFO_1结构。指定此级别时，调用会将某些属性初始化为其默认值。有关更多信息，请参见下面的“备注”部分。
2	指定第一级信息和有关用户帐户的其他属性。 buf 参数指向USER_INFO_2结构。
3	指定有关用户帐户的二级信息和附加属性。此级别仅在服务器上有效。 buf 参数指向USER_INFO_3结构。请注意，建议改用 USER_INFO_4 。
4	指定有关用户帐户的二级信息和附加属性。此级别仅在服务器上有效。 buf 参数指向USER_INFO_4结构。 Windows 2000：不支持此级别。

[in] buf

指向指定数据的缓冲区的指针。此数据的格式取决于级别参数的值。有关详细信息，请参阅网络管理功能缓冲区。

[out] parm_err

指向一个值的指针，该值接收导致ERROR_INVALID_PARAMETER的用户信息结构第一个成员的索引。如果此参数为 NULL，则错误时不会返回索引。有关详细信息，请参阅 NetUserSetInfo 函数。

返回值

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

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

返回代码	说明
ERROR_ACCESS_DENIED	用户无权访问请求的信息。
NERR_InvalidComputer	计算机名称无效。
NERR_NotPrimary	仅允许在域的主域控制器上执行此操作。
NERR_GroupExists	组已存在。
NERR_UserExists	用户帐户已存在。
NERR_PasswordTooShort	密码短于所需密码。 (The password could also be too long, be too recent in its change history, not have enough unique characters, or not meet another password policy requirement.)（密码过短。（密码也可能过长、在其更改历史记录中过新、未包含足够的独特字符或者未符合另一项密码策略的要求。））

注解

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

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

用户容器的安全描述符用于执行此函数的访问检查。调用方必须能够创建用户类的子对象。

服务器用户必须使用服务器在其中为新用户创建系统帐户的系统。此帐户的创建由服务器的 LanMan.ini 文件中的多个参数控制。

如果新添加的用户已作为系统用户存在，则会忽略 USER_INFO_1 结构的 usri1_home_dir 成员。

调用 NetUserAdd 函数并指定信息级别 1 时，调用会将 USER_INFO_2、 USER_INFO_3和 USER_INFO_4 结构中的其他成员初始化为其默认值。可以通过对 NetUserSetInfo 函数进行后续调用来更改默认值。下面列出了提供的默认值。 (前缀 usriX 指示成员可以以多个前缀开头，例如，usri2_或 usri4_.)

成员	默认值
usriX_auth_flags	无 (0)
usriX_full_name	无 (null 字符串)
usriX_usr_comment	无 (null 字符串)
usriX_parms	无 (null 字符串)
usriX_workstations	所有 (null 字符串)
usriX_acct_expires	从不 (TIMEQ_FOREVER)
usriX_max_storage	无限制 (USER_MAXSTORAGE_UNLIMITED)
usriX_logon_hours	允许随时登录 (每个元素0xFF;所有位设置为 1)
usriX_logon_server	任何域控制器 (\\*)
usriX_country_code	0
usriX_code_page	0

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

示例

下面的代码示例演示如何使用调用 NetUserAdd 函数添加用户帐户并分配特权级别。该代码示例填充 USER_INFO_1 结构的成员，并调用 NetUserAdd，并指定信息级别 1。

#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[])
{
   USER_INFO_1 ui;
   DWORD dwLevel = 1;
   DWORD dwError = 0;
   NET_API_STATUS nStatus;

   if (argc != 3)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
      exit(1);
   }
   //
   // Set up the USER_INFO_1 structure.
   //  USER_PRIV_USER: name identifies a user, 
   //    rather than an administrator or a guest.
   //  UF_SCRIPT: required 
   //
   ui.usri1_name = argv[2];
   ui.usri1_password = argv[2];
   ui.usri1_priv = USER_PRIV_USER;
   ui.usri1_home_dir = NULL;
   ui.usri1_comment = NULL;
   ui.usri1_flags = UF_SCRIPT;
   ui.usri1_script_path = NULL;
   //
   // Call the NetUserAdd function, specifying level 1.
   //
   nStatus = NetUserAdd(argv[1],
                        dwLevel,
                        (LPBYTE)&ui,
                        &dwError);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"User %s has been successfully added on %s\n",
               argv[2], argv[1]);
   //
   // 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