NetUserSetInfo 函式 (lmaccess.h)

發行項
02/28/2024

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 Manager 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

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

[out] parm_err

值的指標，接收造成ERROR_INVALID_PARAMETER之使用者信息結構之第一個成員的索引。如果此參數為 NULL，則不會在錯誤時傳回索引。如需詳細資訊，請參閱接下來的＜備註＞一節。

傳回值

如果函式成功，傳回值會NERR_Success。

如果函式失敗，傳回值可以是下列其中一個錯誤碼。

傳回碼	Description
ERROR_ACCESS_DENIED	用戶無法存取要求的資訊。
ERROR_INVALID_PARAMETER	其中一個函式參數無效。如需詳細資訊，請參閱接下來的＜備註＞一節。
NERR_InvalidComputer	電腦名稱無效。
NERR_NotPrimary	只有在網域的主要域控制器上才允許此作業。
NERR_SpeGroupOp	指定的特殊群組不允許此作業，這些群組為使用者群組、系統管理員群組、本機群組或來賓群組。
NERR_LastAdmin	最後一個系統管理帳戶不允許此作業。
NERR_BadPassword	共用名稱或密碼無效。
NERR_PasswordTooShort	密碼比必要短。 (密碼可能太長、變更歷程記錄中太晚、沒有足夠的唯一字元，或不符合另一個密碼原則需求。)
NERR_UserNotFound	找不到用戶名稱。

備註

如果您要針對 Active Directory 進行程式設計，您可以呼叫特定 Active Directory 服務介面 (ADSI) 方法來達成相同的功能，方法是呼叫網路管理使用者函式。如需詳細資訊，請參閱 IADsUser 和 IADsComputer。

如果您在執行 Active Directory 的域控制器上呼叫此函式，則會根據安全性實體對象的訪問控制清單 (ACL) ，允許或拒絕存取。預設 ACL 只允許網域管理員和帳戶操作員呼叫此函式。在成員伺服器或工作站上，只有系統管理員和 Power Users 可以呼叫此函式。如需詳細資訊，請參閱網路管理功能的安全性需求。如需 ACL、ACE 和存取令牌的詳細資訊，請參閱存取控制模型。

User 物件的安全性描述元是用來執行此函式的存取檢查。

只有具有系統管理許可權的使用者或應用程式可以呼叫 NetUserSetInfo 函式來變更用戶的密碼。當系統管理員呼叫 NetUserSetInfo 時，唯一套用的限制是新的密碼長度必須與系統強制回應一致。知道使用者目前密碼的使用者或應用程式可以呼叫 NetUserChangePassword 函式來變更密碼。如需呼叫需要系統管理員許可權之函式的詳細資訊，請參閱以特殊許可權執行。

Administrators 本地組的成員可以設定任何可修改的用戶帳戶元素。所有使用者都可以針對自己的帳戶，設定USER_INFO_2結構 (的usri2_country_code成員，以及USER_INFO_1024結構) usri1024_country_code成員。

帳戶操作員的本地組成員無法設定 Administrators 類別帳戶的詳細數據、提供現有的帳戶系統管理員許可權，或變更任何帳戶的操作員許可權。如果您嘗試變更許可權等級，或停用安全性資料庫中具有系統管理員許可權的最後一個帳戶， (安全性帳戶管理員 (SAM) 資料庫，或者，在域控制器的情況下， Active Directory) ，NetUserSetInfo 函式會失敗並傳回NERR_LastAdmin。

若要設定下列用戶帳戶控制旗標，需要下列許可權和控制訪問許可權。

帳戶控制旗標	需要許可權或許可權
UF_TRUSTED_TO_AUTHENTICATE_FOR_DELEGATION	SeEnableDelegationPrivilege 許可權，預設會授與系統管理員。
UF_TRUSTED_FOR_DELEGATION	SeEnableDelegationPrivilege。
UF_PASSWD_NOTREQD	[更新密碼不需要] 控制 Domain 物件上的訪問許可權，預設會授與已驗證的使用者。
UF_DONT_EXPIRE_PASSWD	“Unexpire password” 控制 Domain 物件上的訪問許可權，預設會授與已驗證的使用者。
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED	[啟用每個使用者可反轉加密的密碼] 控制 Domain 物件上的訪問許可權，預設會授與已驗證的使用者。
UF_SERVER_TRUST_ACCOUNT	「在網域中新增/移除複本」控制網域對象的訪問許可權，預設會授與系統管理員。

如需許可權常數的清單，請參閱授權常數。

指定帳戶新名稱的正確方法是使用 USER_INFO_0 呼叫 NetUserSetInfo，並使用 usri0_name 成員指定新值。如果您使用其他資訊層級呼叫 NetUserSetInfo ，並使用 usriX_name 成員指定值，則會忽略此值。

請注意，對 NetUserSetInfo 的呼叫只能針對網路伺服器所建立的使用者帳戶變更主目錄。

如果 NetUserSetInfo 函式傳回ERROR_INVALID_PARAMETER，您可以使用 parm_err 參數來表示使用者信息結構的第一個成員無效。 (使用者資訊結構開頭為 USER_INFO_，且其格式是由 level 參數所指定。) 下表列出可在 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 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	lmaccess.h (包括 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll