NetUserModalsSet 函式 (lmaccess.h)

發行項
03/09/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
);

參數

[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

指定資料的緩衝區指標。此資料的格式取決於 level 參數的值。如需詳細資訊，請參閱網路管理功能緩衝區。

[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_，且其格式是由 level 參數所指定。) 下表列出可在 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_OBSER加值稅ION_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)
程式庫	Netapi32.lib
Dll	Netapi32.dll