WNetAddConnection3W 函式 (winnetwk.h)

發行項
03/08/2023

WNetAddConnection3函式會連線到網路資源。函式可以將本機裝置重新導向至網路資源。

WNetAddConnection3函式類似于WNetAddConnection2函式。主要差異在於 WNetAddConnection3 具有額外的參數，這是網路資源提供者可用來作為對話方塊擁有者視窗的視窗控制碼。 WNetAddConnection2函式和WNetAddConnection3函式會取代WNetAddConnection函式。

語法

DWORD WNetAddConnection3W(
  [in] HWND           hwndOwner,
  [in] LPNETRESOURCEW lpNetResource,
  [in] LPCWSTR        lpPassword,
  [in] LPCWSTR        lpUserName,
  [in] DWORD          dwFlags
);

參數

[in] hwndOwner

網路資源的提供者可以做為對話方塊擁有者視窗的視窗控制碼。如果您在 dwFlags 參數中設定CONNECT_INTERACTIVE值，請使用此參數。

hwndOwner參數可以是Null。如果是， 對 WNetAddConnection3 的呼叫相當於呼叫 WNetAddConnection2 函式。

[in] lpNetResource

NETRESOURCE結構的指標，指定建議連線的詳細資料，例如網路資源、本機裝置和網路資源提供者的相關資訊。

您必須指定 NETRESOURCE 結構的下列成員。

成員	意義
dwType	要連線的網路資源類型。如果 lpLocalName 成員指向無空字串，此成員可以等於RESOURCETYPE_DISK或RESOURCETYPE_PRINT。如果 lpLocalName 為 Null，或指向空字串， dwType 可以等於RESOURCETYPE_DISK、RESOURCETYPE_PRINT或RESOURCETYPE_ANY。雖然需要此成員，但網路服務提供者可能會忽略其資訊。
lpLocalName	Null終止字串的指標，指定要重新導向的本機裝置名稱，例如「F：」或「LPT1」。字串會以不區分大小寫的方式處理。如果字串是空的，或 lpLocalName 為 Null，則函式會建立與網路資源的連線，而不需重新導向本機裝置。
lpRemoteName	指定要連線之網路資源的 Null終止字串指標。字串長度最多可以MAX_PATH個字元，而且必須遵循網路提供者的命名慣例。
lpProvider	指定要連線之網路提供者之 Null終止字串的指標。如果 lpProvider 為 Null，或指向空字串，作業系統會嘗試剖析 lpRemoteName 成員指向的字串，以判斷正確的提供者。如果這個成員不是 Null，則作業系統只會嘗試與具名網路提供者建立連線。只有在您知道要使用哪一個網路提供者時，才應該設定此成員。否則，讓作業系統判斷網路名稱對應的網路提供者。

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	如果設定此旗標，作業系統可能會與使用者互動以進行驗證。
CONNECT_PROMPT	此旗標會指示系統不要對使用者名稱或密碼使用任何預設設定，而不需要提供使用者提供替代選項的機會。除非同時設定CONNECT_INTERACTIVE，否則會忽略此旗標。
CONNECT_REDIRECT	此旗標會在進行連線時強制重新導向本機裝置。如果NETRESOURCE的lpLocalName成員指定要重新導向的本機裝置，此旗標就不會有任何作用，因為作業系統仍會嘗試重新導向指定的裝置。當作業系統自動選擇本機裝置時， dwType 成員不得等於RESOURCETYPE_ANY。如果未設定此旗標，只有在網路需要重新導向本機裝置時，才會自動選擇本機裝置進行重新導向。 Windows Server 2003 和 Windows XP：當系統自動指派網路磁碟機號時，會從 Z：開始指派字母，然後 Y：，並以 C：結尾。這樣可減少每一登錄磁碟機號 (之間的衝突，例如網路磁碟機號) 和全域磁碟機號 (，例如磁片磁碟機) 。請注意，舊版 Windows 指派的磁碟機號以 C：開頭，結尾為 Z：。
CONNECT_UPDATE_PROFILE	應記住網路資源連線。如果設定此位旗標，作業系統會在使用者登入時自動嘗試還原連線。作業系統只會記住重新導向本機裝置的成功連線。它不會記住不成功或無裝置連線的連線。 (當 lpLocalName 成員為 Null 或指向空字串時，就會發生無裝置連線。) 如果清除此位旗標，作業系統不會在登入時自動還原連線。
CONNECT_COMMANDLINE	如果設定此旗標，作業系統會提示使用者使用命令列進行驗證，而不是圖形化使用者介面， (GUI) 。除非同時設定CONNECT_INTERACTIVE，否則會忽略此旗標。 Windows 2000/NT 和 Windows Me/98/95：不支援此值。
CONNECT_CMD_SAVECRED	如果已設定此旗標，而且作業系統會提示輸入認證，則認證應該由認證管理員儲存。如果呼叫端的登入會話停用認證管理員，或網路提供者不支援儲存認證，則會忽略此旗標。除非您設定CONNECT_COMMANDLINE旗標，否則也會忽略此旗標。 Windows 2000/NT 和 Windows Me/98/95：不支援此值。

傳回值

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

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

傳回碼	描述
ERROR_ACCESS_DENIED	呼叫端無法存取網路資源。
ERROR_ALREADY_ASSIGNED	lpLocalName成員指定的本機裝置已連線到網路資源。
ERROR_BAD_DEV_TYPE	本機裝置的類型和網路資源類型不符。
ERROR_BAD_DEVICE	lpLocalName所指定的值無效。
ERROR_BAD_NET_NAME	lpRemoteName成員指定的值無法接受給任何網路資源提供者，可能是因為資源名稱無效，或因為無法找到具名資源。
ERROR_BAD_PROFILE	使用者設定檔的格式不正確。
ERROR_BAD_PROVIDER	lpProvider成員指定的值不符合任何提供者。
ERROR_BUSY	路由器或提供者忙碌中，可能正在初始化。呼叫端應該重試。
ERROR_CANCELLED	使用者透過其中一個網路資源提供者的對話方塊，或由呼叫的資源取消連線的嘗試。
ERROR_CANNOT_OPEN_PROFILE	系統無法開啟使用者設定檔來處理持續性連線。
ERROR_DEVICE_ALREADY_REMEMBERED	lpLocalName成員所指定的裝置專案已在使用者設定檔中。
ERROR_EXTENDED_ERROR	發生網路特定錯誤。呼叫 WNetGetLastError 函式以取得錯誤的描述。
ERROR_INVALID_PASSWORD	指定的密碼無效，且未設定CONNECT_INTERACTIVE旗標。
ERROR_NO_NET_OR_BAD_PATH	無法執行作業，因為網路元件未啟動或無法使用指定的名稱。
ERROR_NO_NETWORK	網路無法使用。

備註

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