LPFN_CONNECTEX fungsi panggilan balik (mswsock.h)

Artikel
08/25/2023

Fungsi ConnectEx membuat koneksi ke soket tertentu, dan secara opsional mengirim data setelah koneksi dibuat. Fungsi ConnectEx hanya didukung pada soket berorientasi koneksi.

Catatan Fungsi ini adalah ekstensi khusus Microsoft untuk spesifikasi Windows Sockets.

Sintaks

LPFN_CONNECTEX LpfnConnectex;

BOOL LpfnConnectex(
  [in]           SOCKET s,
  [in]           const sockaddr *name,
  [in]           int namelen,
  [in, optional] PVOID lpSendBuffer,
  [in]           DWORD dwSendDataLength,
  [out]          LPDWORD lpdwBytesSent,
  [in]           LPOVERLAPPED lpOverlapped
)
{...}

Parameter

[in] s

Deskriptor yang mengidentifikasi soket yang tidak terhubung dan sebelumnya terikat. Lihat Keterangan untuk informasi selengkapnya.

[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 aliran IPv6 tambahan dan informasi id cakupan.

[in] namelen

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

[in, optional] lpSendBuffer

Penunjuk ke buffer yang akan ditransfer setelah koneksi dibuat. Parameter ini bersifat opsional. Jika opsi TCP_FASTOPEN diaktifkan pada s sebelum ConnectEx dipanggil, maka beberapa data ini dapat dikirim selama pembentukan koneksi.

[in] dwSendDataLength

Panjang, dalam byte, data yang diacu oleh parameter lpSendBuffer . Parameter ini diabaikan ketika parameter lpSendBuffer adalah NULL.

[out] lpdwBytesSent

Saat pengembalian berhasil, parameter ini menunjuk ke nilai DWORD yang menunjukkan jumlah byte yang dikirim setelah koneksi dibuat. Byte yang dikirim berasal dari buffer yang diacu oleh parameter lpSendBuffer . Parameter ini diabaikan ketika parameter lpSendBuffer adalah NULL.

[in] lpOverlapped

Struktur TUMPANG TINDIH yang digunakan untuk memproses permintaan. Parameter lpOverlapped harus ditentukan, dan tidak boleh NULL.

Nilai kembali

Jika berhasil, fungsi ConnectEx mengembalikan TRUE. Jika gagal, fungsi mengembalikan FALSE. Gunakan fungsi WSAGetLastError untuk mendapatkan informasi kesalahan yang diperluas. Jika panggilan ke fungsi WSAGetLastError mengembalikan ERROR_IO_PENDING, operasi berhasil dimulai dan sedang berlangsung. Dalam keadaan seperti itu, panggilan mungkin masih gagal ketika operasi yang tumpang tindih selesai.

Jika kode kesalahan yang dikembalikan adalah WSAECONNREFUSED, WSAENETUNREACH, atau WSAETIMEDOUT, aplikasi dapat memanggil ConnectEx, WSAConnect, atau terhubung lagi pada soket yang sama.

Kode kesalahan	Deskripsi
WSANOTINITIALISED	Panggilan fungsi WSAStartup yang berhasil harus terjadi sebelum menggunakan ConnectEx.
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 operasi pengikatan , tetapi kesalahan dapat tertunda hingga panggilan fungsi ConnectEx , jika fungsi ikatan dipanggil dengan alamat kartubebas (INADDR_ANY atau in6addr_any) yang ditentukan untuk alamat IP lokal. Alamat IP tertentu harus terikat secara implisit oleh fungsi ConnectEx .
WSAEALREADY	Panggilan fungsi connect, WSAConnect, atau ConnectEx yang tidak diblokir sedang berlangsung pada soket yang ditentukan.
WSAEADDRNOTAVAIL	Alamat jarak jauh bukan alamat yang valid, seperti ADDR_ANY (fungsi ConnectEx hanya didukung untuk soket berorientasi koneksi).
WSAEAFNOSUPPORT	Alamat dalam keluarga yang ditentukan tidak dapat digunakan dengan soket ini.
WSAECONNREFUSED	Upaya untuk tersambung ditolak.
WSAEFAULT	Nama,lpSendBuffer, atau parameter lpOverlapped bukan bagian yang valid dari ruang alamat pengguna, atau namelen terlalu kecil.
WSAEINVAL	Parameter s adalah soket yang tidak terikat atau mendengarkan.
WSAEISCONN	Soket sudah tersambung.
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.
WSAETIMEDOUT	Upaya untuk menyambungkan kehabisan waktu tanpa membuat koneksi.

Keterangan

Fungsi ConnectEx menggabungkan beberapa fungsi soket ke dalam satu transisi API/kernel. Operasi berikut dilakukan saat panggilan ke fungsi ConnectEx berhasil diselesaikan:

Koneksi baru dibuat.
Blok data opsional dikirim setelah koneksi dibuat.

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

Fungsi ConnectEx hanya dapat digunakan dengan soket berorientasi koneksi. Soket yang diteruskan dalam parameter s harus dibuat dengan jenis soket SOCK_STREAM, SOCK_RDM, atau SOCK_SEQPACKET.

Parameter lpSendBuffer menunjuk ke buffer data untuk dikirim setelah koneksi dibuat. Parameter dwSendDataLength menentukan panjang byte data ini untuk dikirim. Aplikasi dapat meminta untuk mengirim buffer besar data menggunakan ConnectEx dengan cara yang sama seperti fungsi kirim dan WSASend dapat digunakan. Tetapi pengembang sangat disarankan untuk tidak mengirim buffer besar dalam satu panggilan menggunakan ConnectEx, karena operasi ini menggunakan sejumlah besar sumber daya memori sistem sampai seluruh buffer telah dikirim.

Jika fungsi ConnectEx berhasil, koneksi dibuat dan semua data yang diacu oleh parameter lpSendBuffer dikirim ke alamat yang ditentukan dalam struktur sockaddr yang diacu oleh parameter nama .

Catatan Penunjuk fungsi untuk fungsi ConnectEx harus diperoleh pada durasi dengan melakukan panggilan ke fungsi WSAIoctl dengan opcode SIO_GET_EXTENSION_FUNCTION_POINTER yang ditentukan. Buffer input yang diteruskan ke fungsi WSAIoctl harus berisi WSAID_CONNECTEX, pengidentifikasi unik global (GUID) yang nilainya mengidentifikasi fungsi ekstensi ConnectEx . Jika berhasil, output yang dikembalikan oleh fungsi WSAIoctl berisi penunjuk ke fungsi ConnectEx . GUID WSAID_CONNECTEX didefinisikan dalam file header Mswsock.h .

Fungsi ConnectEx menggunakan I/O yang tumpang tindih. Akibatnya, fungsi ConnectEx memungkinkan aplikasi untuk melayani sejumlah besar klien dengan utas yang relatif sedikit. Sebaliknya, fungsi WSAConnect , yang tidak menggunakan I/O yang tumpang tindih, biasanya memerlukan utas terpisah untuk melayani setiap permintaan koneksi saat permintaan simultan diterima.

Catatan Semua I/O yang dimulai oleh utas tertentu dibatalkan ketika utas tersebut keluar. Untuk soket yang tumpang tindih, operasi asinkron yang tertunda dapat gagal jika utas ditutup sebelum operasi selesai. Lihat ExitThread untuk informasi selengkapnya.

Soket berorientasi koneksi sering kali tidak dapat menyelesaikan koneksi mereka segera, dan oleh karena itu operasi dimulai dan fungsi segera kembali dengan kesalahan ERROR_IO_PENDING atau WSA_IO_PENDING. Ketika operasi koneksi selesai dan keberhasilan atau kegagalan tercapai, status dilaporkan menggunakan mekanisme pemberitahuan penyelesaian yang ditunjukkan dalam lpOverlapped. Seperti semua panggilan fungsi yang tumpang tindih, Anda dapat menggunakan peristiwa atau port penyelesaian sebagai mekanisme pemberitahuan penyelesaian. Parameter lpNumberOfBytesTransferred dari fungsi GetQueuedCompletionStatus atau GetOverlappedResult atau WSAGetOverlappedResult menunjukkan jumlah byte yang dikirim dalam permintaan.

Ketika fungsi ConnectEx berhasil diselesaikan , handel soket hanya dapat diteruskan ke fungsi berikut:

Jika fungsi TransmitFile dipanggil pada soket yang terhubung sebelumnya dengan bendera TF_DISCONNECT dan TF_REUSE_SOCKET, soket yang ditentukan dikembalikan ke keadaan di mana tidak tersambung, tetapi masih terikat. Dalam kasus seperti itu, handel soket dapat diteruskan ke fungsi ConnectEx dalam parameter s , tetapi soket tidak dapat digunakan kembali dalam panggilan fungsi AcceptEx . Demikian pula, soket yang diterima digunakan kembali menggunakan fungsi TransmitFile tidak dapat digunakan dalam panggilan ke ConnectEx. Perhatikan bahwa dalam kasus soket yang digunakan kembali, ConnectEx tunduk pada perilaku transportasi yang mendasar. Misalnya, soket TCP dapat tunduk pada status TIME_WAIT TCP, menyebabkan panggilan ConnectEx tertunda.

Saat fungsi ConnectEx mengembalikan TRUE, soket berada dalam status default untuk soket yang tersambung. Soket tidak mengaktifkan properti atau opsi yang diatur sebelumnya hingga SO_UPDATE_CONNECT_CONTEXT diatur pada soket. Gunakan fungsi setsockopt untuk mengatur opsi SO_UPDATE_CONNECT_CONTEXT.

Contohnya:

//Need to #include <mswsock.h> for SO_UPDATE_CONNECT_CONTEXT

int iResult = 0;

iResult = setsockopt( s, SOL_SOCKET, SO_UPDATE_CONNECT_CONTEXT, NULL, 0 );

Fungsi getsockopt dapat digunakan dengan opsi soket SO_CONNECT_TIME untuk memeriksa apakah koneksi telah dibuat saat ConnectEx sedang berlangsung. Jika koneksi telah dibuat, nilai yang dikembalikan dalam parameter optval yang diteruskan ke fungsi getsockopt adalah jumlah detik soket telah tersambung. Jika soket tidak tersambung, parameter optval yang dikembalikan berisi 0xFFFFFFFF. Memeriksa koneksi dengan cara ini diperlukan untuk menentukan apakah koneksi telah dibuat untuk jangka waktu tertentu tanpa mengirim data apa pun; dalam kasus seperti itu, disarankan agar koneksi tersebut dihentikan.

Contohnya:


//Need to #include <mswsock.h> for SO_CONNECT_TIME

int seconds;
int bytes = sizeof(seconds);
int iResult = 0;

iResult = getsockopt( s, SOL_SOCKET, SO_CONNECT_TIME,
                      (char *)&seconds, (PINT)&bytes );
if ( iResult != NO_ERROR ) {
    printf( "getsockopt(SO_CONNECT_TIME) failed with error: %u\n", 
        WSAGetLastError() );
}
else {
    if (seconds == 0xFFFFFFFF)
        printf("Connection not established yet\n");
    else
       printf("Connection has been established %ld seconds\n",
           seconds);
}

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

Jika parameter alamat struktur sockaddr yang ditunjukkan dalam parameter nama adalah semua nol, ConnectEx mengembalikan kesalahan WSAEADDRNOTAVAIL. Setiap upaya untuk menyambungkan kembali koneksi aktif akan gagal dengan kode kesalahan WSAEISCONN.

Ketika soket yang terhubung ditutup karena alasan apa pun, disarankan agar soket dibuang dan soket baru dibuat. Alasan untuk ini adalah bahwa paling aman untuk mengasumsikan bahwa ketika semuanya menjadi salah pada soket yang terhubung karena alasan apa pun, aplikasi harus membuang soket dan membuat soket yang diperlukan lagi untuk kembali ke titik yang stabil.

Jika fungsi DisconnectEx dipanggil dengan bendera TF_REUSE_SOCKET , soket yang ditentukan dikembalikan ke status di mana tidak tersambung, tetapi masih terikat. Dalam kasus seperti itu, handel soket dapat diteruskan ke fungsi ConnectEx dalam parameter s .

Interval waktu yang harus berlalu sebelum TCP dapat melepaskan koneksi tertutup dan menggunakan kembali sumber dayanya dikenal sebagai status TIME_WAIT atau status 2MSL. Selama waktu ini, koneksi dapat dibuka kembali dengan biaya yang jauh lebih sedikit ke klien dan server daripada membuat koneksi baru.

Perilaku TIME_WAIT ditentukan dalam RFC 793, yang mengharuskan TCP mempertahankan koneksi tertutup untuk interval setidaknya sama dengan dua kali masa pakai segmen maksimum (MSL) jaringan. Ketika koneksi dirilis, pasangan soket dan sumber daya internalnya yang digunakan untuk soket dapat digunakan untuk mendukung koneksi lain.

TCP Windows kembali ke status TIME_WAIT berikutnya ke penutupan koneksi. Saat dalam status TIME_WAIT, pasangan soket tidak dapat digunakan kembali. Periode TIME_WAIT dapat dikonfigurasi dengan memodifikasi pengaturan registri DWORD berikut yang mewakili periode TIME_WAIT dalam hitungan detik.

\ HKEY_LOCAL_MACHINESistem\CurrentControlSet\Layanan\TCPIP\Parameter\TcpTimedWaitDelay

Secara default, MSL didefinisikan menjadi 120 detik. Pengaturan registri TcpTimedWaitDelay default ke nilai 240 detik, yang mewakili 2 kali masa pakai segmen maksimum 120 detik atau 4 menit. Namun, Anda dapat menggunakan entri ini untuk menyesuaikan interval.

Mengurangi nilai entri ini memungkinkan TCP untuk melepaskan koneksi tertutup lebih cepat, menyediakan lebih banyak sumber daya untuk koneksi baru. Namun, jika nilainya terlalu rendah, TCP mungkin merilis sumber daya koneksi sebelum koneksi selesai, mengharuskan server menggunakan sumber daya tambahan untuk membuat ulang koneksi.

Pengaturan registri ini dapat diatur dari 0 hingga 300 detik.

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