NetUserSetInfo 函数 (lmaccess.h)

项目
08/24/2023

NetUserSetInfo 函数设置用户帐户的参数。

语法

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

参数

[in] servername

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

[in] username

指向常量字符串的指针，该常量字符串指定要为其设置信息的用户帐户的名称。有关更多信息，请参见下面的“备注”部分。

[in] level

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

值	含义
0	制定用户帐户名称。 buf 参数指向USER_INFO_0结构。使用此结构可以指定新的组名称。有关更多信息，请参见下面的“备注”部分。
1	指定有关用户帐户的详细信息。 buf 参数指向USER_INFO_1结构。
2	指定有关用户帐户的第一级信息和附加属性。 buf 参数指向USER_INFO_2结构。
3	指定有关用户帐户的二级信息和附加属性。此级别仅在服务器上有效。 buf 参数指向USER_INFO_3结构。请注意，建议改用 USER_INFO_4 。
4	指定有关用户帐户的二级信息和附加属性。此级别仅在服务器上有效。 buf 参数指向USER_INFO_4结构。
21	指定单向加密 LAN 管理器 2。x 兼容密码。 buf 参数指向 USER_INFO_21 结构。
22	指定有关用户帐户的详细信息。 buf 参数指向USER_INFO_22结构。
1003	指定用户密码。 buf 参数指向USER_INFO_1003结构。
1005	指定用户特权级别。 buf 参数指向USER_INFO_1005结构。
1006	指定用户的主目录的路径。 buf 参数指向USER_INFO_1006结构。
1007	指定要与用户帐户关联的注释。 buf 参数指向USER_INFO_1007结构。
1008	指定用户帐户属性。 buf 参数指向USER_INFO_1008结构。
1009	指定用户的登录脚本文件的路径。 buf 参数指向USER_INFO_1009结构。
1010	指定用户的操作员特权。 buf 参数指向USER_INFO_1010结构。
1011	指定用户的全名。 buf 参数指向USER_INFO_1011结构。
1012	指定要与用户关联的注释。 buf 参数指向USER_INFO_1012结构。
1014	指定用户可以从中登录的工作站的名称。 buf 参数指向USER_INFO_1014结构。
1017	指定用户帐户过期的时间。 buf 参数指向USER_INFO_1017结构。
1020	指定用户可以登录的时间。 buf 参数指向USER_INFO_1020结构。
1024	指定用户的国家/地区代码。 buf 参数指向USER_INFO_1024结构。
1051	指定表示已注册用户的全局组的相对标识符。 buf 参数指向USER_INFO_1051结构。
1052	指定网络用户配置文件的路径。 buf 参数指向USER_INFO_1052结构。
1053	指定分配给用户主目录的驱动器号。 buf 参数指向USER_INFO_1053结构。

[in] buf

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

[out] parm_err

指向一个值的指针，该值接收导致ERROR_INVALID_PARAMETER的用户信息结构的第一个成员的索引。如果此参数为 NULL，则错误时不会返回索引。有关更多信息，请参见下面的“备注”部分。

返回值

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

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

返回代码	说明
ERROR_ACCESS_DENIED	用户无权访问请求的信息。
ERROR_INVALID_PARAMETER	其中一个函数参数无效。有关更多信息，请参见下面的“备注”部分。
NERR_InvalidComputer	计算机名称无效。
NERR_NotPrimary	仅允许在域的主域控制器上执行此操作。
NERR_SpeGroupOp	不允许对指定的特殊组（用户组、管理员组、本地组或来宾组）执行该操作。
NERR_LastAdmin	不允许在最后一个管理帐户上执行此操作。
NERR_BadPassword	共享名称或密码无效。
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.)（密码过短。（密码也可能过长、在其更改历史记录中过新、未包含足够的独特字符或者未符合另一项密码策略的要求。））
NERR_UserNotFound	找不到用户名。

注解

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

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

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

只有具有管理权限的用户或应用程序才能调用 NetUserSetInfo 函数来更改用户的密码。当管理员调用 NetUserSetInfo 时，应用的唯一限制是新密码长度必须与系统模式一致。知道用户当前密码的用户或应用程序可以调用 NetUserChangePassword 函数来更改密码。有关调用需要管理员权限的函数的详细信息，请参阅使用特殊特权运行。

管理员本地组的成员可以设置任何可修改的用户帐户元素。所有用户 都可以为自己的 帐户设置 USER_INFO_2 结构 (的usri2_country_code 成员和 USER_INFO_1024结构) 的 usri1024_country_code 成员。

帐户操作员本地组的成员无法为管理员类帐户设置详细信息、授予现有帐户管理员权限或更改任何帐户的操作员权限。如果尝试更改特权级别或禁用安全数据库中最后一个具有管理员权限的帐户， (安全帐户管理器 (SAM) 数据库;如果是域控制器，则 Active Directory ) ，NetUserSetInfo 函数将失败并返回NERR_LastAdmin。

若要设置以下用户帐户控制标志，需要以下权限和控制访问权限。

帐户控制标志	需要权限或权限
UF_TRUSTED_TO_AUTHENTICATE_FOR_DELEGATION	SeEnableDelegationPrivilege 特权，默认情况下授予管理员。
UF_TRUSTED_FOR_DELEGATION	SeEnableDelegationPrivilege。
UF_PASSWD_NOTREQD	“不需要更新密码”控制对域对象的访问权限，默认情况下授予经过身份验证的用户。
UF_DONT_EXPIRE_PASSWD	“取消过期密码”控制对域对象的访问权限，默认情况下授予经过身份验证的用户。
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED	“启用每个用户可逆加密的密码”控制对域对象的访问权限，默认情况下授予经过身份验证的用户。
UF_SERVER_TRUST_ACCOUNT	“在域中添加/删除副本 (replica) ”控制对域对象的访问权限，默认情况下授予管理员。

有关特权常量的列表，请参阅授权常量。

为帐户指定新名称的正确方法是使用 USER_INFO_0 调用 NetUserSetInfo，并使用 usri0_name 成员指定新值。如果使用其他信息级别调用 NetUserSetInfo 并使用 usriX_name 成员指定值，则会忽略该值。

请注意，对 NetUserSetInfo 的调用只能更改网络服务器创建的用户帐户的主目录。

如果 NetUserSetInfo 函数返回ERROR_INVALID_PARAMETER，则可以使用 parm_err 参数指示用户信息结构的第一个成员无效。 (用户信息结构以 USER_INFO_ 开头，其格式由级别参数指定。) 下表列出了可在 parm_err 参数中返回的值以及出错的相应结构成员。 (前缀 usri*_ 指示成员可以以多个前缀开头，例如，usri10_或 usri1003_.)

值	成员
USER_NAME_PARMNUM	usri*_name
USER_PASSWORD_PARMNUM	usri*_password
USER_PASSWORD_AGE_PARMNUM	usri*_password_age
USER_PRIV_PARMNUM	usri*_priv
USER_HOME_DIR_PARMNUM	usri*_home_dir
USER_COMMENT_PARMNUM	usri*_comment
USER_FLAGS_PARMNUM	usri*_flags
USER_SCRIPT_PATH_PARMNUM	usri*_script_path
USER_AUTH_FLAGS_PARMNUM	usri*_auth_flags
USER_FULL_NAME_PARMNUM	usri*_full_name
USER_USR_COMMENT_PARMNUM	usri*_usr_comment
USER_PARMS_PARMNUM	usri*_parms
USER_WORKSTATIONS_PARMNUM	usri*_workstations
USER_LAST_LOGON_PARMNUM	usri*_last_logon
USER_LAST_LOGOFF_PARMNUM	usri*_last_logoff
USER_ACCT_EXPIRES_PARMNUM	usri*_acct_expires
USER_MAX_STORAGE_PARMNUM	usri*_max_storage
USER_UNITS_PER_WEEK_PARMNUM	usri*_units_per_week
USER_LOGON_HOURS_PARMNUM	usri*_logon_hours
USER_PAD_PW_COUNT_PARMNUM	usri*_bad_pw_count
USER_NUM_LOGONS_PARMNUM	usri*_num_logons
USER_LOGON_SERVER_PARMNUM	usri*_logon_server
USER_COUNTRY_CODE_PARMNUM	usri*_country_code
USER_CODE_PAGE_PARMNUM	usri*_code_page
USER_PRIMARY_GROUP_PARMNUM	usri*_primary_group_id
USER_PROFILE_PARMNUM	usri*_profile
USER_HOME_DIR_DRIVE_PARMNUM	usri*_home_dir_drive

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

NetUserSetInfo 函数无法控制通过网络发送到远程服务器以更改用户密码时如何保护密码参数。这些参数的任何加密都由远程过程调用 (RPC) 机制处理，该机制由提供网络传输的网络重定向程序支持。加密还受本地计算机支持的安全机制和 servername 参数中指定的远程网络服务器支持的安全机制控制。有关使用 Microsoft 网络重定向程序且远程网络服务器运行 Microsoft Windows 时的安全性的更多详细信息，请参阅 MS-RPCE 和 MS-SAMR 的协议文档。

示例

下面的代码示例演示如何通过调用 NetUserSetInfo 函数来禁用用户帐户。代码示例填充 USER_INFO_1008 结构的 usri1008_flags 成员，并指定值UF_ACCOUNTDISABLE。然后，该示例调用 NetUserSetInfo，并将信息级别指定为 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 = 1008;
   USER_INFO_1008 ui;
   NET_API_STATUS nStatus;

   if (argc != 3)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
      exit(1);
   }
   // Fill in the USER_INFO_1008 structure member.
   // UF_SCRIPT: required.
   //
   ui.usri1008_flags = UF_SCRIPT | UF_ACCOUNTDISABLE;
   //
   // Call the NetUserSetInfo function 
   //  to disable the account, specifying level 1008.
   //
   nStatus = NetUserSetInfo(argv[1],
                            argv[2],
                            dwLevel,
                            (LPBYTE)&ui,
                            NULL);
   //
   // Display the result of the call.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"User account %s has been disabled\n", argv[2]);
   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