NetUserAdd 函式 (lmaccess.h)

發行項
02/28/2024

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

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

[out] parm_err

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

傳回值

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

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

傳回碼	Description
ERROR_ACCESS_DENIED	用戶無法存取要求的資訊。
NERR_InvalidComputer	電腦名稱無效。
NERR_NotPrimary	此作業只允許在網域的主要域控制器上執行。
NERR_GroupExists	群組已經存在。
NERR_UserExists	用戶帳戶已經存在。
NERR_PasswordTooShort	密碼比必要短。 (密碼可能太長、變更歷程記錄中太近、沒有足夠唯一字元，或不符合另一個密碼原則需求。)

備註

如果您是針對 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)
程式庫	Netapi32.lib
Dll	Netapi32.dll