fungsi bind (winsock2.h)

Artikel
11/20/2024

Fungsi pengikatan mengaitkan alamat lokal dengan soket.

Sintaksis

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

Parameter

[in] s

Deskriptor yang mengidentifikasi soket yang tidak terikat.

[in] name

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

[in] namelen

Panjangnya, dalam byte, dari nilai yang ditujukkan oleh nama parameter.

Mengembalikan nilai

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

Kode kesalahan	Arti
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 upaya untuk 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, nama atau parameter namelen bukan bagian yang valid dari ruang alamat pengguna, parameter namelen terlalu kecil, nama parameter 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 s.
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	Operasi pada soket tidak dapat dilakukan karena sistem tidak memiliki ruang buffer yang cukup atau karena antrean penuh. Kesalahan ini dikembalikan karena tidak tersedia cukup buffer atau ada terlalu banyak koneksi.
WSAENOTSOCK	Operasi dicoba pada sesuatu yang bukan soket. Kesalahan ini dikembalikan jika deskriptor dalam parameter bukan soket.

Komentar

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

Ketika soket dibuat dengan panggilan ke fungsi soket , soket tersebut 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, nama parameter 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 ukuran namelen. 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 . 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 sebelumnya 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 mengikat untuk mempelajari alamat dan port yang telah ditetapkan ke soket. Jika alamat Internet sama dengan INADDR_ANY atau in6addr_any, getsockname tidak selalu dapat 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 bertentangan dengan soket lain yang sudah menggunakan nomor port tersebut di komputer lokal.

Catatan Saat menggunakan pengikatan dengan opsi soket SO_EXCLUSIVEADDRUSE atau SO_REUSEADDR, opsi soket harus diatur sebelum menjalankan ikatan agar 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 pengikatan dengan alamat ini di dalam anggota sa_data 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 pengikatan selesai, aplikasi kemudian akan bergabung dengan grup minat multicast. 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 menggunakanrecv , recvfrom, WSARecv, WSARecvEx, WSARecvFrom, atau LPFN_WSARECVMSG (WSARecvMsg) fungsi.

Fungsi pengikatan 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 pengikatan diperlukan sebelum penggunaan fungsi mengirim atau WSASend yang tidak melakukan ikatan implisit dan hanya diizinkan pada soket yang terhubung, yang berarti soket harus sudah terikat agar terhubung. Fungsi pengikatan dapat digunakan sebelum mengirim operasi menggunakan kirim ke,WSASendMsg, atau WSASendTo fungsi 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 kirim ke,WSASendMsg , atau fungsi WSASendTo dapat mengakibatkan alamat IP lokal yang berbeda digunakan untuk operasi pengiriman.

Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti mengikat, 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 ditentukan, 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 menyambungkan fungsi. Jika soket IrDA sebelumnya terikat ke nama layanan menggunakanikatan , fungsi connect 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 untuk 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 pada Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.

Contoh

Contoh berikut menunjukkan penggunaan fungsi ikatan . Untuk contoh lain yang menggunakan fungsi ikatan , 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

Syarat	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]
Platform Target	Windows
Header	winsock2.h (termasuk Winsock2.h)
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll