Fungsi WNetUseConnectionA (winnetwk.h)

Artikel
03/08/2023

Fungsi WNetUseConnection membuat koneksi ke sumber daya jaringan. Fungsi ini dapat mengalihkan perangkat lokal ke sumber daya jaringan.

Fungsi WNetUseConnection mirip dengan fungsi WNetAddConnection3 . Perbedaan utamanya adalah WNetUseConnection dapat secara otomatis memilih perangkat lokal yang tidak digunakan untuk dialihkan ke sumber daya jaringan.

Sintaks

DWORD WNetUseConnectionA(
  [in]      HWND           hwndOwner,
  [in]      LPNETRESOURCEA lpNetResource,
  [in]      LPCSTR         lpPassword,
  [in]      LPCSTR         lpUserId,
  [in]      DWORD          dwFlags,
  [out]     LPSTR          lpAccessName,
  [in, out] LPDWORD        lpBufferSize,
  [out]     LPDWORD        lpResult
);

Parameter

[in] hwndOwner

Tangani ke jendela yang dapat digunakan penyedia sumber daya jaringan sebagai jendela pemilik untuk kotak dialog. Gunakan parameter ini jika Anda mengatur nilai CONNECT_INTERACTIVE dalam parameter dwFlags .

[in] lpNetResource

Penunjuk ke struktur NETRESOURCE yang menentukan detail koneksi yang diusulkan. Struktur berisi informasi tentang sumber daya jaringan, perangkat lokal, dan penyedia sumber daya jaringan.

Anda harus menentukan anggota struktur NETRESOURCE berikut.

Anggota	Makna
dwType	Menentukan jenis sumber daya yang akan disambungkan. Paling efisien untuk menentukan jenis sumber daya dalam anggota ini, seperti RESOURCETYPE_DISK atau RESOURCETYPE_PRINT. Namun, jika anggota lpLocalName adalah NULL, atau jika menunjuk ke string kosong dan CONNECT_REDIRECT tidak diatur, dwType dapat RESOURCETYPE_ANY. Metode ini hanya berfungsi jika fungsi tidak secara otomatis memilih perangkat untuk dialihkan ke sumber daya jaringan. Meskipun anggota ini diperlukan, informasinya dapat diabaikan oleh penyedia layanan jaringan.
lpLocalName	Penunjuk ke string yang dihentikan null yang menentukan nama perangkat lokal yang akan dialihkan, seperti "F:" atau "LPT1". String diperlakukan dengan cara yang tidak peka huruf besar/kecil. Jika string kosong, atau jika lpLocalNameADALAH NULL, koneksi ke jaringan terjadi tanpa pengalihan. Jika nilai CONNECT_REDIRECT diatur dalam parameter dwFlags , atau jika jaringan memerlukan perangkat lokal yang dialihkan, fungsi memilih perangkat lokal untuk mengalihkan dan mengembalikan nama perangkat dalam parameter lpAccessName .
lpRemoteName	Penunjuk ke string yang dihentikan null yang menentukan sumber daya jaringan yang akan disambungkan. Panjang string dapat mencapai MAX_PATH karakter, dan harus mengikuti konvensi penamaan penyedia jaringan.
lpProvider	Penunjuk ke string yang dihentikan null yang menentukan penyedia jaringan yang akan disambungkan. Jika lpProvider adalah NULL, atau jika menunjuk ke string kosong, sistem operasi mencoba menentukan penyedia yang benar dengan mengurai string yang diacu oleh anggota lpRemoteName . Jika anggota ini bukan NULL, sistem operasi mencoba membuat koneksi hanya ke penyedia jaringan bernama. Anda harus mengatur anggota ini hanya jika Anda tahu penyedia jaringan yang ingin Anda gunakan. Jika tidak, biarkan sistem operasi menentukan penyedia mana yang dipetakan nama jaringan.

Fungsi WNetUseConnection mengabaikan anggota lain dari struktur NETRESOURCE . Untuk informasi selengkapnya, lihat deskripsi berikut untuk parameter dwFlags .

[in] lpPassword

Penunjuk ke string konstanta yang dihentikan null yang menentukan kata sandi yang akan digunakan dalam membuat koneksi jaringan.

Jika lpPassword adalah NULL, fungsi menggunakan kata sandi default saat ini yang terkait dengan pengguna yang ditentukan oleh lpUserID.

Jika lpPassword menunjuk ke string kosong, fungsi tidak menggunakan kata sandi.

Jika koneksi gagal karena kata sandi yang tidak valid dan nilai CONNECT_INTERACTIVE diatur dalam parameter dwFlags , fungsi menampilkan kotak dialog yang meminta pengguna untuk mengetik kata sandi.

[in] lpUserId

Penunjuk ke string konstanta yang dihentikan null yang menentukan nama pengguna untuk membuat koneksi.

Jika lpUserID adalah NULL, fungsi menggunakan nama pengguna default. (Konteks pengguna untuk proses ini menyediakan nama pengguna default.)

Parameter lpUserID ditentukan ketika pengguna ingin terhubung ke sumber daya jaringan tempat mereka telah diberi nama pengguna atau akun selain nama pengguna atau akun default.

String nama pengguna mewakili konteks keamanan. Ini mungkin khusus untuk penyedia jaringan.

[in] dwFlags

Set bendera bit yang menjelaskan koneksi. Parameter ini dapat berupa kombinasi apa pun dari nilai berikut.

Nilai	Makna
CONNECT_INTERACTIVE	Jika bendera ini diatur, sistem operasi dapat berinteraksi dengan pengguna untuk tujuan autentikasi.
CONNECT_PROMPT	Bendera ini menginstruksikan sistem untuk tidak menggunakan pengaturan default apa pun untuk nama pengguna atau kata sandi tanpa menawarkan pengguna kesempatan untuk menyediakan alternatif. Bendera ini diabaikan kecuali CONNECT_INTERACTIVE juga diatur.
CONNECT_REDIRECT	Bendera ini memaksa pengalihan perangkat lokal saat membuat koneksi. Jika anggota lpLocalNameNETRESOURCE menentukan perangkat lokal untuk dialihkan, bendera ini tidak berpengaruh, karena sistem operasi masih mencoba mengalihkan perangkat yang ditentukan. Ketika sistem operasi secara otomatis memilih perangkat lokal, anggota dwType tidak boleh sama dengan RESOURCETYPE_ANY. Jika bendera ini tidak diatur, perangkat lokal secara otomatis dipilih untuk pengalihan hanya jika jaringan memerlukan perangkat lokal untuk dialihkan. Windows XP: Ketika sistem secara otomatis menetapkan huruf kandar jaringan, huruf ditetapkan dimulai dengan Z:, lalu Y:, dan diakhapi dengan C:. Ini mengurangi tabrakan antara huruf kandar per log masuk (seperti huruf kandar jaringan) dan huruf kandar global (seperti drive disk). Perhatikan bahwa rilis sebelumnya menetapkan huruf drive yang dimulai dengan C: dan berakhir dengan Z:.
CONNECT_UPDATE_PROFILE	Bendera ini menginstruksikan sistem operasi untuk menyimpan koneksi sumber daya jaringan. Jika bendera bit ini diatur, sistem operasi secara otomatis mencoba memulihkan koneksi saat pengguna masuk. Sistem hanya mengingat koneksi yang berhasil yang mengalihkan perangkat lokal. Ini tidak mengingat koneksi yang gagal atau koneksi tanpa perangkat. (Koneksi tanpa perangkat terjadi ketika lpLocalNameadalah NULL atau ketika menunjuk ke string kosong.) Jika bendera bit ini jelas, sistem operasi tidak secara otomatis memulihkan koneksi saat masuk.
CONNECT_COMMANDLINE	Jika bendera ini diatur, sistem operasi meminta pengguna untuk autentikasi menggunakan baris perintah alih-alih antarmuka pengguna grafis (GUI). Bendera ini diabaikan kecuali CONNECT_INTERACTIVE juga diatur. Windows 2000/NT dan Windows Me/98/95: Nilai ini tidak didukung.
CONNECT_CMD_SAVECRED	Jika bendera ini diatur, dan sistem operasi meminta kredensial, kredensial harus disimpan oleh manajer kredensial. Jika pengelola kredensial dinonaktifkan untuk sesi masuk penelepon, atau jika penyedia jaringan tidak mendukung penyimpanan kredensial, bendera ini diabaikan. Bendera ini juga diabaikan kecuali Anda mengatur bendera CONNECT_COMMANDLINE. Windows 2000/NT dan Windows Me/98/95: Nilai ini tidak didukung.

[out] lpAccessName

Penunjuk ke buffer yang menerima permintaan sistem pada koneksi. Parameter ini bisa NULL.

Jika parameter ini ditentukan, dan anggota lpLocalName dari struktur NETRESOURCE menentukan perangkat lokal, buffer ini menerima nama perangkat lokal. Jika lpLocalName tidak menentukan perangkat dan jaringan memerlukan pengalihan perangkat lokal, atau jika nilai CONNECT_REDIRECT diatur, buffer ini menerima nama perangkat lokal yang dialihkan.

Jika tidak, nama yang disalin ke dalam buffer adalah dari sumber daya jarak jauh. Jika ditentukan, buffer ini harus setidaknya sebesar string yang diacu oleh anggota lpRemoteName .

[in, out] lpBufferSize

Penunjuk ke variabel yang menentukan ukuran buffer lpAccessName , dalam karakter. Jika panggilan gagal karena buffer tidak cukup besar, fungsi mengembalikan ukuran buffer yang diperlukan di lokasi ini. Untuk informasi selengkapnya, lihat deskripsi parameter lpAccessName dan kode kesalahan ERROR_MORE_DATA di bagian Nilai Pengembalian.

[out] lpResult

Penunjuk ke variabel yang menerima informasi tambahan tentang koneksi. Parameter ini bisa menjadi nilai berikut.

Nilai	Makna
CONNECT_LOCALDRIVE	Jika bendera ini diatur, koneksi dibuat menggunakan pengalihan perangkat lokal. Jika parameter lpAccessName menunjuk ke buffer, nama perangkat lokal disalin ke buffer.

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_ACCESS_DENIED	Pemanggil tidak memiliki akses ke sumber daya jaringan.
ERROR_ALREADY_ASSIGNED	Perangkat lokal yang ditentukan oleh anggota lpLocalName sudah tersambung ke sumber daya jaringan.
ERROR_BAD_DEVICE	Nilai yang ditentukan oleh lpLocalName tidak valid.
ERROR_BAD_NET_NAME	Nilai yang ditentukan oleh anggota lpRemoteName tidak dapat diterima oleh penyedia sumber daya jaringan apa pun karena nama sumber daya tidak valid, atau karena sumber daya bernama tidak dapat ditemukan.
ERROR_BAD_PROVIDER	Nilai yang ditentukan oleh anggota lpProvider tidak cocok dengan penyedia mana pun.
ERROR_CANCELLED	Upaya untuk membuat koneksi dibatalkan oleh pengguna melalui kotak dialog dari salah satu penyedia sumber daya jaringan, atau oleh sumber daya yang disebut.
ERROR_EXTENDED_ERROR	Terjadi kesalahan khusus jaringan. Untuk mendapatkan deskripsi kesalahan, panggil fungsi WNetGetLastError .
ERROR_INVALID_ADDRESS	Penelepon meneruskan penunjuk ke buffer yang tidak dapat diakses.
ERROR_INVALID_PARAMETER	Kesalahan ini adalah akibat dari salah satu kondisi berikut: Anggota lpRemoteName adalah NULL. Selain itu, lpAccessName bukan NULL, tetapi lpBufferSize adalah NULL atau titik ke nol. Anggota dwType tidak RESOURCETYPE_DISK maupun RESOURCETYPE_PRINT. Selain itu, CONNECT_REDIRECT diatur dalam dwFlags dan lpLocalName adalah NULL, atau koneksinya adalah ke jaringan yang memerlukan pengalihan perangkat lokal.
ERROR_INVALID_PASSWORD	Kata sandi yang ditentukan tidak valid dan bendera CONNECT_INTERACTIVE tidak diatur.
ERROR_MORE_DATA	Buffer lpAccessName terlalu kecil. Jika perangkat lokal dialihkan, buffer harus cukup besar untuk berisi nama perangkat lokal. Jika tidak, buffer harus cukup besar untuk berisi string yang ditunjukkan oleh lpRemoteName, atau nama sumber daya yang dapat dihubungkan yang aliasnya ditunjukkan oleh lpRemoteName. Jika kesalahan ini dikembalikan, maka tidak ada koneksi yang dibuat.
ERROR_NO_MORE_ITEMS	Sistem operasi tidak dapat secara otomatis memilih pengalihan lokal karena semua perangkat lokal yang valid sedang digunakan.
ERROR_NO_NET_OR_BAD_PATH	Operasi tidak dapat diselesaikan, baik karena komponen jaringan tidak dimulai, atau karena nama sumber daya yang ditentukan tidak dikenali.
ERROR_NO_NETWORK	Jaringan tidak tersedia.

Keterangan

Windows Server 2003 dan Windows XP: Fungsi WNet membuat dan menghapus huruf drive jaringan di 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.

Catatan

Header winnetwk.h mendefinisikan WNetUseConnection 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