Fungsi WNetAddConnection3A (winnetwk.h)

Artikel
03/08/2023

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

Fungsi WNetAddConnection3 mirip dengan fungsi WNetAddConnection2 . Perbedaan utamanya adalah WNetAddConnection3 memiliki parameter tambahan, handel ke jendela yang dapat digunakan penyedia sumber daya jaringan sebagai jendela pemilik untuk kotak dialog. Fungsi WNetAddConnection2 dan fungsi WNetAddConnection3 menggantikan fungsi WNetAddConnection .

Sintaks

DWORD WNetAddConnection3A(
  [in] HWND           hwndOwner,
  [in] LPNETRESOURCEA lpNetResource,
  [in] LPCSTR         lpPassword,
  [in] LPCSTR         lpUserName,
  [in] DWORD          dwFlags
);

Parameter

[in] hwndOwner

Handel 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 .

Parameter hwndOwner dapat berupa NULL. Jika ya, panggilan ke WNetAddConnection3 setara dengan memanggil fungsi WNetAddConnection2 .

[in] lpNetResource

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

Anda harus menentukan anggota struktur NETRESOURCE berikut.

Anggota	Makna
dwType	Jenis sumber daya jaringan yang akan disambungkan. Jika anggota lpLocalName menunjuk ke string yang tidak kosong, anggota ini dapat sama dengan RESOURCETYPE_DISK atau RESOURCETYPE_PRINT. Jika lpLocalNameadalah NULL, atau jika menunjuk ke string kosong, dwType dapat sama dengan RESOURCETYPE_DISK, RESOURCETYPE_PRINT, atau RESOURCETYPE_ANY. Meskipun anggota ini diperlukan, informasinya dapat diabaikan oleh penyedia layanan jaringan.
lpLocalName	Penunjuk ke string yang dihentikan null yang menentukan nama perangkat lokal untuk dialihkan, seperti "F:" atau "LPT1". String diperlakukan dengan cara yang tidak peka huruf besar/kecil. Jika string kosong atau jika lpLocalNameadalah NULL, fungsi membuat koneksi ke sumber daya jaringan tanpa mengalihkan perangkat lokal.
lpRemoteName	Penunjuk ke string yang dihentikan null yang menentukan sumber daya jaringan untuk 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 untuk 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 mana yang ingin Anda gunakan. Jika tidak, biarkan sistem operasi menentukan penyedia jaringan mana yang dipetakan nama jaringan.

Fungsi WNetAddConnection3 mengabaikan anggota lain dari struktur NETRESOURCE .

[in] lpPassword

Penunjuk ke string 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 parameter lpUserName .

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.

Windows Me/98/95: Parameter ini harus NULL atau string kosong.

[in] lpUserName

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

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

Parameter lpUserName 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.

Windows Me/98/95: Parameter ini harus NULL atau string kosong.

[in] dwFlags

Sekumpulan opsi koneksi. Nilai berikut saat ini ditentukan.

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 Server 2003 dan 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 versi sebelumnya dari huruf kandar yang ditetapkan Windows dimulai dengan C: dan berakhir dengan Z:.
CONNECT_UPDATE_PROFILE	Koneksi sumber daya jaringan harus diingat. Jika bendera bit ini diatur, sistem operasi secara otomatis mencoba memulihkan koneksi saat pengguna masuk. Sistem operasi hanya mengingat koneksi yang berhasil yang mengalihkan perangkat lokal. Ini tidak mengingat koneksi yang gagal atau koneksi tanpa perangkat. (Koneksi tanpa perangkat terjadi ketika anggota lpLocalName adalah 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.

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_DEV_TYPE	Jenis perangkat lokal dan jenis sumber daya jaringan tidak cocok.
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, baik karena nama sumber daya tidak valid, atau karena sumber daya bernama tidak dapat ditemukan.
ERROR_BAD_PROFILE	Profil pengguna dalam format yang salah.
ERROR_BAD_PROVIDER	Nilai yang ditentukan oleh anggota lpProvider tidak cocok dengan penyedia mana pun.
ERROR_BUSY	Router atau penyedia sibuk, mungkin menginisialisasi. Pemanggil harus mencoba kembali.
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_CANNOT_OPEN_PROFILE	Sistem tidak dapat membuka profil pengguna untuk memproses koneksi persisten.
ERROR_DEVICE_ALREADY_REMEMBERED	Entri untuk perangkat yang ditentukan oleh anggota lpLocalName sudah ada di profil pengguna.
ERROR_EXTENDED_ERROR	Terjadi kesalahan khusus jaringan. Panggil fungsi WNetGetLastError untuk mendapatkan deskripsi kesalahan.
ERROR_INVALID_PASSWORD	Kata sandi yang ditentukan tidak valid dan bendera CONNECT_INTERACTIVE tidak diatur.
ERROR_NO_NET_OR_BAD_PATH	Operasi tidak dapat dilakukan karena komponen jaringan tidak dimulai atau karena nama yang ditentukan tidak dapat digunakan.
ERROR_NO_NETWORK	Jaringan tidak tersedia.

Keterangan

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

Pada 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 (a
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 log masuk kedua pengguna dibuat dalam sesi masuk, misalnya, dengan memanggil fungsi CreateProcessAsUser , dan masuk kedua menjalankan aplikasi yang memanggil fungsi GetLogicalDrives . Panggilan ke fungsi GetLogicalDrives tidak mengembalikan huruf kandar jaringan yang dibuat oleh panggilan 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.

Pada Windows Server 2003 dan Windows XP, jika layanan yang berjalan sebagai LocalSystem memanggil fungsi WNetAddConnection3 , maka drive yang dipetakan terlihat oleh semua sesi masuk pengguna.

Untuk penyedia jaringan Microsoft, anggota lpRemoteName dari struktur NETRESOURCE yang diarahkan oleh parameter lpNetResource dapat berisi alamat IPv4 dalam notasi dotted-decimal. Contoh untuk berbagi mungkin sebagai berikut:

\192.168.1.1\share

Untuk penyedia jaringan Microsoft di Windows Vista dan yang lebih baru, anggota lpRemoteName dari struktur NETRESOURCE yang diacu oleh parameter lpNetResource dapat berisi alamat IPv6. Namun, format harfiah IPv6 harus digunakan sehingga alamat IPv6 diurai dengan benar. Alamat harfiah IPv6 adalah dari bentuk:

ipv6-address dengan karakter ':' digantikan oleh karakter '-' diikuti oleh string ".ipv6-literal.net".

Misalnya, untuk alamat IPv6 berikut:

2001:4898:9:3:c069:aa97:fe76:2449

contoh untuk berbagi mungkin sebagai berikut:

\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share

Penyedia jaringan lain dapat mendukung anggota lpRemoteName dari struktur NETRESOURCE yang diarahkan oleh parameter lpNetResource yang berisi alamat IPv4 atau IPv6, tetapi ini hingga penyedia jaringan tertentu.

Windows 7 dan Windows Server 2008 R2: Jika fungsi WNetAddConnection3 dipanggil dengan kredensial pengguna eksplisit yang ditentukan dalam pUsername dan lpPassword untuk membuat koneksi dengan sumber daya jaringan di server tertentu dan kemudian dipanggil lagi dengan salah satu parameter ini sebagai NULL (untuk menggunakan nama pengguna default atau kata sandi default) ke server yang sama, panggilan dengan gagal. Kesalahan yang dikembalikan akan ERROR_BAD_USERNAME atau ERROR_INVALID_PASSWORD.

Catatan

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

Persyaratan	Nilai
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