Bagikan melalui


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.

Catatan Pada Windows 7, Windows Server 2008 R2, dan yang lebih lama, fungsi WSAConnectByName memerlukan soket yang tidak terikat dan tidak tersambung. Ini berbeda dari panggilan Winsock lainnya untuk membuat koneksi (misalnya, WSAConnect).
 

[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
WSAEHOSTUNREACH
Host diteruskan sebagai parameter nodename tidak dapat dijangkau.
WSAEINVAL
Parameter yang tidak valid diteruskan ke fungsi. Nodename atau parameter servicename tidak boleh NULL. Parameter Yang Dicadangkan harus NULL.
WSAENOBUFS
Memori yang cukup tidak dapat dialokasikan.
WSAENOTSOCK
Soket yang tidak valid diteruskan ke fungsi. Parameter s tidak boleh INVALID_SOCKET atau NULL.
WSAETIMEDOUT
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 );

Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti WSAConnectByName dengan parameter batas waktu yang diatur ke NULL, 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.
 
Windows Phone 8: Fungsi WSAConnectByNameW didukung untuk aplikasi Windows Phone Store di Windows Phone 8 dan yang lebih baru.

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

Lihat juga

Opsi Soket IPPROTO_IPV6

SOCKADDR

WSAConnect

WSAConnectByList

WSAGetLastError

getaddrinfo

getpeername

getsockname

setsockopt