pilih fungsi (winsock2.h)

Artikel
08/27/2023

Fungsi pilih menentukan status satu atau beberapa soket, menunggu jika perlu, untuk melakukan I/O sinkron.

Sintaks

int WSAAPI select(
  [in]      int           nfds,
  [in, out] fd_set        *readfds,
  [in, out] fd_set        *writefds,
  [in, out] fd_set        *exceptfds,
  [in]      const timeval *timeout
);

Parameter

[in] nfds

Diabaikan. Parameter nfds hanya disertakan untuk kompatibilitas dengan soket Berkeley.

[in, out] readfds

Penunjuk opsional ke sekumpulan soket yang akan diperiksa keterbacaannya.

[in, out] writefds

Penunjuk opsional ke sekumpulan soket yang akan diperiksa untuk mendapatkan wribilitas.

[in, out] exceptfds

Penunjuk opsional ke sekumpulan soket yang akan diperiksa kesalahannya.

[in] timeout

Waktu maksimum untuk memilih untuk menunggu, disediakan dalam bentuk struktur TIMEVAL . Atur parameter batas waktu ke null untuk operasi pemblokiran.

Mengembalikan nilai

Fungsi select mengembalikan jumlah total handel soket yang siap dan terkandung dalam struktur fd_set , nol jika batas waktu kedaluwarsa, atau SOCKET_ERROR jika terjadi kesalahan. Jika nilai yang dikembalikan SOCKET_ERROR, WSAGetLastError dapat digunakan untuk mengambil kode kesalahan tertentu.

Kode kesalahan	Makna
WSANOTINITIALISED	Panggilan WSAStartup yang berhasil harus terjadi sebelum menggunakan fungsi ini.
WSAEFAULT	Implementasi Windows Sockets tidak dapat mengalokasikan sumber daya yang diperlukan untuk operasi internalnya, atau readfd, writefd,exceptfds, atau parameter timeval bukan bagian dari ruang alamat pengguna.
WSAENETDOWN	Subsistem jaringan gagal.
WSAEINVAL	Nilai waktu habis tidak valid, atau ketiga parameter deskriptor null.
WSAEINTR	Panggilan Windows Socket 1.1 pemblokiran dibatalkan melalui WSACancelBlockingCall.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets 1.1 sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAENOTSOCK	Salah satu set deskriptor berisi entri yang bukan soket.

Keterangan

Fungsi select digunakan untuk menentukan status satu atau beberapa soket. Untuk setiap soket, pemanggil dapat meminta informasi tentang status baca, tulis, atau kesalahan. Kumpulan soket yang statusnya diminta ditunjukkan oleh struktur fd_set . Soket yang terkandung dalam struktur fd_set harus dikaitkan dengan satu penyedia layanan. Untuk tujuan pembatasan ini, soket dianggap berasal dari penyedia layanan yang sama jika struktur WSAPROTOCOL_INFO yang menjelaskan protokol mereka memiliki nilai providerId yang sama. Setelah kembali, struktur diperbarui untuk mencerminkan subset soket ini yang memenuhi kondisi yang ditentukan. Fungsi pilih mengembalikan jumlah soket yang memenuhi kondisi. Sekumpulan makro disediakan untuk memanipulasi struktur fd_set . Makro ini kompatibel dengan yang digunakan dalam perangkat lunak Berkeley, tetapi representasi yang mendasar benar-benar berbeda.

Parameter readfds mengidentifikasi soket yang akan diperiksa keterbacaannya. Jika soket saat ini dalam status mendengarkan , soket akan ditandai sebagai dapat dibaca jika permintaan koneksi masuk telah diterima sehingga penerimaan dijamin selesai tanpa memblokir. Untuk soket lain, keterbacaan berarti bahwa data yang diantrekan tersedia untuk dibaca sedunia sehingga panggilan ke recv, WSARecv, WSARecvFrom, atau recvfrom dijamin tidak akan memblokir.

Untuk soket berorientasi koneksi, keterbacaan juga dapat menunjukkan bahwa permintaan untuk menutup soket telah diterima dari serekan. Jika sirkuit virtual ditutup dengan lancar, dan semua data diterima, maka recv akan segera kembali dengan pembacaan nol byte. Jika sirkuit virtual direset, maka recv akan segera selesai dengan kode kesalahan seperti WSAECONNRESET. Kehadiran data OOB akan diperiksa apakah opsi soket SO_OOBINLINE telah diaktifkan (lihat setsockopt).

Parameter writefds mengidentifikasi soket yang akan diperiksa untuk writability. Jika soket memproses panggilan sambungkan (tidak memblokir), soket dapat ditulis jika pembentukan koneksi berhasil diselesaikan. Jika soket tidak memproses panggilan sambungkan , writability berarti kirim, kirim ke, atau WSASendto dijamin berhasil. Namun, mereka dapat memblokir soket pemblokiran jika parameter lensa melebihi jumlah ruang buffer sistem keluar yang tersedia. Tidak ditentukan berapa lama jaminan ini dapat diasumsikan valid, terutama di lingkungan multithreaded.

Parameter exceptfds mengidentifikasi soket yang akan diperiksa keberadaan data OOB atau kondisi kesalahan yang luar biasa.

Catatan Data di luar band hanya akan dilaporkan dengan cara ini jika opsi SO_OOBINLINE FALSE. Jika soket memproses panggilan koneksi (nonblocking), kegagalan upaya koneksi ditunjukkan dalam exceptfds (aplikasi kemudian harus memanggil getsockopt SO_ERROR untuk menentukan nilai kesalahan untuk menjelaskan mengapa kegagalan terjadi). Dokumen ini tidak menentukan kesalahan lain mana yang akan disertakan.

Dua parameter, readfd, writefd, atau exceptfd, dapat diberikan sebagai null. Setidaknya satu harus non-null, dan set deskriptor non-null harus berisi setidaknya satu handel ke soket.

Singkatnya, soket akan diidentifikasi dalam set tertentu saat memilih mengembalikan jika:

readfds:

Jika mendengarkan telah dipanggil dan koneksi tertunda, terima akan berhasil.
Data tersedia untuk dibaca (termasuk data OOB jika SO_OOBINLINE diaktifkan).
Koneksi telah ditutup/direset/dihentikan.

writefds:

Jika memproses panggilan sambungkan (tidak memblokir), koneksi telah berhasil.
Data dapat dikirim.

exceptfds:

Jika memproses panggilan sambungkan (tidak memblokir), upaya koneksi gagal.
Data OOB tersedia untuk dibaca (hanya jika SO_OOBINLINE dinonaktifkan).

Empat makro ditentukan dalam file header Winsock2.h untuk memanipulasi dan memeriksa set deskriptor. Variabel FD_SETSIZE menentukan jumlah maksimum deskriptor dalam satu set. (Nilai default FD_SETSIZE adalah 64, yang dapat dimodifikasi dengan menentukan FD_SETSIZE ke nilai lain sebelum menyertakan Winsock2.h.) Secara internal, handel soket dalam struktur fd_set tidak direpresentasikan sebagai bendera bit seperti di Berkeley Unix. Representasi data mereka buram. Penggunaan makro ini akan mempertahankan portabilitas perangkat lunak di antara lingkungan soket yang berbeda. Makro yang akan dimanipulasi dan diperiksa konten fd_set adalah:

FD_ZERO(*set) - Menginisialisasi diatur ke set kosong. Satu set harus selalu dibersihkan sebelum digunakan.
FD_CLR, *set) - Menghapus soket dari set.
FD_ISSET, *set) - Memeriksa untuk melihat apakah s adalah anggota set dan mengembalikan TRUE jika demikian.
FD_SET, *set) - Menambahkan soket untuk diatur.

Parameter time-out mengontrol berapa lama waktu yang diperlukan untuk menyelesaikan pilihan. Jika waktu habis adalah penunjuk null , pilih akan memblokir tanpa batas waktu hingga setidaknya satu deskriptor memenuhi kriteria yang ditentukan. Jika tidak, waktu habis menunjuk ke struktur TIMEVAL yang menentukan waktu maksimum yang dipilih harus menunggu sebelum kembali. Saat memilih kembali, konten struktur TIMEVAL tidak diubah. Jika TIMEVAL diinisialisasi ke {0, 0}, pilih akan segera kembali; ini digunakan untuk melakukan polling status soket yang dipilih. Jika pilih segera kembali, maka panggilan pilih dianggap tidak memblokir dan asumsi standar untuk panggilan nonblocking berlaku. Misalnya, kait pemblokiran tidak akan dipanggil, dan Windows Sockets tidak akan menghasilkan.

Catatan Fungsi select tidak berpengaruh pada persistensi peristiwa soket yang terdaftar di WSAAsyncSelect atau WSAEventSelect.

Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti memilih 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 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


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