LogonUserA 函式 （winbase.h）
LogonUser 函式會嘗試將使用者登入本機電腦。 本機電腦是呼叫 LogonUser 的電腦。 您無法使用 LogonUser 登入遠端電腦。 您可以使用使用者名稱和網域來指定使用者，以 純文字 密碼來 驗證使用者。 如果函式成功，您會收到代表登入使用者的令牌句柄。 然後，您可以使用此令牌句柄模擬指定的使用者，或在大多數情況下，建立 進程 在指定使用者的內容中執行。
語法
BOOL LogonUserA(
[in] LPCSTR lpszUsername,
[in, optional] LPCSTR lpszDomain,
[in, optional] LPCSTR lpszPassword,
[in] DWORD dwLogonType,
[in] DWORD dwLogonProvider,
[out] PHANDLE phToken
);
參數
[in] lpszUsername
指定用戶名稱之 Null 終止字串的指標。 這是要登入的用戶帳戶名稱。 如果您使用 用戶主體名稱 （UPN） 格式，USER@DNSDomainName，lpszDomain 參數必須 NULL。
[in, optional] lpszDomain
null 終止字串的指標，指定帳戶資料庫包含 lpszUsername 帳戶之網域或伺服器的名稱。 如果此參數 NULL，則必須以 UPN 格式指定使用者名稱。 如果此參數為 “.”，函式只會使用本機帳戶資料庫來驗證帳戶。
[in, optional] lpszPassword
null 終止字串的指標，指定 lpszUsername所指定使用者帳戶的純文本密碼。 當您完成使用密碼時，請呼叫 SecureZeroMemory 函式，從記憶體清除密碼。 如需保護密碼的詳細資訊，請參閱 處理密碼。
[in] dwLogonType
要執行的登入作業類型。 此參數可以是Winbase.h中定義的下列其中一個值。
| 價值 | 意義 |
|---|---|
|
此登入類型適用於批次伺服器，其中進程可能會代表用戶執行，而不需要直接介入。 此類型也適用於一次處理許多純文本驗證嘗試的高效能伺服器，例如郵件或網頁伺服器。 |
|
此登入類型適用於會以互動方式使用計算機的使用者，例如 終端機 伺服器、遠端殼層或類似程式登入的使用者。 此登入類型有快取已中斷連線作業之登入資訊的額外費用;因此，某些用戶端/伺服器應用程式不合適，例如郵件伺服器。 |
|
此登入類型適用於高效能伺服器，以驗證純文本密碼。 LogonUser 函式不會快取此登入類型的認證。 |
|
此登入類型會在 驗證套件中保留名稱和密碼，這可讓伺服器在模擬用戶端時連線到其他網路伺服器。 伺服器可以接受來自用戶端的純文本認證、呼叫 LogonUser、確認使用者可以透過網路存取系統，並且仍與其他伺服器通訊。 |
|
此登入類型可讓呼叫端複製其目前的令牌，並指定輸出連線的新認證。 新的登入會話具有相同的本機標識符，但會針對其他網路連線使用不同的認證。
只有LOGON32_PROVIDER_WINNT50登入提供者才支援此登入類型。 注意：自 2023 年 1 月起，無法搭配群組受管理的服務帳戶 （gMSA） 使用LOGON32_LOGON_NEW_CREDENTIALS登入類型。 |
|
表示服務類型的登入。 提供的帳戶必須啟用服務許可權。 |
|
不再支援 GINA。
Windows Server 2003 和 Windows XP：此登入類型適用於以互動方式使用電腦登入使用者的 GINA DLL。 此登入類型可以產生唯一的稽核記錄，顯示工作站解除鎖定時。 |
[in] dwLogonProvider
指定登入提供者。 此參數可以是下列其中一個值。
| 價值 | 意義 |
|---|---|
|
使用系統的標準登入提供者。 默認 安全性提供者 為交涉，除非您傳遞功能變數名稱 NULL，且用戶名稱不是 UPN 格式。 在此情況下，預設提供者為NTLM。 |
|
使用交涉登入提供者。 |
|
使用 NTLM 登入提供者。 |
[out] phToken
句柄變數的指標，接收代表指定之使用者的令牌句柄。
您可以在呼叫 impersonateLoggedOnUser 函式時，使用傳回的句柄。
在大部分情況下，傳回的句柄是 主要令牌，可用於呼叫 createProcessAsUser 函式。 不過，如果您指定LOGON32_LOGON_NETWORK旗標，
當您不再需要此句柄時，請呼叫 CloseHandle 函式加以關閉。
傳回值
如果函式成功，函式會傳回非零。
如果函式失敗，則會傳回零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
言論
LOGON32_LOGON_NETWORK登入類型最快，但有下列限制：
- 函式會傳回 模擬令牌，而不是主要令牌。 您無法直接在 createProcessAsUser 函式
使用此令牌。 不過，您可以呼叫 DuplicateTokenEx 函式，將令牌轉換成主要令牌，然後在 createProcessAsUser使用它。 - 如果您將令牌轉換成主要令牌，並在 createProcessAsUser
使用它來啟動進程，則新進程無法透過重新導向器存取其他網路資源，例如遠端伺服器或印表機。 例外狀況是，如果網路資源不受訪問控制，則新進程將能夠存取它。
除非您登入 Passport 帳戶，否則此函式不需要SE_TCB_NAME許可權。
lpszUsername所指定的帳戶必須具有必要的帳戶許可權。 例如，若要以LOGON32_LOGON_INTERACTIVE旗標登入使用者，使用者（或使用者所屬的群組）必須擁有SE_INTERACTIVE_LOGON_NAME帳戶許可權。 如需影響各種登入作業的帳戶許可權清單，請參閱 帳戶許可權常數。
如果至少有一個令牌存在，則會將用戶視為登入。 如果您呼叫 CreateProcessAsUser，然後關閉令牌，系統會將使用者視為仍在登入，直到進程（以及所有子進程）結束為止。
如果 LogonUser 呼叫成功，系統會透過呼叫提供者的 NPLogonNotify 進入點函式來通知網路提供者登入。
例子
您可以使用下列程式代碼來產生LocalService令牌。
LogonUser(L"LocalService", L"NT AUTHORITY", NULL, LOGON32_LOGON_SERVICE, LOGON32_PROVIDER_DEFAULT, &hToken)
注意
winbase.h 標頭會將 LogonUser 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 支援的最低伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | winbase.h （包括 Windows.h） |
| 連結庫 | Advapi32.lib |
| DLL | Advapi32.dll |