Fungsi panggilan balik LPWSPCONNECT (ws2spi.h)
Fungsi LPWSPConnect membuat koneksi ke serekan, bertukar data koneksi, dan menentukan kualitas layanan yang diperlukan berdasarkan spesifikasi alur yang disediakan.
Sintaks
LPWSPCONNECT Lpwspconnect;
int Lpwspconnect(
[in] SOCKET s,
[in] const sockaddr *name,
[in] int namelen,
[in] LPWSABUF lpCallerData,
[out] LPWSABUF lpCalleeData,
[in] LPQOS lpSQOS,
[in] LPQOS lpGQOS,
[out] LPINT lpErrno
)
{...}
Parameter
[in] s
Deskriptor mengidentifikasi soket yang tidak terhubung.
[in] name
Nama serekan tempat soket di sockaddr akan disambungkan.
[in] namelen
Panjang nama, dalam byte.
[in] lpCallerData
Arahkan ke data pengguna yang akan ditransfer ke serekan selama pembentukan koneksi.
[out] lpCalleeData
Penunjuk ke buffer tempat data pengguna apa pun yang diterima dari serekan selama pembentukan koneksi dapat disalin.
[in] lpSQOS
Arahkan ke spesifikasi alur untuk soket, satu untuk setiap arah.
[in] lpGQOS
Dicadangkan.
[out] lpErrno
Arahkan ke kode kesalahan.
Mengembalikan nilai
Jika tidak ada kesalahan yang terjadi, LPWSPConnect mengembalikan nol. Jika tidak, kode mengembalikan SOCKET_ERROR, dan kode kesalahan tertentu tersedia di lpErrno.
Pada soket pemblokiran, nilai yang dikembalikan menunjukkan keberhasilan atau kegagalan upaya koneksi. Jika kode kesalahan pengembalian menunjukkan upaya koneksi gagal (yaitu, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) klien Winsock SPI dapat memanggil LPWSPConnect lagi untuk soket yang sama.
| Kode Kesalahan | Makna |
|---|---|
| Subsistem jaringan gagal. | |
| Alamat lokal soket sudah digunakan dan soket tidak ditandai untuk memungkinkan penggunaan kembali alamat dengan SO_REUSEADDR. Kesalahan ini biasanya terjadi pada saat pengikatan, tetapi dapat ditunda sampai fungsi ini jika ikatannya adalah ke alamat wildcard sebagian (melibatkan ADDR_ANY) dan jika alamat tertentu perlu dilakukan pada saat fungsi ini. | |
| (Pemblokiran) panggilan dibatalkan melalui LPWSPCancelBlockingCall. | |
| Pemblokiran panggilan Winsock sedang berlangsung atau penyedia layanan masih memproses fungsi panggilan balik. | |
|
Panggilan LPWSPConnect yang tidak diblokir sedang berlangsung pada soket yang ditentukan. Untuk mempertahankan kompatibilitas mundur, kesalahan ini dilaporkan sebagai WSAEINVAL ke aplikasi Windows Sockets 1.1 yang terhubung ke Winsock.dll atau Wsock32.dll. |
|
| Alamat jarak jauh bukan alamat yang valid (misalnya, ADDR_ANY). | |
| Alamat dalam keluarga yang ditentukan tidak dapat digunakan dengan soket ini. | |
| Upaya untuk menyambungkan ditolak. | |
| 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. | |
| Parameter s adalah soket mendengarkan. | |
| Soket sudah terhubung (hanya soket berorientasi koneksi). | |
| Jaringan tidak dapat dijangkau dari host ini saat ini. | |
| Tidak ada ruang buffer yang tersedia. Soket tidak dapat dihubungkan. | |
| Deskriptor bukan soket. | |
| Spesifikasi alur yang ditentukan dalam lpSQOS tidak dapat dipenuhi. | |
| Augment lpCallerData tidak didukung oleh penyedia layanan. | |
| Upaya untuk menyambungkan kehabisan waktu tanpa membuat koneksi. | |
| Soket ditandai sebagai nonblocking dan koneksi tidak dapat segera diselesaikan. Dimungkinkan untuk memilih soket menggunakan fungsi LPWSPSelect saat terhubung dengan menggunakan fungsi **WSPSelect** untuk memilihnya untuk ditulis. | |
| Upaya untuk menyambungkan soket datagram ke alamat siaran gagal karena WSPSetSockOpt SO_BROADCAST tidak diaktifkan. |
Keterangan
Fungsi ini digunakan untuk membuat koneksi ke tujuan yang ditentukan dan untuk melakukan sejumlah operasi tambahan lainnya yang terjadi pada waktu koneksi juga. Jika soket, s, tidak terikat, nilai unik ditetapkan ke asosiasi lokal oleh sistem dan soket ditandai sebagai terikat.
Untuk soket berorientasi koneksi (misalnya, ketik SOCK_STREAM), koneksi aktif dimulai ke host yang ditentukan menggunakan nama (alamat di namespace soket. Untuk deskripsi terperinci, lihat LPWSPBind. Ketika panggilan ini berhasil diselesaikan, soket siap untuk mengirim dan menerima data. Jika anggota alamat struktur nama semuanya nol, LPWSPConnect akan mengembalikan kesalahan WSAEADDRNOTAVAIL. Setiap upaya untuk menyambungkan kembali koneksi aktif akan gagal dengan kode kesalahan WSAEISCONN.
Untuk soket yang berorientasi pada koneksi, tidak memblokir seringkali tidak mungkin untuk segera menyelesaikan koneksi. Dalam kasus seperti itu, fungsi ini kembali dengan kesalahan WSAEWOULDBLOCK tetapi 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 LPWSPSelect, keberhasilan dilaporkan dalam set writefds dan kegagalan dilaporkan dalam set exceptfds . Jika klien menggunakan LPWSPAsyncSelect atau LPWSPEventSelect, 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 LPWSPConnect adalah menetapkan alamat tujuan default sehingga soket dapat digunakan dengan operasi kirim dan terima berorientasi koneksi berikutnya (LPWSPSend, LPWSPRecv). Setiap datagram yang diterima dari alamat selain alamat tujuan yang ditentukan akan dibuang. Jika anggota alamat struktur nama semuanya nol, soket akan terputus — alamat jarak jauh default akan tidak ditentukan, sehingga panggilan LPWSPSend dan LPWSPRecv akan mengembalikan kode kesalahan WSAENOTCONN. Namun, LPWSPSendTo dan LPWSPRecvFrom masih dapat digunakan. Tujuan default dapat diubah hanya dengan memanggil LPWSPConnect lagi, bahkan jika soket sudah tersambung. Setiap datagram yang diantrekan untuk tanda terima dibuang jika nama berbeda dari LPWSPConnect sebelumnya.
Untuk soket tanpa koneksi, nama dapat menunjukkan alamat yang valid, termasuk alamat siaran. Namun, untuk menyambungkan ke alamat siaran, soket harus mengaktifkan WSPSetSockOpt SO_BROADCAST. Jika tidak, LPWSPConnect 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.
Klien Winsock SPI bertanggung jawab untuk mengalokasikan ruang memori apa pun yang diarahkan ke secara langsung atau tidak langsung oleh salah satu parameter yang ditentukannya.
lpCallerData adalah parameter nilai yang berisi data pengguna apa pun yang akan dikirim bersama dengan permintaan koneksi. Jika lpCallerData null, tidak ada data pengguna yang akan diteruskan ke peer. lpCalleeData adalah parameter hasil yang akan mereferensikan setiap data pengguna yang diteruskan kembali dari peer sebagai bagian dari pembentukan koneksi. lpCalleeData-len> awalnya berisi panjang buffer yang dialokasikan oleh klien Winsock SPI dan ditunjukkan oleh lpCalleeData-buf.> lpCalleeData-len> akan diatur ke nol jika tidak ada data pengguna yang diteruskan kembali. Informasi lpCalleeData akan valid ketika operasi koneksi selesai. Untuk memblokir soket, ini akan menjadi ketika fungsi LPWSPConnect kembali. Untuk soket yang tidak diblokir, ini akan terjadi setelah pemberitahuan FD_CONNECT terjadi. Jika lpCalleeData null, tidak ada data pengguna yang akan diteruskan kembali. Format data pengguna yang tepat khusus untuk keluarga alamat tempat soket berada dan/atau aplikasi yang terlibat.
Pada waktu koneksi, klien Winsock SPI dapat menggunakan parameter lpSQOS untuk mengambil alih spesifikasi QoS sebelumnya yang dibuat untuk soket melalui LPWSPIoctl dengan opcode SIO_SET_QOS.
lpSQOS menentukan spesifikasi alur 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 mematuhi permintaan QoS, kesalahan akan dikembalikan seperti yang ditunjukkan di bawah ini. Nilai spesifikasi alur pengiriman atau penerimaan akan diabaikan, masing-masing, untuk soket searah apa pun. Jika tidak ada parameter khusus penyedia yang disediakan, buf dan anggota len darilpSQOS-ProviderSpecific masing-masing> harus diatur ke null dan nol. Nilai null untuk lpSQOS menunjukkan bahwa tidak ada aplikasi yang menyediakan kualitas layanan.
Catatan
Ketika soket yang terhubung berhenti (yaitu, ditutup karena alasan apa pun), soket tersebut harus dibuang dan dibuat ulang. Paling aman untuk berasumsi bahwa ketika semuanya menjadi salah karena alasan apa pun pada soket yang terhubung, klien Winsock SPI harus membuang dan membuat ulang soket yang diperlukan untuk kembali ke titik yang stabil.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 2000 Professional [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows 2000 Server [hanya aplikasi desktop] |
| Header | ws2spi.h |