Fungsi WNetGetConnectionA (winnetwk.h)

Artikel
08/27/2023

Fungsi WNetGetConnection mengambil nama sumber daya jaringan yang terkait dengan perangkat lokal.

Sintaks

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

Parameter

[in] lpLocalName

Penunjuk ke string konstanta yang dihentikan null yang menentukan nama perangkat lokal untuk mendapatkan nama jaringan.

[out] lpRemoteName

Penunjuk ke string yang dihentikan null yang menerima nama jarak jauh yang digunakan untuk membuat koneksi.

[in, out] lpnLength

Penunjuk ke variabel yang menentukan ukuran buffer yang diacu oleh parameter lpRemoteName , dalam karakter. Jika fungsi gagal karena buffer tidak cukup besar, parameter ini mengembalikan ukuran buffer yang diperlukan.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah NO_ERROR.

Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan sistem, seperti salah satu nilai berikut.

Menampilkan kode	Deskripsi
ERROR_BAD_DEVICE	String yang ditujukan oleh parameter lpLocalName tidak valid.
ERROR_NOT_CONNECTED	Perangkat yang ditentukan oleh lpLocalName bukan perangkat yang dialihkan. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
ERROR_MORE_DATA	Buffer terlalu kecil. Parameter lpnLength menunjuk ke variabel yang berisi ukuran buffer yang diperlukan. Entri lainnya tersedia dengan panggilan berikutnya.
ERROR_CONNECTION_UNAVAIL	Perangkat saat ini tidak tersambung, tetapi merupakan koneksi persisten. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
ERROR_NO_NETWORK	Jaringan tidak tersedia.
ERROR_EXTENDED_ERROR	Terjadi kesalahan khusus jaringan. Untuk mendapatkan deskripsi kesalahan, panggil fungsi WNetGetLastError .
ERROR_NO_NET_OR_BAD_PATH	Tidak ada penyedia yang mengenali nama lokal yang memiliki koneksi. Namun, jaringan tidak tersedia untuk setidaknya satu penyedia yang mungkin memiliki koneksi.

Keterangan

Jika koneksi jaringan dibuat menggunakan jaringan Microsoft LAN Manager, dan aplikasi panggilan berjalan dalam sesi masuk yang berbeda dari aplikasi yang membuat koneksi, panggilan ke fungsi WNetGetConnection untuk perangkat lokal terkait akan gagal. Fungsi gagal dengan ERROR_NOT_CONNECTED atau ERROR_CONNECTION_UNAVAIL. Ini karena koneksi yang dibuat menggunakan Microsoft LAN Manager hanya terlihat oleh aplikasi yang berjalan dalam sesi masuk yang sama dengan aplikasi yang membuat koneksi. (Untuk mencegah panggilan ke WNetGetConnection gagal, tidak cukup bagi aplikasi untuk berjalan di akun pengguna yang membuat koneksi.)

Windows Server 2003 dan Windows XP: Fungsi ini meminta namespace perangkat MS-DOS yang terkait dengan sesi masuk karena perangkat MS-DOS diidentifikasi oleh AuthenticationID. (AuthenticationID adalah pengidentifikasi unik lokal, atau LUID, yang terkait dengan sesi masuk.) Ini dapat memengaruhi aplikasi yang memanggil salah satu fungsi WNet untuk membuat huruf kandar jaringan di bawah satu masuk pengguna, tetapi kueri untuk huruf drive jaringan yang ada di bawah masuk pengguna yang berbeda. Contoh situasi ini bisa jadi ketika masuk kedua pengguna dibuat dalam sesi masuk, misalnya, dengan memanggil fungsi CreateProcessAsUser , dan masuk kedua menjalankan aplikasi yang memanggil fungsi GetLogicalDrives . GetLogicalDrives tidak mengembalikan huruf kandar jaringan yang dibuat oleh fungsi WNet di bawah masuk pertama. Perhatikan bahwa dalam contoh sebelumnya sesi masuk pertama masih ada, dan contohnya dapat berlaku untuk sesi masuk apa pun, termasuk sesi Layanan Terminal. Untuk informasi selengkapnya, lihat Menentukan Nama Perangkat MS-DOS.

Contoh

Untuk sampel kode yang menggambarkan cara menggunakan fungsi WNetGetConnection untuk mengambil nama sumber daya jaringan yang terkait dengan perangkat lokal, lihat Mengambil Nama Koneksi.

Catatan

Header winnetwk.h mendefinisikan WNetGetConnection sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	winnetwk.h
Pustaka	Mpr.lib
DLL	Mpr.dll