Fungsi WSAConnect (winsock2.h)

Artikel
08/27/2023

Fungsi WSAConnect menetapkan koneksi ke aplikasi soket lain, bertukar data koneksi, dan menentukan kualitas layanan yang diperlukan berdasarkan struktur FLOWSPEC yang ditentukan.

Sintaks

int WSAAPI WSAConnect(
  [in]  SOCKET         s,
  [in]  const sockaddr *name,
  [in]  int            namelen,
  [in]  LPWSABUF       lpCallerData,
  [out] LPWSABUF       lpCalleeData,
  [in]  LPQOS          lpSQOS,
  [in]  LPQOS          lpGQOS
);

Parameter

[in] s

Deskriptor yang mengidentifikasi soket yang tidak terhubung.

[in] name

Penunjuk ke struktur sockaddr yang menentukan alamat yang akan disambungkan. Untuk IPv4, sockaddr berisi AF_INET untuk keluarga alamat, alamat IPv4 tujuan, dan port tujuan. Untuk IPv6, struktur sockaddr berisi AF_INET6 untuk keluarga alamat, alamat IPv6 tujuan, port tujuan, dan mungkin berisi informasi aliran dan id cakupan tambahan.

[in] namelen

Panjangnya, dalam byte, dari struktur sockaddr yang ditujukkan oleh parameter nama .

[in] lpCallerData

Penunjuk ke data pengguna yang akan ditransfer ke soket lain selama pembentukan koneksi. Lihat Keterangan.

[out] lpCalleeData

Penunjuk ke data pengguna yang akan ditransfer kembali dari soket lain selama pembentukan koneksi. Lihat Keterangan.

[in] lpSQOS

Penunjuk ke struktur FLOWSPEC untuk soket , satu untuk setiap arah.

[in] lpGQOS

Dicadangkan untuk digunakan di masa mendatang dengan grup soket. Penunjuk ke struktur FLOWSPEC untuk grup soket (jika berlaku). Parameter ini harus NULL.

Nilai kembali

Jika tidak ada kesalahan yang terjadi, WSAConnect mengembalikan nol. Jika tidak, ia mengembalikan SOCKET_ERROR, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError. Pada soket pemblokiran, nilai pengembalian menunjukkan keberhasilan atau kegagalan upaya koneksi.

Dengan soket yang tidak memblokir, upaya koneksi tidak dapat segera diselesaikan. Dalam hal ini, WSAConnect akan mengembalikan SOCKET_ERROR, dan WSAGetLastError akan mengembalikan WSAEWOULDBLOCK; oleh karena itu, aplikasi dapat:

Gunakan pilih untuk menentukan penyelesaian permintaan koneksi dengan memeriksa apakah soket dapat ditulis.
Jika aplikasi Anda menggunakan WSAAsyncSelect untuk menunjukkan minat pada peristiwa koneksi, maka aplikasi Anda akan menerima pemberitahuan FD_CONNECT ketika operasi koneksi selesai (berhasil atau tidak).
Jika aplikasi Anda menggunakan WSAEventSelect untuk menunjukkan minat pada peristiwa koneksi, maka objek peristiwa terkait akan diberi sinyal ketika operasi koneksi selesai (berhasil atau tidak).

Untuk soket nonblocking, sampai upaya koneksi menyelesaikan semua panggilan berikutnya ke WSAConnect pada soket yang sama akan gagal dengan kode kesalahan WSAEALREADY.

Jika kode kesalahan pengembalian menunjukkan upaya koneksi gagal (yaitu, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) aplikasi dapat memanggil WSAConnect lagi untuk soket yang sama.

Kode kesalahan	Makna
WSANOTINITIALISED	Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.
WSAENETDOWN	Subsistem jaringan gagal.
WSAEADDRINUSE	Alamat lokal soket sudah digunakan dan soket tidak ditandai untuk memungkinkan penggunaan kembali alamat dengan SO_REUSEADDR. Kesalahan ini biasanya terjadi selama eksekusi ikatan, tetapi dapat ditunda sampai fungsi ini jika fungsi ikat beroperasi pada alamat kartubebas sebagian (melibatkan ADDR_ANY) dan jika alamat tertentu perlu "diterapkan" pada saat fungsi ini.
WSAEINTR	Panggilan (memblokir) Windows Socket 1.1 dibatalkan melalui WSACancelBlockingCall.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets 1.1 sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEALREADY	Sambungan nonblokir atau panggilan WSAConnect sedang berlangsung pada soket yang ditentukan.
WSAEADDRNOTAVAIL	Alamat jarak jauh bukan alamat yang valid (seperti ADDR_ANY).
WSAEAFNOSUPPORT	Alamat dalam keluarga yang ditentukan tidak dapat digunakan dengan soket ini.
WSAECONNREFUSED	Upaya untuk menyambungkan ditolak.
WSAEFAULT	Nama atau parameter namelen bukan bagian yang valid dari ruang alamat pengguna, parameter namelen terlalu kecil, panjang buffer untuk lpCalleeData, lpSQOS, dan lpGQOS terlalu kecil, atau panjang buffer untuk lpCallerData terlalu besar.
WSAEINVAL	Parameter adalah soket mendengarkan, atau alamat tujuan yang ditentukan tidak konsisten dengan grup yang dibatasi tempat soket berada, atau parameter lpGQOS bukan NULL.
WSAEISCONN	Soket sudah tersambung (hanya soket berorientasi koneksi).
WSAENETUNREACH	Jaringan tidak dapat dijangkau dari host ini saat ini.
WSAEHOSTUNREACH	Operasi soket dicoba ke host yang tidak dapat dijangkau.
WSAENOBUFS	Tidak ada ruang buffer yang tersedia. Soket tidak dapat dihubungkan.
WSAENOTSOCK	Deskriptor bukan soket.
WSAEOPNOTSUPP	Struktur FLOWSPEC yang ditentukan dalam lpSQOS dan lpGQOS tidak dapat dipenuhi.
WSAEPROTONOSUPPORT	Parameter lpCallerData tidak didukung oleh penyedia layanan.
WSAETIMEDOUT	Coba sambungkan kehabisan waktu tanpa membuat koneksi.
WSAEWOULDBLOCK	Soket ditandai sebagai nonblocking dan koneksi tidak dapat segera diselesaikan.
WSAEACCES	Upaya untuk menyambungkan soket datagram ke alamat siaran gagal karena setsockopt SO_BROADCAST tidak diaktifkan.

Keterangan

Fungsi WSAConnect digunakan untuk membuat koneksi ke tujuan yang ditentukan, dan untuk melakukan sejumlah operasi tambahan lainnya yang terjadi pada waktu koneksi. Jika soket, s, tidak terikat, nilai unik ditetapkan ke asosiasi lokal oleh sistem, dan soket ditandai sebagai terikat.

Untuk aplikasi yang ditargetkan ke Windows Vista dan yang lebih baru, pertimbangkan untuk menggunakan fungsi WSAConnectByList atau WSAConnectByName yang sangat menyederhanakan desain aplikasi klien.

Untuk soket berorientasi koneksi (misalnya, ketik SOCK_STREAM), koneksi aktif dimulai ke host asing menggunakan nama (alamat di namespace soket; untuk deskripsi terperinci, silakan lihat ikatan). Ketika panggilan ini berhasil diselesaikan, soket siap untuk mengirim/menerima data. Jika parameter alamat struktur nama semuanya nol, WSAConnect akan mengembalikan kesalahan WSAEADDRNOTAVAIL. Setiap upaya untuk menyambungkan kembali koneksi aktif akan gagal dengan kode kesalahan WSAEISCONN.

Catatan Jika soket dibuka, panggilan setsockopt dilakukan, lalu panggilan sendto dilakukan, Windows Sockets melakukan panggilan fungsi ikat implisit.

Untuk soket yang berorientasi koneksi dan tidak memblokir, seringkali tidak mungkin untuk segera menyelesaikan koneksi. Dalam kasus seperti itu, fungsi ini mengembalikan kesalahan WSAEWOULDBLOCK. Namun, operasi berlanjut. Ketika hasil keberhasilan atau kegagalan diketahui, itu dapat dilaporkan dengan salah satu dari beberapa cara tergantung pada bagaimana klien mendaftar untuk pemberitahuan. Jika klien menggunakan pilih, keberhasilan dilaporkan dalam set writefds dan kegagalan dilaporkan dalam set exceptfds . Jika klien menggunakan WSAAsyncSelect atau WSAEventSelect, pemberitahuan diumumkan dengan FD_CONNECT dan kode kesalahan yang terkait dengan FD_CONNECT menunjukkan keberhasilan atau alasan tertentu untuk kegagalan.

Untuk soket tanpa koneksi (misalnya, jenis SOCK_DGRAM), operasi yang dilakukan oleh WSAConnect hanya untuk membuat alamat tujuan default sehingga soket dapat digunakan pada operasi kirim dan terima berorientasi koneksi berikutnya (kirim, WSASend, recv, dan WSARecv). Setiap datagram yang diterima dari alamat selain alamat tujuan yang ditentukan akan dibuang. Jika seluruh struktur nama semuanya nol (bukan hanya parameter alamat struktur nama), maka soket akan terputus. Kemudian, alamat jarak jauh default tidak akan ditentukan, jadi panggilan kirim, WSASend, recv, dan WSARecv akan mengembalikan kode kesalahan WSAENOTCONN. Namun, sendto, WSASendTo, recvfrom, dan WSARecvFrom masih dapat digunakan. Tujuan default dapat diubah hanya dengan memanggil WSAConnect lagi, bahkan jika soket sudah tersambung. Setiap datagram yang diantrekan untuk tanda terima dibuang jika nama berbeda dari WSAConnect sebelumnya.

Untuk soket tanpa koneksi, nama dapat menunjukkan alamat yang valid, termasuk alamat siaran. Namun, untuk terhubung ke alamat siaran, soket harus mengaktifkan setsockopt SO_BROADCAST. Jika tidak, WSAConnect akan gagal dengan kode kesalahan WSAEACCES.

Pada soket tanpa koneksi, pertukaran data pengguna-ke-pengguna tidak dimungkinkan dan parameter yang sesuai akan diabaikan secara diam-diam.

Aplikasi ini bertanggung jawab untuk mengalokasikan ruang memori apa pun yang diarahkan ke secara langsung atau tidak langsung oleh salah satu parameter yang ditentukannya.

Parameter lpCallerData berisi pointer ke data pengguna apa pun yang akan dikirim bersama dengan permintaan koneksi (disebut menyambungkan data). Ini adalah data tambahan, bukan dalam aliran data jaringan normal, yang dikirim dengan permintaan jaringan untuk membuat koneksi. Opsi ini digunakan oleh protokol warisan seperti DECNet, OSI TP4, dan lainnya.

Catatan Data sambungkan tidak didukung oleh protokol TCP/IP di Windows. Data koneksi hanya didukung pada ATM (RAWWAN) melalui soket mentah.

Jika lpCallerData adalah NULL, tidak ada data pengguna yang akan diteruskan ke peer. lpCalleeData adalah parameter hasil yang akan berisi data pengguna apa pun yang diteruskan kembali dari soket lain sebagai bagian dari pembentukan koneksi dalam struktur WSABUF. Anggota lensa struktur WSABUF yang diarahkan oleh parameter lpCalleeData awalnya berisi panjang buffer yang dialokasikan oleh aplikasi untuk anggota buf struktur WSABUF . Anggota len dari struktur WSABUF yang diarahkan oleh parameter lpCalleeData akan diatur ke nol jika tidak ada data pengguna yang diteruskan kembali. Informasi lpCalleeData akan valid ketika operasi koneksi selesai. Untuk memblokir soket, operasi koneksi selesai ketika fungsi WSAConnect kembali. Untuk soket yang tidak diblokir, penyelesaian akan dilakukan setelah pemberitahuan FD_CONNECT terjadi. Jika lpCalleeData adalah NULL, tidak ada data pengguna yang akan diteruskan kembali. Format data pengguna yang tepat khusus untuk keluarga alamat tempat soket berada.

Pada waktu koneksi, aplikasi dapat menggunakan parameter lpSQOS dan lpGQOS untuk mengambil alih kualitas spesifikasi layanan sebelumnya yang dibuat untuk soket melalui WSAIoctl dengan opcode SIO_SET_QOS atau SIO_SET_GROUP_QOS.

Parameter lpSQOS menentukan struktur FLOWSPEC untuk soket, satu untuk setiap arah, diikuti oleh parameter khusus penyedia tambahan. Jika penyedia transportasi terkait secara umum atau jenis soket tertentu khususnya tidak dapat menghormati kualitas permintaan layanan, kesalahan akan dikembalikan seperti yang ditunjukkan dalam hal berikut. Nilai spesifikasi alur pengiriman atau penerimaan akan diabaikan, masing-masing, untuk soket searah apa pun. Jika tidak ada parameter khusus penyedia yang ditentukan, anggota buf dan len dari struktur WSABUF yang ditunjukkan oleh parameter lpCalleeData masing-masing harus diatur ke NULL dan nol. Nilai NULL untuk parameter lpSQOS menunjukkan tidak ada kualitas layanan yang disediakan aplikasi.

Dicadangkan untuk digunakan di masa mendatang dengan grup soket lpGQOS menentukan struktur FLOWSPEC untuk grup soket (jika berlaku), satu untuk setiap arah, diikuti oleh parameter khusus penyedia tambahan. Jika tidak ada parameter khusus penyedia yang ditentukan, anggota buf dan len dari struktur WSABUF yang ditunjukkan oleh parameter lpCalleeData masing-masing harus diatur ke NULL dan nol. Nilai NULL untuk lpGQOS menunjukkan tidak ada kualitas layanan grup yang disediakan aplikasi. Parameter ini akan diabaikan jika s bukan pembuat grup soket.

Ketika soket yang terhubung ditutup karena alasan apa pun, soket harus dibuang dan dibuat ulang. Paling aman untuk berasumsi bahwa ketika segala sesuatunya salah karena alasan apa pun pada soket yang terhubung, aplikasi harus membuang dan membuat ulang soket yang diperlukan untuk kembali ke titik stabil.

Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti WSAConnect, Winsock mungkin perlu menunggu peristiwa jaringan sebelum panggilan dapat selesai. Winsock melakukan penantian yang dapat diperingatkan dalam situasi ini, yang dapat terganggu oleh panggilan prosedur asinkron (APC) yang dijadwalkan pada utas yang sama. Mengeluarkan panggilan Winsock pemblokiran lain di dalam APC yang mengganggu panggilan Winsock pemblokiran yang sedang berlangsung pada utas yang sama akan menyebabkan perilaku yang tidak terdefinisi, dan tidak boleh dicoba oleh klien Winsock.

Windows Phone 8: Fungsi ini didukung untuk aplikasi Windows Phone Store di Windows Phone 8 dan yang lebih baru.

Windows 8.1 dan Windows Server 2012 R2: Fungsi ini didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8.1, Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	winsock2.h
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll