WNetGetConnectionA 函式 (winnetwk.h)

發行項
08/27/2023

WNetGetConnection函式會擷取與本機裝置相關聯的網路資源名稱。

語法

DWORD WNetGetConnectionA(
  [in]      LPCSTR  lpLocalName,
  [out]     LPSTR   lpRemoteName,
  [in, out] LPDWORD lpnLength
);

參數

[in] lpLocalName

常數 Null 終止字串的指標，指定要取得網路名稱的本機裝置名稱。

[out] lpRemoteName

以 Null 結尾的字串指標，該字串會接收用來建立連接的遠端名稱。

[in, out] lpnLength

變數的指標，指定 lpRemoteName 參數所指向的緩衝區大小，以字元為單位。如果函式因為緩衝區不夠大而失敗，此參數會傳回所需的緩衝區大小。

傳回值

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

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

傳回碼	描述
ERROR_BAD_DEVICE	lpLocalName參數指向的字串無效。
ERROR_NOT_CONNECTED	lpLocalName指定的裝置不是重新導向的裝置。如需詳細資訊，請參閱接下來的＜備註＞一節。
ERROR_MORE_DATA	緩衝區太小。 lpnLength參數會指向包含所需緩衝區大小的變數。後續呼叫可取得更多專案。
ERROR_CONNECTION_UNAVAIL	裝置目前未連線，但它是持續性連線。如需詳細資訊，請參閱接下來的＜備註＞一節。
ERROR_NO_NETWORK	網路無法使用。
ERROR_EXTENDED_ERROR	發生網路特定錯誤。若要取得錯誤的描述，請呼叫 WNetGetLastError 函式。
ERROR_NO_NET_OR_BAD_PATH	任何提供者都不會將本機名稱辨識為具有連線。不過，至少一個連線所屬的提供者無法使用網路。

備註

如果使用 Microsoft LAN Manager 網路建立網路連線，而且呼叫端應用程式在與建立連線的應用程式不同的登入會話中執行，則相關聯本機裝置的 WNetGetConnection 函式呼叫將會失敗。函式會因為ERROR_NOT_CONNECTED或ERROR_CONNECTION_UNAVAIL而失敗。這是因為使用 Microsoft LAN Manager 建立的連線只會對執行于與建立連線之應用程式相同的登入會話中執行的應用程式看見。 (若要防止 呼叫 WNetGetConnection 失敗，它不足以讓應用程式在建立 connection 的使用者帳戶中執行。)

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

範例

如需說明如何使用 WNetGetConnection 函式擷取與本機裝置相關聯之網路資源名稱的程式碼範例，請參閱擷取連線名稱。

注意

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

規格需求


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