mendengarkan fungsi (winsock2.h)

Artikel
03/08/2023

Fungsi dengar menempatkan soket dalam keadaan di mana ia mendengarkan koneksi masuk.

Sintaks

int WSAAPI listen(
  [in] SOCKET s,
  [in] int    backlog
);

Parameter

[in] s

Deskriptor yang mengidentifikasi soket yang terikat dan tidak terhubung.

[in] backlog

Panjang maksimum antrean koneksi tertunda. Jika diatur ke SOMAXCONN, penyedia layanan yang mendasar yang bertanggung jawab atas soket akan mengatur backlog ke nilai wajar maksimum. Jika diatur ke SOMAXCONN_HINT(N) (di mana N adalah angka), nilai backlog akan menjadi N, disesuaikan agar berada dalam rentang (200, 65535). Perhatikan bahwa SOMAXCONN_HINT dapat digunakan untuk mengatur backlog ke nilai yang lebih besar dari yang mungkin dengan SOMAXCONN.

SOMAXCONN_HINT hanya didukung oleh penyedia layanan Microsoft TCP/IP. Tidak ada ketentuan standar untuk mendapatkan nilai backlog aktual.

Mengembalikan nilai

Jika tidak ada kesalahan yang terjadi, mendengarkan mengembalikan nol. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

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 selama eksekusi fungsi ikatan , tetapi dapat ditunda sampai fungsi ini jika ikatan adalah ke alamat kartubebas sebagian (melibatkan ADDR_ANY) dan jika alamat tertentu perlu diterapkan pada saat fungsi ini.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets 1.1 sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEINVAL	Soket belum terikat dengan ikatan.
WSAEISCONN	Soket sudah tersambung.
WSAEMFILE	Tidak ada lagi deskriptor soket yang tersedia.
WSAENOBUFS	Tidak ada ruang buffer yang tersedia.
WSAENOTSOCK	Deskriptor bukan soket.
WSAEOPNOTSUPP	Soket yang dirujuk bukan jenis yang mendukung operasi mendengarkan .

Keterangan

Untuk menerima koneksi, soket pertama kali dibuat dengan fungsi soket dan terikat ke alamat lokal dengan fungsi ikatan . Backlog untuk koneksi masuk ditentukan dengan mendengarkan, lalu koneksi diterima dengan fungsi terima . Soket yang berorientasi pada koneksi, yang berjenis SOCK_STREAM misalnya, digunakan dengan mendengarkan. Soket dimasukkan ke dalam mode pasif di mana permintaan koneksi masuk diakui dan mengantrekan penerimaan tertunda oleh proses.

Nilai untuk backlogSOMAXCONN adalah konstanta khusus yang menginstruksikan penyedia layanan yang mendasar yang bertanggung jawab atas soket untuk mengatur panjang antrean koneksi yang tertunda ke nilai maksimum yang wajar.

Pada Windows Sockets 2, nilai maksimum ini default ke nilai besar (biasanya beberapa ratus atau lebih).

Saat memanggil fungsi mendengarkan dalam aplikasi Bluetooth, sangat disarankan agar nilai yang jauh lebih rendah digunakan untuk parameter backlog (biasanya 2 hingga 4), karena hanya beberapa koneksi klien yang diterima. Ini mengurangi sumber daya sistem yang dialokasikan untuk digunakan oleh soket mendengarkan. Rekomendasi yang sama ini berlaku untuk aplikasi jaringan lain yang hanya mengharapkan beberapa koneksi klien.

Fungsi mendengarkan biasanya digunakan oleh server yang dapat memiliki lebih dari satu permintaan koneksi pada satu waktu. Jika permintaan koneksi tiba dan antrean penuh, klien akan menerima kesalahan dengan indikasi WSAECONNREFUSED.

Jika tidak ada deskriptor soket yang tersedia, dengarkan upaya untuk terus berfungsi. Jika deskriptor tersedia, panggilan nanti untuk mendengarkan atau menerima akan mengisi ulang antrean ke nilai saat ini atau terbaru yang ditentukan untuk parameter backlog , jika memungkinkan, dan melanjutkan mendengarkan koneksi masuk.

Jika fungsi dengar dipanggil pada soket yang sudah mendengarkan, fungsi ini akan mengembalikan keberhasilan tanpa mengubah nilai untuk parameter backlog . Mengatur parameter backlog ke 0 dalam panggilan berikutnya untuk mendengarkan soket mendengarkan tidak dianggap sebagai reset yang tepat, terutama jika ada koneksi pada soket.

Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti mendengarkan, Winsock mungkin perlu menunggu acara 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 dengar .

#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 = 0;

    SOCKET ListenSocket = INVALID_SOCKET;
    sockaddr_in service;

    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != NO_ERROR) {
        wprintf(L"WSAStartup() failed with error: %d\n", iResult);
        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: %ld\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);

    iResult = bind(ListenSocket, (SOCKADDR *) & service, sizeof (service));
    if (iResult == SOCKET_ERROR) {
        wprintf(L"bind function failed with error %d\n", WSAGetLastError());
        iResult = closesocket(ListenSocket);
        if (iResult == SOCKET_ERROR)
            wprintf(L"closesocket function failed with error %d\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }
    //----------------------
    // Listen for incoming connection requests 
    // on the created socket
    if (listen(ListenSocket, SOMAXCONN) == SOCKET_ERROR)
        wprintf(L"listen function failed with error: %d\n", WSAGetLastError());

    wprintf(L"Listening on socket...\n");

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

    WSACleanup();
    return 0;
}

Contoh Kode

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

Catatan untuk Soket IrDA

File header Af_irda.h harus disertakan secara eksplisit.

Kompatibilitas

Parameter backlog terbatas (diam-diam) ke nilai yang wajar seperti yang ditentukan oleh penyedia layanan yang mendasar. Nilai ilegal digantikan oleh nilai hukum terdekat. Tidak ada ketentuan standar untuk mengetahui nilai backlog yang sebenarnya.

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.

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	winsock2.h
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll