WNetUseConnectionA 函式 (winnetwk.h)
WNetUseConnection函式會連線到網路資源。 函式可以將本機裝置重新導向至網路資源。
WNetUseConnection函式類似于WNetAddConnection3函式。 主要差異在於 WNetUseConnection 可以自動選取未使用的本機裝置，以重新導向至網路資源。
語法
DWORD WNetUseConnectionA(
[in] HWND hwndOwner,
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserId,
[in] DWORD dwFlags,
[out] LPSTR lpAccessName,
[in, out] LPDWORD lpBufferSize,
[out] LPDWORD lpResult
);
參數
[in] hwndOwner
處理網路資源提供者可用來作為對話方塊擁有者視窗的視窗。 如果您在 dwFlags 參數中設定CONNECT_INTERACTIVE值，請使用此參數。
[in] lpNetResource
NETRESOURCE結構的指標，指定建議連接的詳細資料。 結構包含網路資源、本機裝置和網路資源提供者的相關資訊。
您必須指定 NETRESOURCE 結構的下列成員。
WNetUseConnection函式會忽略NETRESOURCE結構的其他成員。 如需詳細資訊，請參閱 dwFlags 參數的下列描述。
[in] lpPassword
常數 Null終止字串的指標，指定要用於建立網路連線的密碼。
如果 lpPassword 為 Null，函式會使用與 lpUserID所指定使用者相關聯的目前預設密碼。
如果 lpPassword 指向空字串，則函式不會使用密碼。
如果連線因為密碼無效而失敗，且 在 dwFlags 參數中設定了CONNECT_INTERACTIVE值，則函式會顯示一個對話方塊，要求使用者輸入密碼。
[in] lpUserId
常數 Null終止字串的指標，指定用於建立連接的使用者名稱。
如果 lpUserID 為 Null，函式會使用預設的使用者名稱。 (進程的使用者內容會提供預設的使用者名稱。)
當使用者想要連線到已獲指派預設使用者名稱或帳戶以外的使用者名稱或帳戶的網路資源時，會指定 lpUserID 參數。
使用者名稱字串代表 安全性內容。 它可能專屬於網路提供者。
[in] dwFlags
描述連線的位旗標集。 此參數可以是下列值的任何組合。
| 值 | 意義 |
|---|---|
|
如果設定此旗標，作業系統可能會與使用者互動以進行驗證。 |
|
此旗標會指示系統不要對使用者名稱或密碼使用任何預設設定，而不需要提供使用者提供替代選項的機會。 除非同時設定CONNECT_INTERACTIVE，否則會忽略此旗標。 |
|
此旗標會在進行連線時強制重新導向本機裝置。
如果NETRESOURCE的lpLocalName成員指定要重新導向的本機裝置，此旗標就不會有任何作用，因為作業系統仍會嘗試重新導向指定的裝置。 當作業系統自動選擇本機裝置時， dwType 成員不得等於RESOURCETYPE_ANY。 如果未設定此旗標，只有在網路需要重新導向本機裝置時，才會自動選擇本機裝置進行重新導向。 Windowsxp： 當系統自動指派網路磁碟機號時，會從 Z：開始指派字母，然後 Y：，並以 C： 結尾。 這樣可減少每一登錄磁碟機號 (之間的衝突，例如網路磁碟機號) 和全域磁碟機號 (，例如磁片磁碟機) 。 請注意，舊版指派的磁碟機號開頭為 C： ，並以 Z：結尾。 |
|
此旗標會指示作業系統儲存網路資源連線。
如果設定此位旗標，作業系統會在使用者登入時自動嘗試還原連線。 系統只會記住重新導向本機裝置的成功連線。 它不會記住不成功或無裝置連線的連線。 (當 lpLocalName 為 Null 或指向空字串時，就會發生無裝置連線。) 如果清除此位旗標，作業系統不會在登入時自動還原連線。 |
|
如果設定此旗標，作業系統會提示使用者使用命令列進行驗證，而不是圖形化使用者介面， (GUI) 。 除非同時設定CONNECT_INTERACTIVE，否則會忽略此旗標。
Windows 2000/NT 和 Windows Me/98/95： 不支援此值。 |
|
如果已設定此旗標，而且作業系統會提示輸入認證，則認證應該由認證管理員儲存。 如果呼叫端的登入會話停用認證管理員，或網路提供者不支援儲存認證，則會忽略此旗標。 除非您設定CONNECT_COMMANDLINE旗標，否則也會忽略此旗標。
Windows 2000/NT 和 Windows Me/98/95： 不支援此值。 |
[out] lpAccessName
接收連線上系統要求的緩衝區指標。 此參數可以是 Null。
如果指定此參數，且NETRESOURCE結構的lpLocalName成員會指定本機裝置，則此緩衝區會接收本機裝置名稱。 如果 lpLocalName 未指定裝置，且網路需要本機裝置重新導向，或已設定CONNECT_REDIRECT值，則此緩衝區會接收重新導向本機裝置的名稱。
否則，複製到緩衝區的名稱就是遠端資源的名稱。 如果指定，這個緩衝區必須至少與 lpRemoteName 成員所指向的字串相同。
[in, out] lpBufferSize
指定 字元中 lpAccessName 緩衝區大小的變數指標。 如果呼叫失敗，因為緩衝區不夠大，函式會傳回這個位置中所需的緩衝區大小。 如需詳細資訊，請參閱傳回值一節中的 lpAccessName 參數描述和ERROR_MORE_DATA錯誤碼。
[out] lpResult
接收有關連接之其他資訊的變數指標。 此參數可以是下列值。
| 值 | 意義 |
|---|---|
|
如果已設定此旗標，則會使用本機裝置重新導向進行連線。 如果 lpAccessName 參數指向緩衝區，則會將本機裝置名稱複製到緩衝區。 |
傳回值
如果函式成功，傳回值會NO_ERROR。
如果函式失敗，傳回值是 系統錯誤碼，例如下列其中一個值。
| 傳回碼 | 描述 |
|---|---|
|
呼叫端無法存取網路資源。 |
|
由 lpLocalName成員指定的本機裝置已連線到網路資源。 |
|
lpLocalName指定的值無效。 |
|
任何網路資源提供者都無法接受 由 lpRemoteName 成員指定的值，因為資源名稱無效，或是無法找到具名資源。 |
|
lpProvider成員指定的值不符合任何提供者。 |
|
使用者透過其中一個網路資源提供者的對話方塊，或由呼叫的資源取消連線的嘗試。 |
|
發生網路特定錯誤。 若要取得錯誤的描述，請呼叫 WNetGetLastError 函 式。 |
|
傳入無法存取之緩衝區指標的呼叫端。 |
|
此錯誤是下列其中一個條件的結果：
|
|
指定的密碼無效，且未設定CONNECT_INTERACTIVE旗標。 |
|
lpAccessName緩衝區太小。
如果重新導向本機裝置，緩衝區必須夠大，才能包含本機裝置名稱。 否則，緩衝區必須夠大，才能包含 lpRemoteName所指向的字串，或別名由 lpRemoteName指向的可連接資源名稱。 如果傳回此錯誤，則不會進行任何連線。 |
|
作業系統無法自動選擇本機重新導向，因為所有有效的本機裝置都正在使用中。 |
|
無法完成作業，可能是因為網路元件未啟動，或無法辨識指定的資源名稱。 |
|
網路無法使用。 |
備註
Windows Server 2003 和 Windows XP： WNet 函式會在與登入會話相關聯的 MS-DOS 裝置命名空間中建立和刪除網路磁碟機號，因為驗證識別碼會識別 MS-DOS 裝置。 (AuthenticationID 是與登入會話相關聯的 本機唯一識別碼或 LUID。) 這可能會影響呼叫其中一個 WNet 函式的應用程式，以在一個使用者登入下建立網路磁碟機號，但在不同的使用者登入下查詢現有的網路磁碟機號。 這種情況的範例可能是當使用者的第二次登入是在登入會話內建立時，例如呼叫 CreateProcessAsUser 函式，而第二次登入會執行呼叫 GetLogicalDrives 函 式的應用程式。 GetLogicalDrives 不會傳回第一次登入下 WNet 函式所建立的網路磁碟機號。 請注意，在上述範例中，第一個登入會話仍然存在，而且此範例可以套用至任何登入會話，包括終端機服務會話。 如需詳細資訊，請參閱 定義 MS-DOS 裝置名稱。
注意
winnetwk.h 標頭會將 WNetUseConnection 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | winnetwk.h |
| 程式庫 | Mpr.lib |
| Dll | Mpr.dll |