Fungsi panggilan balik LPWSPCONNECT (ws2spi.h)

Artikel
08/28/2023

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
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 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.
WSAEINTR	(Pemblokiran) panggilan dibatalkan melalui LPWSPCancelBlockingCall.
WSAEINPROGRESS	Pemblokiran panggilan Winsock sedang berlangsung atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEALREADY	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.
WSAEADDRNOTAVAIL	Alamat jarak jauh bukan alamat yang valid (misalnya, 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 s adalah soket mendengarkan.
WSAEISCONN	Soket sudah terhubung (hanya soket berorientasi koneksi).
WSAENETUNREACH	Jaringan tidak dapat dijangkau dari host ini saat ini.
WSAENOBUFS	Tidak ada ruang buffer yang tersedia. Soket tidak dapat dihubungkan.
WSAENOTSOCK	Deskriptor bukan soket.
WSAEOPNOTSUPP	Spesifikasi alur yang ditentukan dalam lpSQOS tidak dapat dipenuhi.
WSAEPROTONOSUPPORT	Augment lpCallerData tidak didukung oleh penyedia layanan.
WSAETIMEDOUT	Upaya untuk menyambungkan kehabisan waktu tanpa membuat koneksi.
WSAEWOULDBLOCK	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.
WSAEACCES	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