fungsi bind (winsock.h)

Artikel
03/04/2024

Fungsi ikatan mengaitkan alamat lokal dengan soket.

Sintaks

int bind(
  [in] SOCKET         s,
       const sockaddr *addr,
  [in] int            namelen
);

Parameter

[in] s

Deskriptor yang mengidentifikasi soket yang tidak terikat.

addr

Penunjuk ke struktur sockaddr alamat lokal untuk ditetapkan ke soket terikat .

[in] namelen

Panjangnya, dalam byte, dari nilai yang ditujukkan oleh addr.

Mengembalikan nilai

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

Kode kesalahan	Makna
WSANOTINITIALISED	Catatan Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.
WSAENETDOWN	Subsistem jaringan gagal.
WSAEACCES	Upaya dilakukan untuk mengakses soket dengan cara yang dilarang oleh izin aksesnya. Kesalahan ini dikembalikan jika nn mencoba mengikat soket datagram ke alamat siaran gagal karena opsi setsockopt SO_BROADCAST tidak diaktifkan.
WSAEADDRINUSE	Hanya satu penggunaan setiap alamat soket (protokol/alamat jaringan/port) yang biasanya diizinkan. Kesalahan ini dikembalikan jika proses pada komputer sudah terikat ke alamat yang sepenuhnya memenuhi syarat yang sama dan soket belum ditandai untuk mengizinkan penggunaan kembali alamat dengan SO_REUSEADDR. Misalnya, alamat IP dan port yang ditentukan dalam parameter nama sudah terikat ke soket lain yang digunakan oleh aplikasi lain. Untuk informasi selengkapnya, lihat opsi soket SO_REUSEADDR di referensi Opsi Soket SOL_SOCKET , Menggunakan SO_REUSEADDR dan SO_EXCLUSIVEADDRUSE, dan SO_EXCLUSIVEADDRUSE.
WSAEADDRNOTAVAIL	Alamat yang diminta tidak valid dalam konteksnya. Kesalahan ini dikembalikan jika alamat yang ditentukan yang ditujukan oleh parameter nama bukan alamat IP lokal yang valid pada komputer ini.
WSAEFAULT	Sistem mendeteksi alamat penunjuk yang tidak valid dalam mencoba menggunakan argumen penunjuk dalam panggilan. Kesalahan ini dikembalikan jika parameter nama adalah NULL, parameter nama atau namelen bukan bagian yang valid dari ruang alamat pengguna, parameter namelen terlalu kecil, parameter nama berisi format alamat yang salah untuk keluarga alamat terkait, atau dua byte pertama dari blok memori yang ditentukan oleh nama tidak cocok dengan keluarga alamat yang terkait dengan deskriptor soket.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets 1.1 sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEINVAL	Argumen yang tidak valid disediakan. Kesalahan ini dikembalikan dari soket sudah terikat ke alamat.
WSAENOBUFS	Biasanya, WSAENOBUFS adalah indikasi bahwa tidak ada cukup port sementara untuk dialokasikan untuk ikatan.
WSAENOTSOCK	Operasi dicoba pada sesuatu yang bukan soket. Kesalahan ini dikembalikan jika deskriptor dalam parameter s bukan soket.

Keterangan

Fungsi ikatan diperlukan pada soket yang tidak terhubung sebelum panggilan berikutnya ke fungsi dengar . Biasanya digunakan untuk mengikat soket berorientasi koneksi (stream) atau tanpa koneksi (datagram). Fungsi ikatan juga dapat digunakan untuk mengikat soket mentah (soket dibuat dengan memanggil fungsi soket dengan parameter jenis diatur ke SOCK_RAW). Fungsi ikatan juga dapat digunakan pada soket yang tidak terhubung sebelum panggilan berikutnya ke fungsi connect, ConnectEx, WSAConnect, WSAConnectByList, atau WSAConnectByName sebelum mengirim operasi.

Ketika soket dibuat dengan panggilan ke fungsi soket, soket ada di namespace (keluarga alamat), tetapi tidak memiliki nama yang ditetapkan untuk itu. Gunakan fungsi ikatan untuk menetapkan asosiasi lokal soket dengan menetapkan nama lokal ke soket yang tidak disebutkan namanya.

Nama terdiri dari tiga bagian saat menggunakan keluarga alamat Internet:

Keluarga alamat.
Alamat host.
Nomor port yang mengidentifikasi aplikasi.

Di Windows Sockets 2, parameter nama tidak ditafsirkan secara ketat sebagai penunjuk ke struktur sockaddr . Ini dilemparkan dengan cara ini untuk kompatibilitas Windows Sockets 1.1. Penyedia layanan bebas menganggapnya sebagai penunjuk ke blok memori namelen ukuran. 2 byte pertama dalam blok ini (sesuai dengan anggota sa_family struktur sockaddr , anggota sin_family struktur sockaddr_in , atau anggota sin6_family struktur sockaddr_in6 ) harus berisi keluarga alamat yang digunakan untuk membuat soket. Jika tidak, terjadi kesalahan WSAEFAULT.

Jika aplikasi tidak peduli alamat lokal apa yang ditetapkan, tentukan nilai konstanta INADDR_ANY untuk alamat lokal IPv4 atau nilai konstanta in6addr_any untuk alamat lokal IPv6 di anggota sa_data parameter nama . Hal ini memungkinkan penyedia layanan yang mendasar untuk menggunakan alamat jaringan yang sesuai, berpotensi menyederhanakan pemrograman aplikasi di hadapan host multihomed (yaitu, host yang memiliki lebih dari satu antarmuka dan alamat jaringan).

Untuk TCP/IP, jika port ditentukan sebagai nol, penyedia layanan menetapkan port unik ke aplikasi dari rentang port klien dinamis. Pada Windows Vista dan yang lebih baru, rentang port klien dinamis adalah nilai antara 49152 dan 65535. Ini adalah perubahan dari Windows Server 2003 dan yang lebih lama di mana rentang port klien dinamis adalah nilai antara 1025 dan 5000. Nilai maksimum untuk rentang port dinamis klien dapat diubah dengan mengatur nilai di bawah kunci registri berikut:

HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters

Nilai registri MaxUserPort menetapkan nilai yang akan digunakan untuk nilai maksimum rentang port klien dinamis. Anda harus memulai-ulang komputer agar setelan ini berlaku.

Pada Windows Vista dan yang lebih baru, rentang port klien dinamis dapat dilihat dan diubah menggunakan perintah netsh . Rentang port klien dinamis dapat diatur secara berbeda untuk UDP dan TCP dan juga untuk IPv4 dan IPv6. Untuk informasi selengkapnya, lihat KB 929851.

Aplikasi dapat menggunakan getsockname setelah memanggil bind untuk mempelajari alamat dan port yang telah ditetapkan ke soket. Jika alamat Internet sama dengan INADDR_ANY atau in6addr_any, getsockname tidak selalu menyediakan alamat sampai soket tersambung, karena beberapa alamat dapat valid jika host multihomed. Pengikatan ke nomor port tertentu selain port 0 tidak disarankan untuk aplikasi klien, karena ada bahaya konflik dengan soket lain yang sudah menggunakan nomor port tersebut di komputer lokal.

Catatan Saat menggunakan ikatan dengan opsi soket SO_EXCLUSIVEADDRUSE atau SO_REUSEADDR, opsi soket harus diatur sebelum mengeksekusi ikatan memiliki pengaruh apa pun. Untuk informasi selengkapnya, lihat SO_EXCLUSIVEADDRUSE dan Menggunakan SO_REUSEADDR dan SO_EXCLUSIVEADDRUSE.

Untuk operasi multicast, metode yang disukai adalah memanggil fungsi pengikatan untuk mengaitkan soket dengan alamat IP lokal lalu bergabung dengan grup multicast. Meskipun urutan operasi ini tidak wajib, sangat disarankan. Jadi aplikasi multicast pertama-tama akan memilih alamat IPv4 atau IPv6 di komputer lokal, alamat IPv4 wildcard (INADDR_ANY), atau alamat IPv6 wildcard (in6addr_any). Aplikasi multicast kemudian akan memanggil fungsi ikat dengan alamat ini di sa_data anggota parameter nama untuk mengaitkan alamat IP lokal dengan soket. Jika alamat kartubebas ditentukan, maka Windows akan memilih alamat IP lokal yang akan digunakan. Setelah fungsi ikatan selesai, aplikasi kemudian akan bergabung dengan grup multicast yang diminati. Untuk informasi selengkapnya tentang cara bergabung dengan grup multicast, lihat bagian tentang Pemrograman Multicast. Soket ini kemudian dapat digunakan untuk menerima paket multicast dari grup multicast menggunakan fungsi recv, recvfrom, WSARecv, WSARecvEx, WSARecvFrom, atau LPFN_WSARECVMSG (WSARecvMsg ).

Fungsi ikatan biasanya tidak diperlukan untuk mengirim operasi ke grup multicast. Fungsi sendto,WSASendMsg, dan WSASendTo secara implisit mengikat soket ke alamat wildcard jika soket belum terikat. Fungsi ikatan diperlukan sebelum penggunaan fungsi kirim atau WSASend yang tidak melakukan ikatan implisit dan hanya diizinkan pada soket yang terhubung, yang berarti soket harus sudah terikat agar terhubung. Fungsi ikatan mungkin digunakan sebelum mengirim operasi menggunakan fungsi sendto,WSASendMsg, atau WSASendTo jika aplikasi ingin memilih alamat IP lokal tertentu di komputer lokal dengan beberapa antarmuka jaringan dan alamat IP lokal. Jika tidak, ikatan implisit ke alamat wildcard menggunakan fungsi sendto,WSASendMsg , atau WSASendTo dapat mengakibatkan alamat IP lokal yang berbeda digunakan untuk operasi pengiriman.

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

Catatan untuk Soket IrDA

File header Af_irda.h harus disertakan secara eksplisit.
Nama lokal tidak diekspos di IrDA. Oleh karena itu, soket klien IrDA tidak boleh memanggil fungsi pengikatan sebelum fungsi sambungkan . Jika soket IrDA sebelumnya terikat ke nama layanan menggunakan ikatan, fungsi sambungkan akan gagal dengan SOCKET_ERROR.
Jika nama layanan adalah bentuk "LSAP-SELxxx," di mana xxx adalah bilangan bulat desimal dalam rentang 1-127, alamat menunjukkan LSAP-SEL xxx tertentu daripada nama layanan. Nama layanan seperti ini memungkinkan aplikasi server menerima koneksi masuk yang diarahkan ke LSAP-SEL tertentu, tanpa terlebih dahulu melakukan kueri nama layanan ISA untuk mendapatkan LSAP-SEL terkait. Salah satu contoh jenis nama layanan ini adalah perangkat non-Windows yang tidak mendukung IAS.

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.

Contoh

Contoh berikut menunjukkan penggunaan fungsi ikatan . Untuk contoh lain yang menggunakan fungsi ikat , lihat Memulai Winsock.

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

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

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

int main()
{

    // Declare some variables
    WSADATA wsaData;

    int iResult = 0;            // used to return function results

    // the listening socket to be created
    SOCKET ListenSocket = INVALID_SOCKET;

    // The socket address to be passed to bind
    sockaddr_in service;

    //----------------------
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != NO_ERROR) {
        wprintf(L"Error at WSAStartup()\n");
        return 1;
    }
    //----------------------
    // Create a SOCKET for listening for 
    // incoming connection requests
    ListenSocket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (ListenSocket == INVALID_SOCKET) {
        wprintf(L"socket function failed with error: %u\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }
    //----------------------
    // The sockaddr_in structure specifies the address family,
    // IP address, and port for the socket that is being bound.
    service.sin_family = AF_INET;
    service.sin_addr.s_addr = inet_addr("127.0.0.1");
    service.sin_port = htons(27015);

    //----------------------
    // Bind the socket.
    iResult = bind(ListenSocket, (SOCKADDR *) &service, sizeof (service));
    if (iResult == SOCKET_ERROR) {
        wprintf(L"bind failed with error %u\n", WSAGetLastError());
        closesocket(ListenSocket);
        WSACleanup();
        return 1;
    }
    else
        wprintf(L"bind returned success\n");

    WSACleanup();
    return 0;
}

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	winsock.h (termasuk Winsock2.h)
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll