共用方式為

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 結構的下列成員。

成員 意義
dwType
 要連線的網路資源類型。

如果 lpLocalName 成員指向無空字串，這個成員可以等於 RESOURCETYPE_DISK 或 RESOURCETYPE_PRINT。

如果 lpLocalName 是 NULL，或指向空字串，dwType 可以等於RESOURCETYPE_DISK、RESOURCETYPE_PRINT或RESOURCETYPE_ANY。

雖然需要此成員，但網路服務提供者可能會忽略其資訊。
lpLocalName
 null終止字串的指標，指定要重新導向的本機裝置名稱，例如 “F：” 或 “LPT1”。 字串會以不區分大小寫的方式處理。

如果字串是空的，或如果 lpLocalNameNULL，則函式會建立與網路資源的連線，而不重新導向本機裝置。
lpRemoteName
 null終止字串的指標，指定要連線的網路資源。 字串長度最多可以MAX_PATH個字元，而且必須遵循網路提供者的命名慣例。
lpProvider
 null終止字串的指標，指定要連線的網路提供者。

如果 lpProviderNULL，或如果它指向空字串，則操作系統會藉由剖析 lpRemoteName 成員所指向的字元串，嘗試判斷正確的提供者。

如果這個成員未 NULL，則操作系統只會嘗試建立與具名網路提供者的連接。

只有當您知道要使用哪個網路提供者時，才應該設定此成員。 否則，讓操作系統判斷網路名稱所對應的網路提供者。
 

WNetAddConnection3 函式會忽略 NETRESOURCE 結構的其他成員。

[in] lpPassword

null終止字串的指標，指定要用於建立網路連線的密碼。

如果 lpPasswordNULL，函式會使用與 lpUserName 參數所指定使用者相關聯的目前默認密碼。

如果 lpPassword 指向空字串，則函式不會使用密碼。

如果連線因為密碼無效而失敗，且CONNECT_INTERACTIVE值是在 dwFlags 參數中設定，函式會顯示對話框，要求使用者輸入密碼。

Windows Me/98/95：此參數必須 NULL 或空字串。

[in] lpUserName

null終止字串的指標，指定用於建立連線的用戶名稱。

如果 lpUserNameNULL，則函式會使用預設的用戶名稱。 （行程的用戶內容會提供預設的用戶名稱。

當使用者想要連線到已獲指派預設使用者名稱或帳戶以外的使用者名稱或帳戶的網路資源時，會指定 lpUserName 參數。

使用者名稱字串代表 安全性內容。 它可能專屬於網路提供者。

Windows Me/98/95：此參數必須 NULL 或空字串。

[in] dwFlags

一組連線選項。 目前已定義下列值。

價值 意義
CONNECT_INTERACTIVE
 如果已設定此旗標，操作系統可能會與用戶互動以進行驗證。
CONNECT_PROMPT
 此旗標會指示系統不要針對使用者名稱或密碼使用任何預設設定，而不需要提供使用者提供替代選項的機會。 除非同時設定CONNECT_INTERACTIVE，否則會忽略此旗標。
CONNECT_REDIRECT
 此旗標會在進行連線時強制重新導向本機裝置。

如果 lpLocalName netRESOURCE 指定要重新導向 的本機裝置，則此旗標沒有任何作用，因為操作系統仍會嘗試重新導向指定的裝置。 當操作系統自動選擇本機裝置時，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 裝置命名空間中建立和刪除網路驅動器號，因為 authenticationID 會識別 MS-DOS 裝置 （a
與登入會話相關聯的本機唯一標識符或 LUID。 這可能會影響呼叫其中一個 WNet 函式的應用程式，以在一個使用者登入下建立網路驅動器號，但在不同使用者登入下查詢現有的網路驅動器號。 例如，藉由呼叫 CreateProcessAsUser 函式，而第二次登入會執行呼叫 getLogicalDrives 函式 GetLogicalDrives 的應用程式，就可能發生這種情況的範例。 對 getLogicalDrives 函式 呼叫的呼叫不會傳回第一次登入下 WNet 函數呼叫所建立的網路驅動器號。 請注意，在上述範例中，第一個登入會話仍然存在，而且此範例可以套用至任何登入會話，包括終端機服務會話。 如需詳細資訊，請參閱 定義 MS-DOS 裝置名稱。

在 Windows Server 2003 和 Windows XP 上，如果以 LocalSystem 執行的服務會呼叫 WNetAddConnection3 函式，則所有使用者登入會話都會看見對應的磁碟驅動器。

針對Microsoft網路提供者，NETRESOURCE 結構 lpRemoteName 成員，lpNetResource 參數可以包含 dotted-decimal 表示法中的 IPv4 位址。 共用的範例如下：

\192.168.1.1\share

針對 Windows Vista 和更新版本上的Microsoft網路提供者，lpRemoteNameNETRESOURCE 結構的成員，lpNetResource 參數所指向的結構可以包含 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 位址的 lpNetResource 參數所指向 NETRESOURCE 結構 lpRemoteName 成員，但這是由特定網路提供者決定。

Windows 7 和 Windows Server 2008 R2：如果呼叫 WNetAddConnection3 函式時，pUsername 中指定的明確用戶認證 和 lpPassword，以在特定伺服器上建立與網路資源的聯機，然後使用下列其中一個參數再次呼叫，作為 NULL（以使用預設使用者名稱或默認密碼）到相同的伺服器， 話叫失敗。 傳回的錯誤將會 ERROR_BAD_USERNAME 或 ERROR_INVALID_PASSWORD。

注意

winnetwk.h 標頭會根據 UNICODE 預處理器常數的定義，將 WNetAddConnection3 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的 慣例。

要求

要求 價值
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器 Windows 2000 Server [僅限傳統型應用程式]
目標平臺 窗戶
標頭 winnetwk.h
連結庫 Mpr.lib
DLL Mpr.dll

另請參閱

NETRESOURCE

WNetAddConnection2

WNetCancelConnection2

WNetGetConnection

WNetUseConnection

Windows 網路功能 （WNet） 概觀

Windows 網路函式