Fungsi WNetAddConnection3A (winnetwk.h)
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.
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 |
---|---|
|
Jika bendera ini diatur, sistem operasi dapat berinteraksi dengan pengguna untuk tujuan autentikasi. |
|
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. |
|
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:. |
|
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. |
|
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. |
|
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 |
---|---|
|
Pemanggil tidak memiliki akses ke sumber daya jaringan. |
|
Perangkat lokal yang ditentukan oleh anggota lpLocalName sudah tersambung ke sumber daya jaringan. |
|
Jenis perangkat lokal dan jenis sumber daya jaringan tidak cocok. |
|
Nilai yang ditentukan oleh lpLocalName tidak valid. |
|
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. |
|
Profil pengguna dalam format yang salah. |
|
Nilai yang ditentukan oleh anggota lpProvider tidak cocok dengan penyedia mana pun. |
|
Router atau penyedia sibuk, mungkin menginisialisasi. Pemanggil harus mencoba kembali. |
|
Upaya untuk membuat koneksi dibatalkan oleh pengguna melalui kotak dialog dari salah satu penyedia sumber daya jaringan, atau oleh sumber daya yang disebut. |
|
Sistem tidak dapat membuka profil pengguna untuk memproses koneksi persisten. |
|
Entri untuk perangkat yang ditentukan oleh anggota lpLocalName sudah ada di profil pengguna. |
|
Terjadi kesalahan khusus jaringan. Panggil fungsi WNetGetLastError untuk mendapatkan deskripsi kesalahan. |
|
Kata sandi yang ditentukan tidak valid dan bendera CONNECT_INTERACTIVE tidak diatur. |
|
Operasi tidak dapat dilakukan karena komponen jaringan tidak dimulai atau karena nama yang ditentukan tidak dapat digunakan. |
|
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 |
Lihat juga
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk