共用方式為

WNetAddConnection2A 函式 (winnetwk.h)

  • 發行項

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

WNetAddConnection2函式會取代WNetAddConnection函式。 如果您可以將控制碼傳遞給網路資源提供者可作為對話方塊擁有者視窗的視窗，請改為呼叫 WNetAddConnection3 函式。

語法

DWORD WNetAddConnection2A(
  [in] LPNETRESOURCEA lpNetResource,
  [in] LPCSTR         lpPassword,
  [in] LPCSTR         lpUserName,
  [in] DWORD          dwFlags
);

參數

[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，作業系統會嘗試只連線到具名網路提供者。

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

WNetAddConnection2函式會忽略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

一組連線選項。 連線選項的可能值定義于 Winnetwk.h 標頭檔中。 目前可以使用下列值。

值 意義
CONNECT_UPDATE_PROFILE
0x00000001
 應該記住網路資源連線。

如果設定此位旗標，作業系統會在使用者登入時自動嘗試還原連線。

作業系統只會記住重新導向本機裝置的成功連線。 它不會記住不成功或無裝置連線的連線。 (當 lpLocalName 成員為 Null 或指向空字串時，就會發生無裝置連線。)

如果此位旗標清楚，則作業系統不會嘗試在使用者登入時還原連線。
CONNECT_UPDATE_RECENT
0x00000002
 網路資源連線不應放在最近的連線清單中。

如果設定此旗標並成功新增連線，則只有在有與其相關聯的重新導向本機裝置時，才會將網路資源連線放入最近的連線清單中。
CONNECT_TEMPORARY
0x00000004
 不應記住網路資源連線。

如果設定此旗標，當使用者再次登入時，作業系統將不會嘗試還原連線。
CONNECT_INTERACTIVE
0x00000008
 如果設定此旗標，作業系統可能會與使用者互動以進行驗證。
CONNECT_PROMPT
0x00000010
 此旗標會指示系統不要對使用者名稱或密碼使用任何預設設定，而不讓使用者有機會提供替代專案。 除非同時設定CONNECT_INTERACTIVE，否則會忽略此旗標。
CONNECT_REDIRECT
0x00000080
 此旗標會在進行連線時強制重新導向本機裝置。

如果NETRESOURCE的lpLocalName成員指定要重新導向的本機裝置，則此旗標沒有任何作用，因為作業系統仍會嘗試重新導向指定的裝置。 當作業系統自動選擇本機裝置時， dwType 成員不得等於RESOURCETYPE_ANY。

如果未設定此旗標，只有在網路需要重新導向本機裝置時，才會自動選擇本機裝置以進行重新導向。

Windows Server 2003 和 Windows XP： 當系統自動指派網路磁碟機號時，字母會從 Z：開始指派，然後 Y：，並以 C：結尾。 這可減少每一登錄磁碟機號 (之間的衝突，例如網路磁碟機號) 和全域磁碟機號 (，例如磁片磁碟機) 。 請注意，舊版 Windows 指派的磁碟機號以 C： 開頭，結尾為 Z：。
CONNECT_CURRENT_MEDIA
0x00000200
 如果設定此旗標，則作業系統不會開始使用新的媒體來嘗試建立連線， (起始新的撥號連線，例如) 。
CONNECT_COMMANDLINE
0x00000800
 如果設定此旗標，作業系統會提示使用者使用命令列進行驗證，而不是使用圖形化使用者介面 (GUI) 。 除非同時設定CONNECT_INTERACTIVE，否則會忽略此旗標。

Windowsxp： Windows XP 和更新版本支援此值。
CONNECT_CMD_SAVECRED
0x00001000
 如果已設定此旗標，而且作業系統會提示輸入認證，則認證應該由認證管理員儲存。 如果已停用呼叫端登入會話的認證管理員，或網路提供者不支援儲存認證，則會忽略此旗標。 除非同時設定CONNECT_INTERACTIVE，否則會忽略此旗標。 除非您設定CONNECT_COMMANDLINE旗標，否則也會忽略此旗標。

Windowsxp： Windows XP 和更新版本支援此值。
CONNECT_CRED_RESET
0x00002000
 如果設定此旗標，且作業系統提示輸入認證，認證管理員就會重設認證。 如果已停用呼叫端登入會話的認證管理員，或網路提供者不支援儲存認證，則會忽略此旗標。 除非您設定CONNECT_COMMANDLINE旗標，否則也會忽略此旗標。

Windows Vista： Windows Vista 和更新版本支援此值。

傳回值

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

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

傳回碼 描述
ERROR_ACCESS_DENIED
 呼叫端無法存取網路資源。
ERROR_ALREADY_ASSIGNED
 由 lpLocalName成員指定的本機裝置已連線到網路資源。
ERROR_BAD_DEV_TYPE
 本機裝置的類型和網路資源類型不相符。
ERROR_BAD_DEVICE
 指定的裝置名稱無效。 如果lpNetResource參數指向之NETRESOURCE結構的lpLocalName成員指定無法重新導向的裝置，就會傳回此錯誤。
ERROR_BAD_NET_NAME
 找不到網路名稱。 如果lpNetResource參數所指向之 NETRESOURCE結構的lpRemoteName成員指定了無法接受給任何網路資源提供者的資源，則傳回這個值，可能是因為資源名稱是空的、不正確，或因為無法找到具名資源。
ERROR_BAD_PROFILE
 使用者設定檔的格式不正確。
ERROR_BAD_PROVIDER
 指定的網路提供者名稱無效。 如果lpNetResource參數指向之NETRESOURCE結構的lpProvider成員指定的值不符合任何網路提供者，就會傳回此錯誤。
ERROR_BAD_USERNAME
 指定的使用者名稱無效。
ERROR_BUSY
 路由器或提供者忙碌中，可能正在初始化。 呼叫端應該重試。
ERROR_CANCELLED
 使用者透過其中一個網路資源提供者的對話方塊，或由呼叫的資源取消連線的嘗試。
ERROR_CANNOT_OPEN_PROFILE
 系統無法開啟使用者設定檔來處理持續性連線。
ERROR_DEVICE_ALREADY_REMEMBERED
 本機裝置名稱具有另一個網路資源的記住連線。 如果lpNetResource參數所指向之 NETRESOURCE結構之 lpLocalName成員所指定的裝置專案指定了與lpNetResource參數所指定之不同連線的使用者設定檔中已經有的值，就會傳回此錯誤。
ERROR_EXTENDED_ERROR
 發生網路特定錯誤。 呼叫 WNetGetLastError 函 式以取得錯誤的描述。
ERROR_INVALID_ADDRESS
 嘗試存取不正確位址。 如果dwFlags參數指定CONNECT_REDIRECT值，但未指定 lpNetResource參數所指向之 NETRESOURCE結構的lpLocalName成員，就會傳回此錯誤。
ERROR_INVALID_PARAMETER
 參數不正確。 如果lpNetResource參數指向的NETRESOURCE結構的dwType成員指定RESOURCETYPE_DISK、RESOURCETYPE_PRINT或RESOURCETYPE_ANY以外的值，就會傳回此錯誤。 如果 dwFlags 參數指定不正確的或未知的值，也會傳回此錯誤。
ERROR_INVALID_PASSWORD
 指定的密碼無效，且未設定CONNECT_INTERACTIVE旗標。
ERROR_LOGON_FAILURE
 登入失敗，因為使用者名稱不明或密碼不正確。
ERROR_NO_NET_OR_BAD_PATH
 沒有網路提供者接受指定的網路路徑。 如果沒有網路提供者辨識lpResource參數所指向之 NETRESOURCE結構的lpRemoteName成員，就會傳回此錯誤。
ERROR_NO_NETWORK
 網路無法使用。
其他
 使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

在 Windows Server 2003 和 Windows XP 上，WNet 函式會在與登入會話相關聯的 MS-DOS 裝置命名空間中建立和刪除網路磁碟機號，因為驗證識別碼 (
與登入會話相關聯的本機唯一識別碼或 LUID。) 這可能會影響呼叫其中一個 WNet 函式的應用程式，以在一個使用者登入下建立網路磁碟機號，但在不同的使用者登入下查詢現有的網路磁碟機號。 這種情況的範例可能是當使用者的第二次登入是在登入會話內建立時，例如呼叫 CreateProcessAsUser 函式，而第二次登入會執行呼叫 GetLogicalDrives 函 式的應用程式。 對 GetLogicalDrives 函式的呼叫不會傳回第一次登入下 WNet 函數呼叫所建立的網路磁碟機號。 請注意，在上述範例中，第一個登入會話仍然存在，而且此範例可以套用至任何登入會話，包括終端機服務會話。 如需詳細資訊，請參閱 定義 MS-DOS 裝置名稱。

在 Windows Server 2003 和 Windows XP 上，如果以 LocalSystem 身分執行的服務呼叫 WNetAddConnection2 函式，則所有使用者登入會話都會看到對應的磁片磁碟機。

對於 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中指定的明確使用者認證呼叫WNetAddConnection2函式，以在特定伺服器上建立與網路資源的連線，然後使用上述其中一個參數再次呼叫作為Null (，以使用預設使用者名稱或預設密碼) 至相同的伺服器，則呼叫 會失敗。 傳回的錯誤將會 ERROR_BAD_USERNAME 或 ERROR_INVALID_PASSWORD。

範例

下列程式碼範例說明如何使用 WNetAddConnection2 函式來連線到網路資源。

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")

#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>

// Need to link with Netapi32.lib and Mpr.lib

int wmain(int argc, wchar_t * argv[])
{

    DWORD dwRetVal;

    NETRESOURCE nr;
    DWORD dwFlags;

    if (argc != 5) {
        wprintf(L"Usage: %s <localname> <remotename> <username> <password>\n",
                argv[0]);
        wprintf(L"       %s X: \\\\contoso\\public testuser testpasswd\n",
                argv[0]);
        exit(1);
    }

    wprintf(L"Calling WNetAddConnection2 with\n");
    wprintf(L"  lpLocalName = %s\n", argv[1]);
    wprintf(L"  lpRemoteName = %s\n", argv[2]);
    wprintf(L"  lpUsername = %s\n", argv[3]);
    wprintf(L"  lpPassword = %s\n", argv[4]);

// Zero out the NETRESOURCE struct
    memset(&nr, 0, sizeof (NETRESOURCE));

// Assign our values to the NETRESOURCE structure.

    nr.dwType = RESOURCETYPE_ANY;
    nr.lpLocalName = argv[1];
    nr.lpRemoteName = argv[2];
    nr.lpProvider = NULL;

// Assign a value to the connection options
    dwFlags = CONNECT_UPDATE_PROFILE;
//
// Call the WNetAddConnection2 function to assign
//   a drive letter to the share.
//
    dwRetVal = WNetAddConnection2(&nr, argv[4], argv[3], dwFlags);
//
// If the call succeeds, inform the user; otherwise,
//  print the error.
//
    if (dwRetVal == NO_ERROR)
        wprintf(L"Connection added to %s\n", nr.lpRemoteName);
    else
        wprintf(L"WNetAddConnection2 failed with error: %u\n", dwRetVal);

    exit(1); 
}

如需說明如何使用 WNetAddConnection2 函式連線至網路資源的其他程式碼範例，請參閱 新增網路連線 並將 磁片磁碟機指派給共用。

注意

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

規格需求

   
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 winnetwk.h
程式庫 Mpr.lib
Dll Mpr.dll

另請參閱

NETRESOURCE

WNetAddConnection3

WNetCancelConnection2

WNetGetConnection

Windows 網路 (WNet) 概觀

Windows 網路功能