Fungsi WNetAddConnection2A (winnetwk.h)
Fungsi WNetAddConnection2 membuat koneksi ke sumber daya jaringan dan dapat mengalihkan perangkat lokal ke sumber daya jaringan.
Fungsi WNetAddConnection2 menggantikan fungsi WNetAddConnection . Jika Anda dapat meneruskan handel ke jendela yang dapat digunakan penyedia sumber daya jaringan sebagai jendela pemilik untuk kotak dialog, panggil fungsi WNetAddConnection3 sebagai gantinya.
Sintaks
DWORD WNetAddConnection2A(
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
Parameter
[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 WNetAddConnection2 mengabaikan anggota lain dari struktur NETRESOURCE .
[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 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 konstanta yang dihentikan null yang menentukan nama pengguna untuk membuat koneksi.
Jika lpUserNameadalah 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 yang mungkin untuk opsi koneksi ditentukan dalam file header Winnetwk.h . Nilai berikut saat ini dapat digunakan.
| Nilai | Makna |
|---|---|
|
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 lpLocalNamenull atau menunjuk ke string kosong.) Jika bendera bit ini jelas, sistem operasi tidak mencoba memulihkan koneksi ketika pengguna masuk. |
|
Koneksi sumber daya jaringan tidak boleh dimasukkan ke dalam daftar koneksi baru-baru ini.
Jika bendera ini diatur dan koneksi berhasil ditambahkan, koneksi sumber daya jaringan akan dimasukkan ke dalam daftar koneksi terbaru hanya jika memiliki perangkat lokal yang dialihkan yang terkait dengannya. |
|
Koneksi sumber daya jaringan tidak boleh diingat.
Jika bendera ini diatur, sistem operasi tidak akan mencoba memulihkan koneksi ketika pengguna masuk lagi. |
|
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 mengharuskan perangkat lokal 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 huruf kandar yang ditetapkan Windows yang lebih lama dimulai dengan C: dan berakhir dengan Z:. |
|
Jika bendera ini diatur, maka sistem operasi tidak mulai menggunakan media baru untuk mencoba membuat koneksi (memulai koneksi putar-nomor baru, misalnya). |
|
Jika bendera ini diatur, sistem operasi meminta autentikasi pengguna menggunakan baris perintah alih-alih antarmuka pengguna grafis (GUI). Bendera ini diabaikan kecuali CONNECT_INTERACTIVE juga diatur.
Windows XP: Nilai ini didukung pada Windows XP dan yang lebih baru. |
|
Jika bendera ini diatur, dan sistem operasi meminta kredensial, kredensial harus disimpan oleh manajer kredensial. Jika manajer kredensial dinonaktifkan untuk sesi masuk penelepon, atau jika penyedia jaringan tidak mendukung penyimpanan kredensial, bendera ini diabaikan. Bendera ini diabaikan kecuali CONNECT_INTERACTIVE juga diatur. Bendera ini juga diabaikan kecuali Anda mengatur bendera CONNECT_COMMANDLINE.
Windows XP: Nilai ini didukung pada Windows XP dan yang lebih baru. |
|
Jika bendera ini diatur, dan sistem operasi meminta kredensial, kredensial diatur ulang oleh manajer kredensial. Jika manajer 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 Vista: Nilai ini didukung pada Windows Vista dan yang lebih baru. |
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan NO_ERROR.
Jika fungsi gagal, nilai yang dikembalikan dapat menjadi salah satu kode kesalahan berikut atau salah satu kode kesalahan sistem.
| 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. |
|
Nama perangkat yang ditentukan tidak valid. Kesalahan ini dikembalikan jika anggota lpLocalName dari struktur NETRESOURCE yang diarahkan oleh parameter lpNetResource menentukan perangkat yang tidak dapat dialihkan. |
|
Nama jaringan tidak dapat ditemukan. Nilai ini dikembalikan jika anggota lpRemoteName dari struktur NETRESOURCE yang ditunjukkan oleh parameter lpNetResource menentukan sumber daya yang tidak dapat diterima oleh penyedia sumber daya jaringan apa pun, baik karena nama sumber daya kosong, tidak valid, atau karena sumber daya bernama tidak dapat ditemukan. |
|
Profil pengguna dalam format yang salah. |
|
Nama penyedia jaringan yang ditentukan tidak valid. Kesalahan ini dikembalikan jika anggota lpProvider dari struktur NETRESOURCE yang ditujukkan oleh parameter lpNetResource menentukan nilai yang tidak cocok dengan penyedia jaringan apa pun. |
|
Nama pengguna yang ditentukan tidak valid. |
|
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. |
|
Nama perangkat lokal memiliki koneksi yang diingat ke sumber daya jaringan lain. Kesalahan ini dikembalikan jika entri untuk perangkat yang ditentukan oleh anggota lpLocalName dari struktur NETRESOURCE yang ditujukkan oleh parameter lpNetResource menentukan nilai yang sudah ada di profil pengguna untuk koneksi yang berbeda dari yang ditentukan dalam parameter lpNetResource . |
|
Terjadi kesalahan khusus jaringan. Panggil fungsi WNetGetLastError untuk mendapatkan deskripsi kesalahan. |
|
Upaya dilakukan untuk mengakses alamat yang tidak valid. Kesalahan ini dikembalikan jika parameter dwFlags menentukan nilai CONNECT_REDIRECT, tetapi anggota lpLocalName dari struktur NETRESOURCE yang diarahkan oleh parameter lpNetResource tidak ditentukan. |
|
Parameter salah. Kesalahan ini dikembalikan jika anggota dwType dari struktur NETRESOURCE yang diarahkan oleh parameter lpNetResource menentukan nilai selain RESOURCETYPE_DISK, RESOURCETYPE_PRINT, atau RESOURCETYPE_ANY. Kesalahan ini juga dikembalikan jika parameter dwFlags menentukan nilai yang salah atau tidak diketahui. |
|
Kata sandi yang ditentukan tidak valid dan bendera CONNECT_INTERACTIVE tidak diatur. |
|
Kegagalan masuk karena nama pengguna yang tidak dikenal atau kata sandi yang buruk. |
|
Tidak ada penyedia jaringan yang menerima jalur jaringan yang diberikan. Kesalahan ini dikembalikan jika tidak ada penyedia jaringan yang mengenali anggota lpRemoteName dari struktur NETRESOURCE yang ditujukkan oleh parameter lpNetResource . |
|
Jaringan tidak tersedia. |
|
Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan. |
Keterangan
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 WNetAddConnection2 , 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 WNetAddConnection2 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.
Contoh
Sampel kode berikut menggambarkan cara menggunakan fungsi WNetAddConnection2 untuk membuat koneksi ke sumber daya jaringan.
#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>
// Need to link with Netapi32.lib and Mpr.lib
int wmain(int argc, wchar_t * argv[])
{
DWORD dwRetVal;
NETRESOURCE nr;
DWORD dwFlags;
if (argc != 5) {
wprintf(L"Usage: %s <localname> <remotename> <username> <password>\n",
argv[0]);
wprintf(L" %s X: \\\\contoso\\public testuser testpasswd\n",
argv[0]);
exit(1);
}
wprintf(L"Calling WNetAddConnection2 with\n");
wprintf(L" lpLocalName = %s\n", argv[1]);
wprintf(L" lpRemoteName = %s\n", argv[2]);
wprintf(L" lpUsername = %s\n", argv[3]);
wprintf(L" lpPassword = %s\n", argv[4]);
// Zero out the NETRESOURCE struct
memset(&nr, 0, sizeof (NETRESOURCE));
// Assign our values to the NETRESOURCE structure.
nr.dwType = RESOURCETYPE_ANY;
nr.lpLocalName = argv[1];
nr.lpRemoteName = argv[2];
nr.lpProvider = NULL;
// Assign a value to the connection options
dwFlags = CONNECT_UPDATE_PROFILE;
//
// Call the WNetAddConnection2 function to assign
// a drive letter to the share.
//
dwRetVal = WNetAddConnection2(&nr, argv[4], argv[3], dwFlags);
//
// If the call succeeds, inform the user; otherwise,
// print the error.
//
if (dwRetVal == NO_ERROR)
wprintf(L"Connection added to %s\n", nr.lpRemoteName);
else
wprintf(L"WNetAddConnection2 failed with error: %u\n", dwRetVal);
exit(1);
}
Untuk sampel kode lain yang menggambarkan cara membuat koneksi ke sumber daya jaringan menggunakan fungsi WNetAddConnection2 , lihat Menambahkan Koneksi Jaringan dan Menetapkan Drive ke Berbagi.
Catatan
Header winnetwk.h mendefinisikan WNetAddConnection2 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