NetUserModalsSet 函数 (lmaccess.h)

项目
08/24/2023

NetUserModalsSet 函数为安全数据库中所有用户和全局组设置全局信息，安全数据库中是安全帐户管理器 (SAM) 数据库，如果是域控制器，则为 Active Directory。

语法

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

parameters

[in] servername

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

[in] level

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

值	含义
0	指定全局密码参数。 buf 参数指向USER_MODALS_INFO_0结构。
1	指定登录服务器和域控制器信息。 buf 参数指向USER_MODALS_INFO_1结构。
2	指定域名和标识符。 buf 参数指向USER_MODALS_INFO_2结构。
3	指定锁定信息。 buf 参数指向USER_MODALS_INFO_3结构。
1001	指定允许的最小密码长度。 buf 参数指向USER_MODALS_INFO_1001结构。
1002	指定允许的最大密码期限。 buf 参数指向USER_MODALS_INFO_1002结构。
1003	指定允许的最短密码期限。 buf 参数指向USER_MODALS_INFO_1003结构。
1004	指定强制注销信息。 buf 参数指向USER_MODALS_INFO_1004结构。
1005	指定密码历史记录的长度。 buf 参数指向USER_MODALS_INFO_1005结构。
1006	指定登录服务器的角色。 buf 参数指向USER_MODALS_INFO_1006结构。
1007	指定域控制器信息。 buf 参数指向USER_MODALS_INFO_1007结构。

[in] buf

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

[out] parm_err

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

返回值

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

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

返回代码	说明
ERROR_ACCESS_DENIED	用户无权访问请求的信息。
ERROR_INVALID_PARAMETER	指定的参数无效。有关更多信息，请参见下面的“备注”部分。
NERR_InvalidComputer	计算机名称无效。
NERR_UserNotFound	找不到用户名。

注解

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

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

Domain 对象的安全描述符用于执行此函数的访问检查。通常，调用方必须对整个对象具有写入访问权限，才能成功调用此函数。

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

值	成员
MODALS_MIN_PASSWD_LEN_PARMNUM	usrmod*_min_passwd_len
MODALS_MAX_PASSWD_AGE_PARMNUM	usrmod*_max_passwd_age
MODALS_MIN_PASSWD_AGE_PARMNUM	usrmod*_min_passwd_age
MODALS_FORCE_LOGOFF_PARMNUM	usrmod*_force_logoff
MODALS_PASSWD_HIST_LEN_PARMNUM	usrmod*_password_hist_len
MODALS_ROLE_PARMNUM	usrmod*_role
MODALS_PRIMARY_PARMNUM	usrmod*_primary
MODALS_DOMAIN_NAME_PARMNUM	usrmod*_domain_name
MODALS_DOMAIN_ID_PARMNUM	usrmod*_domain_id
MODALS_LOCKOUT_DURATION_PARMNUM	usrmod*_lockout_duration
MODALS_LOCKOUT_OBSERVATION_WINDOW_PARMNUM	usrmod*_lockout_observation_window
MODALS_LOCKOUT_THRESHOLD_PARMNUM	usrmod*_lockout_threshold

示例

以下代码示例演示如何通过调用 NetUserModalsSet 函数为所有用户和全局组设置全局信息。此示例填充 USER_MODALS_INFO_0 结构的成员，并调用 NetUserModalsSet，指定信息级别 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;
   USER_MODALS_INFO_0 ui;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = (LPTSTR) argv[1];
   //
   // Fill in the USER_MODALS_INFO_0 structure.
   //
   ui.usrmod0_min_passwd_len = 0;
   ui.usrmod0_max_passwd_age = (86400 * 30);
   ui.usrmod0_min_passwd_age = 0;
   ui.usrmod0_force_logoff = TIMEQ_FOREVER; // never force logoff
   ui.usrmod0_password_hist_len = 0;
   //
   // Call the NetUserModalsSet function; specify level 0.
   //
   nStatus = NetUserModalsSet((LPCWSTR) pszServerName,
                              dwLevel,
                              (LPBYTE)&ui,
                              NULL);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"Modals information set successfully on %s\n", 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