Fungsi WNetUseConnectionA (winnetwk.h)
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.
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 |
|---|---|
|
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 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:. |
|
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. |
|
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. |
[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 |
|---|---|
|
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 |
|---|---|
|
Pemanggil tidak memiliki akses ke sumber daya jaringan. |
|
Perangkat lokal yang ditentukan oleh anggota lpLocalName sudah tersambung ke sumber daya jaringan. |
|
Nilai yang ditentukan oleh lpLocalName tidak valid. |
|
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. |
|
Nilai yang ditentukan oleh anggota lpProvider tidak cocok dengan penyedia mana pun. |
|
Upaya untuk membuat koneksi dibatalkan oleh pengguna melalui kotak dialog dari salah satu penyedia sumber daya jaringan, atau oleh sumber daya yang disebut. |
|
Terjadi kesalahan khusus jaringan. Untuk mendapatkan deskripsi kesalahan, panggil fungsi WNetGetLastError . |
|
Penelepon meneruskan penunjuk ke buffer yang tidak dapat diakses. |
|
Kesalahan ini adalah akibat dari salah satu kondisi berikut:
|
|
Kata sandi yang ditentukan tidak valid dan bendera CONNECT_INTERACTIVE tidak diatur. |
|
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. |
|
Sistem operasi tidak dapat secara otomatis memilih pengalihan lokal karena semua perangkat lokal yang valid sedang digunakan. |
|
Operasi tidak dapat diselesaikan, baik karena komponen jaringan tidak dimulai, atau karena nama sumber daya yang ditentukan tidak dikenali. |
|
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 |
Lihat juga
Saran dan Komentar
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: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk