Fungsi WSAConnectByNameA (winsock2.h)
Fungsi WSAConnectByName membuat koneksi ke host dan port tertentu. Fungsi ini disediakan untuk memungkinkan koneksi cepat ke titik akhir jaringan yang diberi nama host dan port.
Fungsi ini mendukung alamat IPv4 dan IPv6.
Sintaks
BOOL WSAConnectByNameA(
[in] SOCKET s,
[in] LPCSTR nodename,
[in] LPCSTR servicename,
[in, out] LPDWORD LocalAddressLength,
[out] LPSOCKADDR LocalAddress,
[in, out] LPDWORD RemoteAddressLength,
[out] LPSOCKADDR RemoteAddress,
[in] const timeval *timeout,
LPWSAOVERLAPPED Reserved
);
Parameter
[in] s
Deskriptor yang mengidentifikasi soket yang tidak terhubung.
[in] nodename
String yang dihentikan NULL yang berisi nama host atau alamat IP host yang akan disambungkan untuk IPv4 atau IPv6.
[in] servicename
String yang dihentikan NULL yang berisi nama layanan atau port tujuan host yang akan disambungkan untuk IPv4 atau IPv6.
Nama layanan adalah alias string untuk nomor port. Misalnya, "http" adalah alias untuk port 80 yang ditentukan oleh Internet Engineering Task Force (IETF) sebagai port default yang digunakan oleh server web untuk protokol HTTP. Nilai yang mungkin untuk parameter servicename ketika nomor port tidak ditentukan tercantum dalam file berikut:
%WINDIR%\system32\drivers\etc\services
[in, out] LocalAddressLength
Pada input, penunjuk ke ukuran, dalam byte, dari buffer LocalAddress yang disediakan oleh pemanggil. Pada output, pointer ke ukuran, dalam byte, dari SOCKADDR untuk alamat lokal yang disimpan di buffer LocalAddress yang diisi oleh sistem setelah berhasil menyelesaikan panggilan.
[out] LocalAddress
Penunjuk ke struktur SOCKADDR yang menerima alamat lokal koneksi. Ukuran parameter persis dengan ukuran yang dikembalikan di LocalAddressLength. Ini adalah informasi yang sama yang akan dikembalikan oleh fungsi getsockname . Parameter ini dapat berupa NULL, dalam hal ini, parameter LocalAddressLength diabaikan.
[in, out] RemoteAddressLength
Pada input, penunjuk ke ukuran, dalam byte, dari buffer RemoteAddress yang disediakan oleh pemanggil. Pada output, pointer ke ukuran, dalam byte, dari SOCKADDR untuk alamat jarak jauh yang disimpan dalam buffer RemoteAddress yang diisi oleh sistem setelah berhasil menyelesaikan panggilan.
[out] RemoteAddress
Penunjuk ke struktur SOCKADDR yang menerima alamat jarak jauh koneksi. Ini adalah informasi yang sama yang akan dikembalikan oleh fungsi getpeername . Parameter ini dapat berupa NULL, dalam hal ini, RemoteAddressLength diabaikan.
[in] timeout
Waktu, dalam milidetik, untuk menunggu respons dari aplikasi jarak jauh sebelum membatalkan panggilan.
Reserved
Disediakan untuk implementasi di masa mendatang. Parameter ini harus diatur ke NULL.
Nilai kembali
Jika koneksi dibuat, WSAConnectByName mengembalikan parameter TRUE dan LocalAddress dan RemoteAddress diisi jika buffer ini disediakan oleh pemanggil.
Jika panggilan gagal, FALSE dikembalikan. WSAGetLastError kemudian dapat dipanggil untuk mendapatkan informasi kesalahan yang diperluas.
| Menampilkan kode | Deskripsi |
|---|---|
|
Host diteruskan sebagai parameter nodename tidak dapat dijangkau. |
|
Parameter yang tidak valid diteruskan ke fungsi. Nodename atau parameter servicename tidak boleh NULL. Parameter Yang Dicadangkan harus NULL. |
|
Memori yang cukup tidak dapat dialokasikan. |
|
Soket yang tidak valid diteruskan ke fungsi. Parameter s tidak boleh INVALID_SOCKET atau NULL. |
|
Respons dari aplikasi jarak jauh tidak diterima sebelum parameter batas waktu terlampaui. |
Keterangan
WSAConnectByName disediakan untuk mengaktifkan koneksi cepat dan transparan ke host jarak jauh pada port tertentu. Ini kompatibel dengan versi IPv6 dan IPv4.
Untuk mengaktifkan komunikasi IPv6 dan IPv4, gunakan metode berikut:
- Fungsi setsockopt harus dipanggil pada soket yang dibuat untuk keluarga alamat AF_INET6 untuk menonaktifkan opsi soket IPV6_V6ONLY sebelum memanggil WSAConnectByName. Ini dicapai dengan memanggil fungsi setsockopt pada soket dengan parameter tingkat yang diatur ke IPPROTO_IPV6 (lihat IPPROTO_IPV6 Opsi Soket), parameter optname diatur ke IPV6_V6ONLY, dan nilai parameter optvalue diatur ke nol .
WSAConnectByName memiliki batasan: Ini hanya berfungsi untuk soket berorientasi koneksi, seperti jenis SOCK_STREAM. Fungsi ini tidak mendukung perilaku I/O atau non-pemblokiran yang tumpang tindih. WSAConnectByName akan memblokir meskipun soket dalam mode non-pemblokiran.
WSAConnectByName tidak mendukung data yang disediakan pengguna selama pembentukan koneksi. Panggilan ini juga tidak mendukung struktur FLOWSPEC. Dalam kasus di mana fitur-fitur ini diperlukan, WSAConnect harus digunakan sebagai gantinya.
Dalam versi sebelum Windows 10, jika aplikasi perlu mengikat ke alamat atau port lokal tertentu, maka WSAConnectByName tidak dapat digunakan karena parameter soket ke WSAConnectByName harus merupakan soket yang tidak terikat.
Pembatasan ini dihapus Windows 10.
Parameter RemoteAddress dan LocalAddress menunjuk ke struktur SOCKADDR , yang merupakan jenis data generik. Ketika WSAConnectByName dipanggil, diharapkan bahwa jenis alamat soket khusus untuk protokol jaringan atau keluarga alamat yang digunakan akan benar-benar diteruskan dalam parameter ini. Jadi untuk alamat IPv4, pointer ke struktur sockaddr_in akan ditransmisikan ke pointer ke SOCKADDR sebagai parameter RemoteAddress dan LocalAddress . Untuk alamat IPv6, pointer ke struktur sockaddr_in6 akan ditransmisikan ke pointer ke SOCKADDR sebagai parameter RemoteAddress dan LocalAddress .
Ketika fungsi WSAConnectByName mengembalikan TRUE, soket berada dalam status default untuk soket yang tersambung. Soket tidak mengaktifkan properti atau opsi yang ditetapkan 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 );
Windows 8.1 dan Windows Server 2012 R2: Fungsi WSAConnectByNameW didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.
Contoh
Buat koneksi menggunakan WSAConnectByName.
#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <mswsock.h> // Need for SO_UPDATE_CONNECT_CONTEXT
#include <stdio.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
SOCKET
OpenAndConnect(LPWSTR NodeName, LPWSTR PortName)
{
SOCKET ConnSocket = INVALID_SOCKET;
int ipv6only = 0;
int iResult;
BOOL bSuccess;
SOCKADDR_STORAGE LocalAddr = {0};
SOCKADDR_STORAGE RemoteAddr = {0};
DWORD dwLocalAddr = sizeof(LocalAddr);
DWORD dwRemoteAddr = sizeof(RemoteAddr);
ConnSocket = socket(AF_INET6, SOCK_STREAM, 0);
if (ConnSocket == INVALID_SOCKET){
wprintf(L"socket failed with error: %d\n", WSAGetLastError());
return INVALID_SOCKET;
}
iResult = setsockopt(ConnSocket, IPPROTO_IPV6,
IPV6_V6ONLY, (char*)&ipv6only, sizeof(ipv6only) );
if (iResult == SOCKET_ERROR){
wprintf(L"setsockopt for IPV6_V6ONLY failed with error: %d\n",
WSAGetLastError());
closesocket(ConnSocket);
return INVALID_SOCKET;
}
bSuccess = WSAConnectByName(ConnSocket, NodeName,
PortName, &dwLocalAddr,
(SOCKADDR*)&LocalAddr,
&dwRemoteAddr,
(SOCKADDR*)&RemoteAddr,
NULL,
NULL);
if (!bSuccess){
wprintf(L"WsaConnectByName failed with error: %d\n", WSAGetLastError());
closesocket(ConnSocket);
return INVALID_SOCKET;
}
iResult = setsockopt(ConnSocket, SOL_SOCKET,
SO_UPDATE_CONNECT_CONTEXT, NULL, 0);
if (iResult == SOCKET_ERROR){
wprintf(L"setsockopt for SO_UPDATE_CONNECT_CONTEXT failed with error: %d\n",
WSAGetLastError());
closesocket(ConnSocket);
return INVALID_SOCKET;
}
return ConnSocket;
}
int __cdecl wmain(int argc, wchar_t **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
SOCKET s = INVALID_SOCKET;
// Validate the parameters
if (argc != 3) {
wprintf(L"usage: %ws <Nodename> <Portname>\n", argv[0]);
wprintf(L"wsaconnectbyname establishes a connection to a specified host and port.\n");
wprintf(L"%ws www.contoso.com 8080\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
wprintf(L"WSAStartup failed: %d\n", iResult);
return 1;
}
wprintf(L"WsaConnectByName with following parameters:\n");
wprintf(L"\tNodename = %ws\n", argv[1]);
wprintf(L"\tPortname (or port) = %ws\n\n", argv[2]);
//--------------------------------
// Call our function that uses the WsaConnectByName.
s = OpenAndConnect(argv[1], argv[2]);
if ( s == INVALID_SOCKET ) {
wprintf(L"WsaConnectByName failed with error: %d\n", WSAGetLastError());
WSACleanup();
return 1;
}
else
{
wprintf(L"WsaConnectByName succeeded\n");
closesocket(s);
WSACleanup();
return 0;
}
}
Catatan
Header winsock2.h mendefinisikan WSAConnectByName sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 8.1, Windows Vista [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2008 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | winsock2.h |
| Pustaka | Ws2_32.lib |
| DLL | Ws2_32.dll |