WNetAddConnection3A 函式 (winnetwk.h)
WNetAddConnection3 函式會連線到網路資源。 函式可以將本機裝置重新導向至網路資源。
WNetAddConnection3 函式類似於 WNetAddConnection2 函式。 主要差異在於 WNetAddConnection3 有額外的參數，這是網路資源提供者可作為對話框擁有者視窗的視窗句柄。 WNetAddConnection2 函式和 WNetAddConnection3 函式會取代 WNetAddConnection 函式。
語法
DWORD WNetAddConnection3A(
[in] HWND hwndOwner,
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
參數
[in] hwndOwner
視窗的句柄，供網路資源的提供者作為對話框的擁有者視窗使用。 如果您在 dwFlags 參數中設定CONNECT_INTERACTIVE值，請使用此參數。
hwndOwner 參數可以是 NULL。 如果是， 呼叫 WNetAddConnection3 就相當於呼叫 WNetAddConnection2 函式。
[in] lpNetResource
NETRESOURCE 結構的指標，指定建議連線的詳細數據，例如網路資源、本機裝置和網路資源提供者的相關信息。
您必須指定 NETRESOURCE 結構的下列成員。
WNetAddConnection3 函式會忽略 NETRESOURCE 結構的其他成員。
[in] lpPassword
Null 終止字串的指標，指定要用於建立網路連線的密碼。
如果 lpPassword 為 NULL，則函式會使用與 lpUserName 參數所指定使用者相關聯的目前默認密碼。
如果 lpPassword 指向空字串，則函式不會使用密碼。
如果連線因為密碼無效而失敗，而且 dwFlags 參數中已設定CONNECT_INTERACTIVE值，則函式會顯示對話方塊，要求使用者輸入密碼。
Windows Me/98/95： 此參數必須是 NULL 或空字串。
[in] lpUserName
Null 終止字串的指標，指定用於建立連接的用戶名稱。
如果 lpUserName 為 NULL，則函式會使用預設的用戶名稱。 (進程的用戶內容會提供預設的用戶名稱。)
當使用者想要連線到已為其指派使用者名稱或帳戶以外的使用者名稱或帳戶的網路資源時，就會指定 lpUserName 參數。
用戶名稱字串代表 安全性內容。 它可能是網路提供者特有的。
Windows Me/98/95： 此參數必須是 NULL 或空字串。
[in] dwFlags
一組連線選項。 目前已定義下列值。
| 值 | 意義 |
|---|---|
|
如果設定此旗標，操作系統可能會與用戶互動以進行驗證。 |
|
此旗標會指示系統不要對使用者名稱或密碼使用任何預設設定，而不讓用戶有機會提供替代專案。 除非同時設定CONNECT_INTERACTIVE，否則會忽略此旗標。 |
|
此旗標會在進行連線時強制重新導向本機裝置。
如果 NETRESOURCE 的 lpLocalName 成員指定要重新導向的本機裝置，則此旗標沒有任何作用，因為操作系統仍會嘗試重新導向指定的裝置。 當操作系統自動選擇本機裝置時， dwType 成員不得等於RESOURCETYPE_ANY。 如果未設定此旗標，只有在網路需要重新導向本機裝置時，才會自動選擇本機裝置以進行重新導向。 Windows Server 2003 和 Windows XP： 當系統自動指派網路驅動器號時，字母會從 Z：開始指派，然後 Y：，並以 C：結尾。 這可減少每一登錄驅動器號 (之間的衝突，例如網路驅動器號) 和全局驅動器號 (，例如磁碟驅動器) 。 請注意，舊版 Windows 指派的驅動器號以 C： 開頭，結尾為 Z：。 |
|
應該記住網路資源連線。
如果設定此位旗標，操作系統會在使用者登入時自動嘗試還原連線。 操作系統只會記住重新導向本機裝置的成功連線。 它不會記住不成功或無裝置連線的連線。 (當 lpLocalName 成員為 NULL 或指向空字串時，就會發生無裝置連線。) 如果這個位旗標清楚，操作系統不會在登入時自動還原連線。 |
|
如果設定此旗標，操作系統會提示使用者使用命令行進行驗證，而不是使用圖形使用者介面 (GUI) 。 除非同時設定CONNECT_INTERACTIVE，否則會忽略此旗標。
Windows 2000/NT 和 Windows Me/98/95： 不支援這個值。 |
|
如果已設定此旗標，而且操作系統會提示輸入認證，則認證應該由認證管理員儲存。 如果已停用呼叫端登入會話的認證管理員，或網路提供者不支援儲存認證，則會忽略此旗標。 除非您設定CONNECT_COMMANDLINE旗標，否則也會忽略此旗標。
Windows 2000/NT 和 Windows Me/98/95： 不支援這個值。 |
傳回值
如果函式成功，傳回值會NO_ERROR。
如果函式失敗，傳回值是 系統錯誤碼，例如下列其中一個值。
| 傳回碼 | Description |
|---|---|
|
呼叫端無法存取網路資源。 |
|
由 lpLocalName 成員指定的本機裝置已連線到網路資源。 |
|
本機裝置的類型和網路資源類型不相符。 |
|
lpLocalName 指定的值無效。 |
|
任何網路資源提供者都無法接受 lpRemoteName 成員所指定的值，可能是因為資源名稱無效，或因為無法找到具名資源。 |
|
使用者配置檔的格式不正確。 |
|
lpProvider 成員指定的值不符合任何提供者。 |
|
路由器或提供者忙碌中，可能正在初始化。 呼叫端應該重試。 |
|
使用者透過其中一個網路資源提供者的對話框，或由呼叫的資源取消連線的嘗試。 |
|
系統無法開啟使用者配置檔來處理持續性連線。 |
|
lpLocalName 成員所指定的裝置專案已在使用者配置檔中。 |
|
發生網路特定錯誤。 呼叫 WNetGetLastError 函 式以取得錯誤的描述。 |
|
指定的密碼無效，且未設定CONNECT_INTERACTIVE旗標。 |
|
無法執行作業，因為網路元件未啟動或無法使用指定的名稱。 |
|
網路無法使用。 |
備註
WNetUseConnection 函式類似於 WNetAddConnection3 函式。 主要差異在於 WNetUseConnection 可以自動選取未使用的本機裝置，以重新導向至網路資源。
在 Windows Server 2003 和 Windows XP 上，WNet 函式會在與登入會話相關聯的 MS-DOS 裝置命名空間中建立和刪除網路驅動器號，因為驗證標識符 (
與登入會話相關聯的本機唯一標識碼或 LUID。) 這可能會影響呼叫其中一個 WNet 函式的應用程式，以在一個使用者登入下建立網路驅動器號，但在不同的使用者登入下查詢現有的網路驅動器號。 這種情況的範例可能是當使用者的第二次登入是在登入會話內建立時，例如呼叫 CreateProcessAsUser 函式，而第二次登入會執行呼叫 GetLogicalDrives 函 式的應用程式。 對 GetLogicalDrives 函式的呼叫不會傳回第一次登入下 WNet 函數呼叫所建立的網路驅動器號。 請注意，在上述範例中，第一個登入會話仍然存在，而且此範例可以套用至任何登入會話，包括終端機服務會話。 如需詳細資訊，請參閱 定義 MS-DOS 裝置名稱。
在 Windows Server 2003 和 Windows XP 上，如果以 LocalSystem 身分執行的服務呼叫 WNetAddConnection3 函式，則所有使用者登入會話都會看到對應的磁碟驅動器。
對於 Microsoft 網路提供者，lpNetResource 參數所指向之 NETRESOURCE 結構的 lpRemoteName 成員可以包含 dotted-decimal 表示法中的 IPv4 位址。 共用的範例如下：
\192.168.1.1\share
對於 Windows Vista 和更新版本的 Microsoft 網路提供者，lpNetResource 參數所指向之 NETRESOURCE 結構的 lpRemoteName 成員可以包含 IPv6 位址。 不過，必須使用 IPv6 常值格式，才能正確剖析 IPv6 位址。 IPv6 常值位址的格式如下：
以 '：' 字元取代為 '-' 字元的 ipv6-address，後面接著 “.ipv6-literal.net” 字串。
例如，針對下列 IPv6 位址：
2001:4898:9:3:c069:aa97:fe76:2449
共用的範例如下：
\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share
其他網路提供者可支援包含IPv4或IPv6位址的 lpResource 參數所指向之 NETRESOURCE 結構的 lpRemoteName 成員，但這由特定網路提供者決定。
Windows 7 和 Windows Server 2008 R2： 如果使用 pUsername 和 lpPassword 中指定的明確使用者認證來呼叫 WNetAddConnection3 函式，以在特定伺服器上建立與網路資源的連線，然後使用上述其中一個參數再次呼叫，以 NULL (使用預設使用者名稱或默認密碼) 至相同伺服器，則呼叫 會失敗。 傳回的錯誤將會 ERROR_BAD_USERNAME 或 ERROR_INVALID_PASSWORD。
注意
winnetwk.h 標頭會將 WNetAddConnection3 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | winnetwk.h |
| 程式庫 | Mpr.lib |
| Dll | Mpr.dll |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應