mendengarkan fungsi (winsock2.h)
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 |
---|---|
Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini. | |
Subsistem jaringan gagal. | |
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. | |
Pemblokiran panggilan Windows Sockets 1.1 sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik. | |
Soket belum terikat dengan ikatan. | |
Soket sudah tersambung. | |
Tidak ada lagi deskriptor soket yang tersedia. | |
Tidak ada ruang buffer yang tersedia. | |
Deskriptor bukan soket. | |
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.
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 |