fungsi connect (winsock2.h)

Artikel
08/27/2023

Fungsi sambungkan menetapkan koneksi ke soket tertentu.

Sintaks

int WSAAPI connect(
  [in] SOCKET         s,
  [in] const sockaddr *name,
  [in] int            namelen
);

Parameter

[in] s

Deskriptor yang mengidentifikasi soket yang tidak terhubung.

[in] name

Penunjuk ke struktur sockaddr tempat koneksi harus dibuat.

[in] namelen

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

Menampilkan nilai

Jika tidak ada kesalahan yang terjadi, sambungkan mengembalikan nol. Jika tidak, ia mengembalikan SOCKET_ERROR, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Pada soket pemblokiran, nilai yang dikembalikan menunjukkan keberhasilan atau kegagalan upaya koneksi.

Dengan soket yang tidak diblokir, upaya koneksi tidak dapat segera diselesaikan. Dalam hal ini, koneksi akan mengembalikan SOCKET_ERROR, dan WSAGetLastError akan mengembalikan WSAEWOULDBLOCK. Dalam hal ini, ada tiga skenario yang mungkin:

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

Sampai upaya koneksi selesai pada soket nonblocking, semua panggilan berikutnya untuk terhubung pada soket yang sama akan gagal dengan kode kesalahan WSAEALREADY, dan WSAEISCONN ketika koneksi berhasil diselesaikan. Karena ambiguitas dalam spesifikasi Windows Sockets versi 1.1, kode kesalahan yang dikembalikan dari koneksi sementara koneksi sudah tertunda dapat bervariasi di antara implementasi. Akibatnya, tidak disarankan agar aplikasi menggunakan beberapa panggilan untuk terhubung guna mendeteksi penyelesaian koneksi. Jika mereka melakukannya, mereka harus siap untuk menangani nilai kesalahan WSAEINVAL dan WSAEWOULDBLOCK dengan cara yang sama seperti yang mereka tangani WSAEALREADY, untuk memastikan operasi yang kuat.

Jika kode kesalahan yang dikembalikan menunjukkan upaya koneksi gagal (yaitu, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) aplikasi dapat memanggil terhubung 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 saat menjalankan ikatan, tetapi dapat ditunda hingga fungsi sambungkan jika ikatan ke alamat kartubebas (INADDR_ANY atau in6addr_any) untuk alamat IP lokal. Alamat tertentu harus secara implisit terikat oleh fungsi sambungkan .
WSAEINTR	Panggilan Windows Socket 1.1 pemblokiran dibatalkan melalui WSACancelBlockingCall.
WSAEINPROGRESS	Panggilan Windows Sockets 1.1 yang diblokir sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEALREADY	Panggilan sambungkan yang tidak diblokir sedang berlangsung pada soket yang ditentukan. Catatan 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 (seperti INADDR_ANY atau in6addr_any) .
WSAEAFNOSUPPORT	Alamat dalam keluarga yang ditentukan tidak dapat digunakan dengan soket ini.
WSAECONNREFUSED	Upaya untuk terhubung ditolak secara paksa.
WSAEFAULT	Struktur sockaddr yang diacu oleh nama berisi format alamat yang salah untuk keluarga alamat terkait atau parameter namelen terlalu kecil. Kesalahan ini juga dikembalikan jika struktur sockaddr yang diacu oleh parameter nama dengan panjang yang ditentukan dalam parameter namelen tidak berada di bagian yang valid dari ruang alamat pengguna.
WSAEINVAL	Parameter adalah soket mendengarkan.
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	Catatan Tidak ada ruang buffer yang tersedia. Soket tidak dapat dihubungkan.
WSAENOTSOCK	Deskriptor yang ditentukan dalam parameter s bukan soket.
WSAETIMEDOUT	Upaya untuk menyambungkan 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 opsi setsockopt SO_BROADCAST tidak diaktifkan.

Keterangan

Fungsi sambungkan digunakan untuk membuat koneksi ke tujuan yang ditentukan. Jika soket 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 asing menggunakan nama (alamat di namespace soket; untuk deskripsi terperinci, lihat ikat dan sockaddr).

Catatan Jika soket dibuka, panggilan setsockopt dilakukan, dan kemudian panggilan sendto dilakukan, Windows Sockets melakukan panggilan fungsi ikatan implisit.

Ketika panggilan soket berhasil diselesaikan, soket siap untuk mengirim dan menerima data. Jika anggota alamat struktur yang ditentukan oleh parameter nama diisi dengan nol, sambungkan akan mengembalikan kesalahan WSAEADDRNOTAVAIL. Setiap upaya untuk menyambungkan kembali koneksi aktif akan gagal dengan kode kesalahan WSAEISCONN.

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 dua cara, tergantung pada bagaimana klien mendaftar untuk pemberitahuan.

Jika klien menggunakan fungsi pilih , keberhasilan dilaporkan dalam set writefds dan kegagalan dilaporkan dalam set exceptfds.
Jika klien menggunakan fungsi WSAAsyncSelect atau WSAEventSelect, pemberitahuan diumumkan dengan FD_CONNECT dan kode kesalahan yang terkait dengan FD_CONNECT menunjukkan keberhasilan atau alasan tertentu untuk kegagalan.

Jika koneksi tidak segera selesai, klien harus menunggu penyelesaian koneksi sebelum mencoba mengatur opsi soket menggunakan setsockopt. Memanggil setsockopt saat koneksi sedang berlangsung tidak didukung.

Untuk soket tanpa koneksi (misalnya, jenis SOCK_DGRAM), operasi yang dilakukan oleh koneksi hanya untuk membuat alamat tujuan default yang dapat digunakan pada panggilanWSASend danWSARecv kirim/ ulang/ berikutnya. Setiap datagram yang diterima dari alamat selain alamat tujuan yang ditentukan akan dibuang. Jika anggota alamat struktur yang ditentukan berdasarkan nama diisi dengan nol, soket akan terputus. Kemudian, alamat jarak jauh default tidak akan ditentukan, jadi kirim/ panggilanWSASend danWSARecv recv / akan mengembalikan kode kesalahan WSAENOTCONN. Namun, sendto/ WSASendTo dan recvfrom/ WSARecvFrom masih dapat digunakan. Tujuan default dapat diubah hanya dengan memanggil sambungkan lagi, bahkan jika soket sudah tersambung. Setiap datagram yang diantrekan untuk tanda terima akan dibuang jika nama berbeda dari koneksi sebelumnya.

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

Ketika koneksi antara soket rusak, soket yang tersambung harus dibuang dan soket baru harus dibuat. Ketika masalah berkembang pada soket yang terhubung, aplikasi harus membuang soket dan membuat soket lagi untuk kembali ke titik stabil.

Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti sambungkan, 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.

Contoh Kode

Contoh berikut menunjukkan penggunaan fungsi sambungkan .

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")

int wmain()
{
    //----------------------
    // Initialize Winsock
    WSADATA wsaData;
    int iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != NO_ERROR) {
        wprintf(L"WSAStartup function failed with error: %d\n", iResult);
        return 1;
    }
    //----------------------
    // Create a SOCKET for connecting to server
    SOCKET ConnectSocket;
    ConnectSocket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (ConnectSocket == INVALID_SOCKET) {
        wprintf(L"socket function failed with error: %ld\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }
    //----------------------
    // The sockaddr_in structure specifies the address family,
    // IP address, and port of the server to be connected to.
    sockaddr_in clientService;
    clientService.sin_family = AF_INET;
    clientService.sin_addr.s_addr = inet_addr("127.0.0.1");
    clientService.sin_port = htons(27015);

    //----------------------
    // Connect to server.
    iResult = connect(ConnectSocket, (SOCKADDR *) & clientService, sizeof (clientService));
    if (iResult == SOCKET_ERROR) {
        wprintf(L"connect function failed with error: %ld\n", WSAGetLastError());
        iResult = closesocket(ConnectSocket);
        if (iResult == SOCKET_ERROR)
            wprintf(L"closesocket function failed with error: %ld\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }

    wprintf(L"Connected to server.\n");

    iResult = closesocket(ConnectSocket);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"closesocket function failed with error: %ld\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }

    WSACleanup();
    return 0;
}

Untuk contoh lain yang menggunakan fungsi sambungkan , lihat Memulai Winsock.

Catatan untuk Soket IrDA

File header Af_irda.h harus disertakan secara eksplisit.
Jika koneksi IrDA yang ada terdeteksi pada tingkat akses media, WSAENETDOWN dikembalikan.
Jika koneksi aktif ke perangkat dengan alamat yang berbeda ada, WSAEADDRINUSE dikembalikan.
Jika soket sudah tersambung atau perubahan mode eksklusif/multipleks gagal, WSAEISCONN dikembalikan.
Jika soket sebelumnya terikat ke nama layanan lokal untuk menerima koneksi masuk menggunakan ikatan, WSAEINVAL dikembalikan. Perhatikan bahwa setelah soket terikat, soket tidak dapat digunakan untuk membuat koneksi keluar.

IrDA mengimplementasikan fungsi koneksi dengan alamat formulir sockaddr_irda. Biasanya, aplikasi klien akan membuat soket dengan fungsi soket, memindai sekitar untuk perangkat IrDA dengan opsi soket IRLMP_ENUMDEVICES, memilih perangkat dari daftar yang dikembalikan, membentuk alamat, lalu memanggil koneksi. Tidak ada perbedaan antara semantik pemblokiran dan pemblokiran.

Persyaratan


Klien minimum yang didukung	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