Fungsi panggilan balik LPWSPSETSOCKOPT (ws2spi.h)

Artikel
08/28/2023

Fungsi LPWSPSetSockOpt mengatur opsi soket.

Sintaks

LPWSPSETSOCKOPT Lpwspsetsockopt;

int Lpwspsetsockopt(
  [in]  SOCKET s,
  [in]  int level,
  [in]  int optname,
  [in]  const char *optval,
  [in]  int optlen,
  [out] LPINT lpErrno
)
{...}

Parameter

[in] s

Deskriptor yang mengidentifikasi soket.

[in] level

Tingkat di mana opsi didefinisikan; tingkat yang didukung termasuk SOL_SOCKET. Untuk informasi selengkapnya, lihat Lampiran Winsock.

[in] optname

Opsi soket yang nilainya akan diatur.

[in] optval

Penunjuk ke buffer tempat nilai untuk opsi yang diminta disediakan.

[in] optlen

Ukuran, dalam byte, dari buffer optval .

[out] lpErrno

Penunjuk ke kode kesalahan.

Mengembalikan nilai

Jika tidak ada kesalahan yang terjadi, LPWSPSetSockOpt mengembalikan nol. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu tersedia di lpErrno.

Kode Kesalahan	Makna
WSAENETDOWN	Subsistem jaringan gagal.
WSAEFAULT	Optval tidak berada di bagian yang valid dari ruang alamat proses atau parameter optlen terlalu kecil.
WSAEINPROGRESS	Fungsi dipanggil saat panggilan balik sedang berlangsung.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEINVAL	Tingkat tidak valid, atau informasi dalam optval tidak valid.
WSAENETRESET	Koneksi telah terputus karena aktivitas tetap aktif mendeteksi kegagalan saat operasi sedang berlangsung.
WSAENOPROTOOPT	Opsi tidak diketahui atau tidak didukung untuk penyedia yang ditentukan.
WSAENOTCONN	Koneksi telah direset ketika SO_KEEPALIVE diatur.
WSAENOTSOCK	Deskriptor bukan soket.

Keterangan

Fungsi LPWSPSetSockOpt menetapkan nilai saat ini untuk opsi soket yang terkait dengan soket jenis apa pun, dalam status apa pun. Meskipun opsi dapat ada di beberapa tingkat protokol, opsi selalu ada di tingkat soket paling atas. Opsi memengaruhi operasi soket, seperti apakah pesan siaran dapat dikirim pada soket.

Ada dua jenis opsi soket: Opsi Boolean yang mengaktifkan atau menonaktifkan fitur atau perilaku, dan opsi yang memerlukan nilai atau struktur bilangan bulat. Untuk mengaktifkan opsi Boolean, optval menunjuk ke bilangan bulat bukan nol. Untuk menonaktifkan opsi, optval menunjuk ke bilangan bulat yang sama dengan nol. Parameter optlen harus sama dengan sizeof (int) untuk opsi Boolean. Untuk opsi lain, optval menunjuk ke bilangan bulat atau struktur yang berisi nilai yang diinginkan untuk opsi, dan optlen adalah panjang bilangan bulat atau struktur.

Untuk informasi selengkapnya tentang opsi soket, lihat Opsi Soket.

level = SOL_SOCKET

Nilai	Jenis	Makna
SO_BROADCAST	BOOL	Memungkinkan transmisi dan penerimaan pesan siaran pada soket.
SO_DEBUG	BOOL	Merekam informasi penelusuran kesalahan.
SO_DONTLINGER	BOOL	Dicadangkan.
SO_DONTROUTE	BOOL	Perutean yang dinonaktifkan: kirim langsung ke antarmuka. Pengaturan opsi soket ini berhasil tetapi diabaikan pada soket AF_INET; gagal pada soket AF_INET6 dengan WSAENOPROTOOPT . Opsi ini tidak didukung pada soket ATM (menghasilkan kesalahan).
SO_GROUP_PRIORITY	int	Dicadangkan.
SO_KEEPALIVE	BOOL	Mengirim tetap hidup. Tidak didukung pada soket ATM (menghasilkan kesalahan).
SO_LINGER	struct linger	Linger pada penutupan jika ada data yang tidak terkirman.
SO_OOBINLINE	BOOL	Menerima data OOB dalam aliran data normal.
SO_RCVBUF	int	Menentukan total ruang buffer per soket yang disediakan untuk penerimaan. Ini tidak terkait dengan SO_MAX_MSG_SIZE dan tidak selalu sesuai dengan ukuran jendela penerima TCP.
SO_REUSEADDR	BOOL	Memungkinkan soket terikat ke alamat yang sudah digunakan. (Lihat Ikatan.) Tidak berlaku pada soket ATM.
SO_SNDBUF	int	Menentukan total ruang buffer per soket yang disediakan untuk pengiriman. Ini tidak terkait dengan SO_MAX_MSG_SIZE dan tidak selalu sesuai dengan ukuran jendela pengiriman TCP.
PVD_CONFIG	Dependen Penyedia Layanan	Objek ini menyimpan informasi konfigurasi untuk penyedia layanan yang terkait dengan soket. Format yang tepat dari struktur data ini khusus untuk penyedia layanan.

Memanggil LPWSPGetSockopt dengan opsi yang tidak didukung akan mengakibatkan kode kesalahan WSAENOPROTOOPT dikembalikan dalam lpErrno.

SO_DEBUG

Penyedia layanan Windows Sockets didorong, tetapi tidak diperlukan, untuk menyediakan informasi debug output jika opsi SO_DEBUG diatur oleh klien Windows Sockets SPI. Mekanisme untuk menghasilkan informasi debug dan formatnya berada di luar cakupan spesifikasi ini.

SO_GROUP_PRIORITY

Dicadangkan.

SO_KEEPALIVE

Klien Windows Sockets SPI dapat meminta agar penyedia TCP/IP mengaktifkan penggunaan paket tetap aktif pada koneksi TCP dengan mengaktifkan opsi soket SO_KEEPALIVE . Penyedia Soket Windows tidak perlu mendukung penggunaan tetap hidup: jika ya, semantik yang tepat spesifik implementasinya, tetapi harus sesuai dengan bagian 4.2.3.6 dari RFC 1122: Persyaratan untuk Host Internet—Lapisan Komunikasi. (Sumber daya ini mungkin hanya tersedia dalam bahasa Inggris.) Jika koneksi dihilangkan sebagai akibat dari tetap hidup, kode kesalahan WSAENETRESET dikembalikan ke panggilan apa pun yang sedang berlangsung di soket, dan panggilan berikutnya akan gagal dengan WSAENOTCONN .

SO_LINGER

SO_LINGER mengontrol tindakan yang diambil ketika data yang tidak dikirim diantrekan pada soket dan LPWSPCloseSocket dilakukan. Lihat LPWSPCloseSocket untuk deskripsi cara pengaturan SO_LINGER memengaruhi semantik LPWSPCloseSocket. Klien Windows Sockets SPI menetapkan perilaku yang diinginkan dengan membuat struktur LINGER , yang diarahkan oleh parameter optval , dengan elemen berikut.

struct linger {
  u_short l_onoff;
  u_short l_linger;
}

Untuk mengaktifkan SO_LINGER, klien Windows Sockets SPI harus mengatur l_onoff ke nilai bukan nol, mengatur l_linger ke nol atau batas waktu yang diinginkan, dalam detik, dan memanggil LPWSPSetSockOpt. Untuk mengaktifkan SO_DONTLINGER, yaitu, nonaktifkan SO_LINGER, l_onoff harus diatur ke nol dan LPWSPSetSockOpt harus dipanggil. Ketahuilah bahwa mengaktifkan SO_LINGER dengan batas waktu nonzero pada soket nonblocking tidak disarankan. Untuk informasi selengkapnya, lihat LPWSPCloseSocket.

Mengaktifkan SO_LINGER juga menonaktifkan SO_DONTLINGER, dan sebaliknya. Ketahuilah bahwa jika SO_DONTLINGER dinonaktifkan (yaitu, SO_LINGER diaktifkan) maka tidak ada nilai waktu habis yang ditentukan. Dalam hal ini, waktu habis yang digunakan tergantung pada implementasi. Jika batas waktu sebelumnya telah ditetapkan untuk soket (dengan mengaktifkan SO_LINGER), maka nilai batas waktu ini harus dikembalikan oleh penyedia layanan.

SO_REUSEADDR

Secara default, soket tidak dapat diikat (untuk informasi selengkapnya, lihat LPWSPBind) ke alamat lokal yang sudah digunakan. Namun, terkadang, mungkin diinginkan untuk menggunakan kembali alamat dengan cara ini. Karena setiap koneksi diidentifikasi secara unik oleh kombinasi alamat lokal dan jarak jauh, tidak ada masalah dengan memiliki dua soket yang terikat ke alamat lokal yang sama selama alamat jarak jauh berbeda. Untuk memberi tahu penyedia Soket Windows bahwa LPWSPBind pada soket harus diizinkan untuk mengikat ke alamat lokal yang sudah digunakan oleh soket lain, klien SPI Soket Windows harus mengatur opsi soket SO_REUSEADDR untuk soket sebelum mengeluarkan LPWSPBind. Ketahuilah bahwa opsi ini hanya ditafsirkan pada saat LPWSPBind: oleh karena itu tidak perlu, tetapi tidak berbahaya, untuk mengatur opsi pada soket yang tidak terikat ke alamat yang ada, dan mengatur atau mengatur ulang opsi setelah LPWSPBind tidak berpengaruh pada soket ini atau lainnya.

SO_SNDBUF

Ketika implementasi Windows Sockets mendukung opsi SO_RCVBUF dan SO_SNDBUF , klien Windows Sockets SPI dapat meminta ukuran buffer yang berbeda (lebih besar atau lebih kecil). Panggilan dapat berhasil meskipun penyedia layanan tidak menyediakan seluruh jumlah yang diminta. Klien Windows Sockets SPI harus memanggil LPWSPGetSockopt dengan opsi yang sama untuk memverifikasi ukuran buffer yang sebenarnya disediakan.

PVD_CONFIG

Objek ini menyimpan informasi konfigurasi untuk penyedia layanan yang terkait dengan soket. Format yang tepat dari struktur data ini khusus untuk penyedia layanan.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Header	ws2spi.h