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