NetUserChangePassword 函式 (lmaccess.h)

發行項
03/05/2024

NetUserChangePassword 函式會變更指定網路伺服器或網域的用戶密碼。

語法

NET_API_STATUS NET_API_FUNCTION NetUserChangePassword(
  [in] LPCWSTR domainname,
  [in] LPCWSTR username,
  [in] LPCWSTR oldpassword,
  [in] LPCWSTR newpassword
);

參數

[in] domainname

常數位串的指標，指定要執行函式之遠端伺服器或網域的 DNS 或 NetBIOS 名稱。如果此參數為 NULL，則會使用呼叫端的登入網域。

[in] username

指定用戶名稱之常數位串的指標。 NetUserChangePassword 函式會變更指定用戶的密碼。

如果此參數為 NULL，則會使用呼叫端的登入名稱。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in] oldpassword

指定用戶舊密碼之常數位符串的指標。

[in] newpassword

指定使用者新密碼之常數位符串的指標。

傳回值

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

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

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

備註

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

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

User 對象的安全性描述項是用來執行此函式的存取檢查。此外，呼叫端必須在User對象上擁有「變更密碼」控制訪問許可權。此許可權預設會授與匿名登錄和所有人。

請注意，若要讓函式成功， oldpassword 參數必須符合目前存在的密碼。

在某些情況下，呼叫 NetUserChangePassword 函式的程式也必須啟用SE_CHANGE_NOTIFY_NAME許可權;否則， NetUserChangePassword 會失敗，而且 GetLastError 會傳回ERROR_ACCESS_DENIED。 LocalSystem 帳戶或屬於系統管理員群組成員的帳戶不需要此許可權。根據預設，所有用戶都會啟用SE_CHANGE_NOTIFY_NAME，但某些系統管理員可能會停用每個人的許可權。如需帳戶許可權的詳細資訊，請參閱許可權和授權常數。

如需示範如何使用 NetUserGetInfo 和 NetUserSetInfo 函式在下次登入時強制使用者變更登入密碼的程式代碼範例，請參閱強制用戶變更登入密碼。

用戶帳戶名稱限製為 20 個字元，且組名限製為 256 個字元。此外，帳戶名稱不能以句號終止，而且不能包含逗號或任何下列可列印字元：“、/、、[、]、：、|、<>+、=、;、?、*。名稱也無法在範圍 1-31 中包含不可列印的字元。

NetUserChangePassword 函式不會控制透過網路傳送至遠端伺服器時，oldpassword 和 newpassword 參數的安全方式。這些參數的任何加密都是由提供網路傳輸的網路重新導向器所支援的 RPC) 機制 (遠端過程調用處理。加密也是由本機計算機所支援的安全性機制，以及 domainname 參數中指定的遠端網路伺服器或網域所支援的安全性機制所控制。如需使用 Microsoft 網路重新導向器且遠端網路伺服器執行 Microsoft Windows 時安全性的詳細資訊，請參閱 MS-RPCE、 MS-SAMR、 MS-SPNG 和 MS-NLMP 的通訊協定檔。

範例

下列程式代碼範例示範如何使用 對 NetUserChangePassword 函式的呼叫來變更使用者的密碼。函式的所有參數都是必要參數。

#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 dwError = 0;
   NET_API_STATUS nStatus;
   //
   // All parameters are required.
   //
   if (argc != 5)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName OldPassword NewPassword\n", argv[0]);
      exit(1);
   }
   //
   // Call the NetUserChangePassword function.
   //
   nStatus = NetUserChangePassword(argv[1], argv[2], argv[3], argv[4]);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"User password has been changed successfully\n");
   //
   // 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