NetUserAdd 函式 (lmaccess.h)

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

另請參閱

NetUserDel

NetUserEnum

NetUserSetInfo

網路管理功能

網路管理概觀

USER_INFO_1

USER_INFO_2

USER_INFO_4

使用者函式