Fungsi panggilan balik LPWSPACCEPT (ws2spi.h)

Artikel
03/15/2023

Fungsi LPWSPAccept secara kondisional menerima koneksi berdasarkan nilai pengembalian fungsi kondisi.

Sintaks

LPWSPACCEPT Lpwspaccept;

SOCKET Lpwspaccept(
  [in]      SOCKET s,
  [out]     sockaddr *addr,
  [in, out] LPINT addrlen,
  [in]      LPCONDITIONPROC lpfnCondition,
  [in]      DWORD_PTR dwCallbackData,
  [out]     LPINT lpErrno
)
{...}

Parameter

[in] s

Deskriptor mengidentifikasi soket yang mendengarkan koneksi setelah LPWSPListen.

[out] addr

Penunjuk opsional ke buffer yang menerima alamat entitas penghubung, seperti yang diketahui oleh penyedia layanan. Format parameter addr yang tepat ditentukan oleh keluarga alamat yang ditetapkan ketika soket dalam struktur sockaddr dibuat.

[in, out] addrlen

Penunjuk opsional ke bilangan bulat yang berisi panjang parameter addr , dalam byte.

[in] lpfnCondition

Alamat instans prosedur dari fungsi kondisi opsional yang dilengkapi oleh Windows Sockets. Fungsi ini digunakan dalam keputusan terima atau tolak berdasarkan informasi penelepon yang diteruskan sebagai parameter.

[in] dwCallbackData

Data panggilan balik untuk diteruskan kembali ke klien Windows Socket 2 sebagai nilai parameter dwCallbackData dari fungsi kondisi. Parameter ini tidak ditafsirkan oleh penyedia layanan.

[out] lpErrno

Arahkan ke kode kesalahan.

Mengembalikan nilai

Jika tidak ada kesalahan yang terjadi, LPWSPAccept mengembalikan nilai jenis SOCKET yang merupakan deskriptor untuk soket yang diterima. Jika tidak, nilai INVALID_SOCKET dikembalikan, dan kode kesalahan tertentu tersedia di lpErrno.

Kode Kesalahan	Makna
WSAECONNREFUSED	Permintaan koneksi ditolak secara paksa seperti yang ditunjukkan dalam nilai pengembalian fungsi kondisi (CF_REJECT).
WSAECONNRESET	Koneksi masuk ditunjukkan, tetapi kemudian dihentikan oleh peer jarak jauh sebelum menerima panggilan.
WSAENETDOWN	Subsistem jaringan gagal.
WSAEFAULT	Parameter addrlen terlalu kecil atau parameter lpfnCondition bukan bagian dari ruang alamat pengguna.
WSAEINTR	Panggilan (pemblokiran) dibatalkan melalui LPWSPCancelBlockingCall.
WSAEINPROGRESS	Panggilan Windows Sockets pemblokiran sedang berlangsung.
WSAEINVAL	LPWSPListen tidak dipanggil sebelum LPWSPAccept, parameter g yang ditentukan dalam fungsi kondisi bukan nilai yang valid, nilai yang dikembalikan dari fungsi kondisi bukan yang valid, atau kasus apa pun di mana soket yang ditentukan dalam keadaan tidak valid.
WSAEMFILE	Antrean tidak ada gunanya saat masuk ke LPWSPAccept dan tidak ada deskriptor soket yang tersedia.
WSAENOBUFS	Tidak ada ruang buffer yang tersedia.
WSAENOTSOCK	Deskriptor bukan soket.
WSAEOPNOTSUPP	Soket yang direferensikan bukan jenis yang mendukung layanan berorientasi koneksi.
WSATRY_AGAIN	Penerimaan permintaan koneksi ditangguhkan seperti yang ditunjukkan dalam nilai pengembalian fungsi kondisi (CF_DEFER).
WSAEWOULDBLOCK	Soket ditandai sebagai nonblocking dan tidak ada koneksi yang akan diterima.
WSAEACCES	Permintaan koneksi yang ditawarkan telah kehabisan waktu atau ditarik.

Keterangan

Fungsi LPWSPAccept mengekstrak koneksi pertama pada antrean koneksi yang tertunda pada soket , dan memeriksanya terhadap fungsi kondisi, asalkan fungsi kondisi ditentukan (yaitu, bukan null). Fungsi kondisi harus dijalankan dalam utas yang sama dengan rutinitas ini. Jika fungsi kondisi mengembalikan CF_ACCEPT, LPWSPAccept membuat soket baru.

Soket yang baru dibuat memiliki properti yang sama dengan soket , termasuk peristiwa jaringan yang terdaftar di LPWSPAsyncSelect atau dengan LPWSPEventSelect. Seperti yang dijelaskan dalam DescriptorAllocation, ketika deskriptor soket baru dialokasikan, penyedia IFS harus memanggil penyedia WPUModifyIFSHandle dan non-IFS harus memanggil WPUCreateSocketHandle.

Jika fungsi kondisi mengembalikan CF_REJECT, LPWSPAccept menolak permintaan koneksi. Jika keputusan terima/tolak aplikasi tidak dapat segera dibuat, fungsi kondisi akan mengembalikan CF_DEFER untuk menunjukkan bahwa tidak ada keputusan yang dibuat. Tidak ada tindakan tentang permintaan koneksi ini yang akan diambil oleh penyedia layanan. Ketika aplikasi siap untuk mengambil tindakan pada permintaan koneksi, aplikasi akan memanggil LPWSPAccept lagi dan mengembalikan CF_ACCEPT atau CF_REJECT sebagai nilai pengembalian dari fungsi kondisi.

Untuk soket yang berada dalam mode pemblokiran (default), jika tidak ada koneksi yang tertunda yang ada pada antrean, LPWSPAccept memblokir pemanggil hingga koneksi ada. Untuk soket dalam mode nonblocking, jika fungsi ini dipanggil ketika tidak ada koneksi yang tertunda yang ada pada antrean, LPWSPAccept mengembalikan kode kesalahan WSAEWOULDBLOCK. Soket yang diterima tidak dapat digunakan untuk menerima lebih banyak koneksi. Soket asli tetap terbuka.

Addr parameter adalah parameter hasil yang diisi dengan alamat entitas penghubung, seperti yang diketahui oleh penyedia layanan. Format parameter addr yang tepat ditentukan oleh keluarga alamat tempat komunikasi terjadi. Addrlen adalah parameter hasil nilai; awalnya akan berisi jumlah ruang yang ditujukan oleh addr. Saat dikembalikan, alamat harus berisi panjang aktual (dalam byte) alamat yang dikembalikan oleh penyedia layanan. Panggilan ini digunakan dengan jenis soket berorientasi koneksi seperti SOCK_STREAM. Jika addr dan/atau addrlen sama dengan null, maka tidak ada informasi tentang alamat jarak jauh soket yang diterima yang dikembalikan. Jika tidak, kedua parameter ini akan diisi terlepas dari apakah fungsi kondisi ditentukan atau apa yang dikembalikannya.

Prototipe fungsi kondisi adalah sebagai berikut.

int CALLBACK 
ConditionFunc( 
  IN     LPWSABUF    lpCallerId, 
  IN     LPWSABUF    lpCallerData, 
  IN OUT LPQOS       lpSQOS, 
  IN OUT LPQOS       lpGQOS,
  IN     LPWSABUF    lpCalleeId, 
  IN     LPWSABUF    lpCalleeData, 
  OUT    GROUP FAR * g, 	
  IN     DWORD_PTR   dwCallbackData
);

lpCallerId dan lpCallerData adalah parameter nilai yang harus berisi alamat entitas penghubung dan data pengguna apa pun yang dikirim bersama dengan permintaan koneksi. Jika tidak ada pengidentifikasi penelepon atau data penelepon yang tersedia, parameter yang sesuai akan null. Banyak protokol jaringan tidak mendukung data pemanggil waktu sambung. Sebagian besar protokol jaringan konvensional dapat diharapkan untuk mendukung informasi pengidentifikasi penelepon pada waktu permintaan koneksi. Bagian buf dari WSABUF yang diacu oleh lpCallerId menunjuk ke sockaddr. Sockaddr ditafsirkan sesuai dengan keluarga alamatnya (biasanya dengan mentransmisikan sockaddr ke beberapa jenis khusus untuk keluarga alamat).

Parameter lpSQOS mereferensikan spesifikasi alur untuk soket yang ditentukan oleh pemanggil, satu untuk setiap arah, diikuti oleh parameter khusus penyedia tambahan. Nilai spesifikasi alur pengiriman atau penerimaan akan diabaikan sebagaimana mestinya untuk soket satu arah. Nilai null untuk lpSQOS menunjukkan bahwa tidak ada QoS yang disediakan penelepon dan tidak ada negosiasi yang dimungkinkan. Penunjuk lpSQOSnon-NULL menunjukkan bahwa negosiasi QoS akan terjadi atau bahwa penyedia siap untuk menerima permintaan QoS tanpa negosiasi.

lpCalleeId adalah parameter nilai yang berisi alamat lokal entitas yang terhubung. Bagian buf dari WSABUF yang ditunjukkan oleh lpCalleeId menunjuk ke sockaddr. Sockaddr ditafsirkan sesuai dengan keluarga alamatnya (biasanya dengan mentransmisikan sockaddr ke beberapa jenis khusus untuk keluarga alamat).

lpCalleeData adalah parameter hasil yang digunakan oleh fungsi kondisi untuk menyediakan data pengguna kembali ke entitas penghubung. Penyimpanan untuk data ini harus disediakan oleh penyedia layanan. lpCalleeData-len> awalnya berisi panjang buffer yang dialokasikan oleh penyedia layanan dan ditunjukkan oleh lpCalleeData-buf.> Nilai nol berarti meneruskan data pengguna kembali ke pemanggil tidak didukung. Fungsi kondisi akan menyalin hingga lpCalleeData-len> byte data kelpCalleeData-buf>, lalu memperbaruilpCalleeData-len> untuk menunjukkan jumlah byte aktual yang ditransfer. Jika tidak ada data pengguna yang akan diteruskan kembali ke pemanggil, fungsi kondisi akan mengatur lpCalleeData-len> ke nol. Format semua alamat dan data pengguna khusus untuk keluarga alamat tempat soket berada.

Nilai parameter dwCallbackData yang diteruskan ke fungsi kondisi adalah nilai yang diteruskan sebagai parameter dwCallbackData dalam panggilan LPWSPAccept asli. Nilai ini hanya ditafsirkan oleh klien Windows Sockets 2. Ini memungkinkan klien untuk meneruskan beberapa informasi konteks dari situs panggilan LPWSPAccept ke fungsi kondisi, yang menyediakan fungsi kondisi dengan informasi tambahan yang diperlukan untuk menentukan apakah akan menerima koneksi. Penggunaan umumnya adalah meneruskan penunjuk (pemeran yang cocok) ke struktur data yang berisi referensi ke objek yang ditentukan aplikasi yang terkait dengan soket ini.

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	ws2spi.h