fungsi setsockopt (winsock.h)

Artikel
08/27/2023

Fungsi setsockopt menetapkan opsi soket.

Sintaks

int setsockopt(
  [in] SOCKET     s,
  [in] int        level,
  [in] int        optname,
  [in] const char *optval,
  [in] int        optlen
);

Parameter

[in] s

Deskriptor yang mengidentifikasi soket.

[in] level

Tingkat di mana opsi ditentukan (misalnya, SOL_SOCKET).

[in] optname

Opsi soket yang nilainya akan diatur (misalnya, SO_BROADCAST). Parameter optname harus merupakan opsi soket yang ditentukan dalam tingkat yang ditentukan, atau perilaku tidak terdefinisi.

[in] optval

Penunjuk ke buffer tempat nilai untuk opsi yang diminta ditentukan.

[in] optlen

Ukuran, dalam byte, dari buffer yang diacu oleh parameter optval .

Menampilkan nilai

Jika tidak ada kesalahan yang terjadi, setsockopt 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.
WSAEFAULT	Buffer yang ditujukkan oleh parameter optval tidak berada di bagian ruang alamat proses yang valid atau parameter optlen terlalu kecil.
WSAEINPROGRESS	Pemblokiran panggilan Windows Sockets 1.1 sedang berlangsung, atau penyedia layanan masih memproses fungsi panggilan balik.
WSAEINVAL	Parameter tingkat tidak valid, atau informasi dalam buffer yang diacu oleh parameter optval tidak valid.
WSAENETRESET	Koneksi telah kehabisan waktu ketika SO_KEEPALIVE diatur.
WSAENOPROTOOPT	Opsi tidak diketahui atau tidak didukung untuk penyedia atau soket yang ditentukan (lihat batasan SO_GROUP_PRIORITY).
WSAENOTCONN	Koneksi telah direset ketika SO_KEEPALIVE diatur.
WSAENOTSOCK	Deskriptor bukan soket.

Keterangan

Fungsi setsockopt 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 data yang dipercepat (data OOB misalnya) diterima di aliran data normal, dan apakah pesan siaran dapat dikirim pada soket.

Catatan Jika fungsi setsockopt dipanggil sebelum fungsi ikatan , opsi TCP/IP tidak akan diperiksa dengan menggunakan TCP/IP sampai ikatan terjadi. Dalam hal ini, panggilan fungsi setsockopt akan selalu berhasil, tetapi panggilan fungsi ikatan dapat gagal karena panggilan setsockopt awal gagal.

Catatan Jika soket dibuka, panggilan setsockopt dilakukan, lalu panggilan sendto dilakukan, Windows Sockets melakukan panggilan fungsi ikat implisit.

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, parameter optval menunjuk ke bilangan bulat bukan nol. Untuk menonaktifkan titik optval opsi 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.

Tabel berikut mencantumkan beberapa opsi umum yang didukung oleh fungsi setsockopt . Kolom Jenis mengidentifikasi jenis data yang ditangani oleh parameter optval . Kolom Deskripsi menyediakan beberapa informasi dasar tentang opsi soket. Untuk daftar lengkap opsi soket dan informasi yang lebih rinci (nilai default, misalnya), lihat topik terperinci di bawah Opsi Soket.

Tingkat = SOL_SOCKET

Nilai	Jenis	Deskripsi
SO_BROADCAST	BOOL	Mengonfigurasi soket untuk mengirim data siaran.
SO_CONDITIONAL_ACCEPT	BOOL	Mengaktifkan koneksi masuk akan diterima atau ditolak oleh aplikasi, bukan oleh tumpukan protokol.
SO_DEBUG	BOOL	Mengaktifkan output debug. Penyedia Microsoft saat ini tidak mengeluarkan informasi debug apa pun.
SO_DONTLINGER	BOOL	Tidak memblokir penutupan menunggu data yang belum dikirim. Mengatur opsi ini setara dengan mengatur SO_LINGER dengan l_onoff diatur ke nol.
SO_DONTROUTE	BOOL	Mengatur apakah data keluar harus dikirim pada antarmuka tempat soket terikat dan bukan dirutekan pada beberapa antarmuka lain. Opsi ini tidak didukung pada soket ATM (menghasilkan kesalahan).
SO_GROUP_PRIORITY	int	Dicadangkan.
SO_KEEPALIVE	BOOL	Memungkinkan pengiriman paket tetap hidup untuk koneksi soket. Tidak didukung pada soket ATM (menghasilkan kesalahan).
SO_LINGER	BERLAMA	Berlama-lama pada penutupan jika data yang tidak terkiron ada.
SO_OOBINLINE	BOOL	Menunjukkan bahwa data di luar batas harus dikembalikan sejalan dengan data reguler. Opsi ini hanya berlaku untuk protokol berorientasi koneksi yang mendukung data di luar band. Untuk diskusi tentang topik ini, lihat Protokol Data Out-Of-band Independen.
SO_RCVBUF	int	Menentukan total ruang buffer per soket yang dicadangkan untuk diterima.
SO_REUSEADDR	BOOL	Memungkinkan soket terikat ke alamat yang sudah digunakan. Untuk informasi selengkapnya, lihat mengikat. Tidak berlaku pada soket ATM.
SO_EXCLUSIVEADDRUSE	BOOL	Memungkinkan soket terikat untuk akses eksklusif. Tidak memerlukan hak administratif.
SO_RCVTIMEO	DWORD	Mengatur batas waktu, dalam milidetik, untuk memblokir panggilan terima.
SO_SNDBUF	int	Menentukan total ruang buffer per soket yang dicadangkan untuk pengiriman.
SO_SNDTIMEO	DWORD	Waktu habis, dalam milidetik, untuk memblokir panggilan pengiriman.
SO_UPDATE_ACCEPT_CONTEXT	int	Updates soket yang menerima dengan konteks soket mendengarkan.
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.

Untuk informasi selengkapnya dan terperinci tentang opsi soket untuk SOL_SOCKET tingkat = , lihat Opsi Soket SOL_SOCKET.

Tingkat = IPPROTO_TCP

Lihat TCP_NODELAY dalam opsi soket IPPROTO_TCP. Lihat juga topik tersebut untuk informasi yang lebih lengkap dan terperinci tentang opsi soket untuk IPPROTO_TCP tingkat = .

Tingkat = NSPROTO_IPX

Nilai	Jenis	Deskripsi
IPX_PTYPE	int	Mengatur jenis paket IPX.
IPX_FILTERPTYPE	int	Mengatur jenis paket filter penerima
IPX_STOPFILTERPTYPE	int	Berhenti memfilter set jenis filter dengan IPX_FILTERTYPE
IPX_DSTYPE	int	Mengatur nilai bidang aliran data di header SPX pada setiap paket yang dikirim.
IPX_EXTENDED_ADDRESS	BOOL	Mengatur apakah alamat yang diperluas diaktifkan.
IPX_RECVHDR	BOOL	Mengatur apakah header protokol dikirim pada semua header penerima.
IPX_RECEIVE_BROADCAST	BOOL	Menunjukkan paket siaran kemungkinan ada di soket. Atur ke TRUE secara default. Aplikasi yang tidak menggunakan siaran harus mengatur ini ke FALSE untuk performa sistem yang lebih baik.
IPX_IMMEDIATESPXACK	BOOL	Mengarahkan koneksi SPX untuk tidak menunda sebelum mengirim ACK. Aplikasi tanpa lalu lintas bolak-balik harus mengatur ini ke TRUE untuk meningkatkan performa.

Untuk informasi selengkapnya dan terperinci tentang opsi soket untuk NSPROTO_IPX tingkat = , lihat Opsi Soket NSPROTO_IPX.

Opsi BSD yang tidak didukung untuk setsockopt diperlihatkan dalam tabel berikut.

Nilai	Jenis	Deskripsi
SO_ACCEPTCONN	BOOL	Mengembalikan apakah soket dalam mode mendengarkan. Opsi ini hanya Valid untuk protokol berorientasi koneksi. Opsi soket ini tidak didukung untuk pengaturan.
SO_RCVLOWAT	int	Opsi soket dari BSD UNIX disertakan untuk kompatibilitas mundur. Opsi ini mengatur jumlah minimum byte yang akan diproses untuk operasi input soket.
SO_SNDLOWAT	int	Opsi soket dari BSD UNIX disertakan untuk kompatibilitas mundur. Opsi ini mengatur jumlah minimum byte yang akan diproses untuk operasi output soket.
SO_TYPE	int	Mengembalikan jenis soket untuk soket yang diberikan (SOCK_STREAM atau SOCK_DGRAM, misalnya Opsi soket ini tidak didukung untuk pengaturan jenis soket.

Catatan Saat mengeluarkan panggilan Winsock pemblokiran seperti setsockopt, 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.

Contoh Kode

Contoh berikut menunjukkan fungsi setsockopt .

#ifndef UNICODE
#define UNICODE
#endif

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

int main()
{

    //---------------------------------------
    // Declare variables
    WSADATA wsaData;

    SOCKET ListenSocket;
    sockaddr_in service;

    int iResult = 0;

    BOOL bOptVal = FALSE;
    int bOptLen = sizeof (BOOL);

    int iOptVal = 0;
    int iOptLen = sizeof (int);

    //---------------------------------------
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != NO_ERROR) {
        wprintf(L"Error at WSAStartup()\n");
        return 1;
    }
    //---------------------------------------
    // Create a listening socket
    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;
    }
    //---------------------------------------
    // Bind the socket to the local IP address
    // and port 27015
    hostent *thisHost;
    char *ip;
    u_short port;
    port = 27015;
    thisHost = gethostbyname("");
    ip = inet_ntoa(*(struct in_addr *) *thisHost->h_addr_list);

    service.sin_family = AF_INET;
    service.sin_addr.s_addr = inet_addr(ip);
    service.sin_port = htons(port);

    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;
    }
    //---------------------------------------
    // Initialize variables and call setsockopt. 
    // The SO_KEEPALIVE parameter is a socket option 
    // that makes the socket send keepalive messages
    // on the session. The SO_KEEPALIVE socket option
    // requires a boolean value to be passed to the
    // setsockopt function. If TRUE, the socket is
    // configured to send keepalive messages, if FALSE
    // the socket configured to NOT send keepalive messages.
    // This section of code tests the setsockopt function
    // by checking the status of SO_KEEPALIVE on the socket
    // using the getsockopt function.

    bOptVal = TRUE;

    iResult = getsockopt(ListenSocket, SOL_SOCKET, SO_KEEPALIVE, (char *) &iOptVal, &iOptLen);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"getsockopt for SO_KEEPALIVE failed with error: %u\n", WSAGetLastError());
    } else
        wprintf(L"SO_KEEPALIVE Value: %ld\n", iOptVal);

    iResult = setsockopt(ListenSocket, SOL_SOCKET, SO_KEEPALIVE, (char *) &bOptVal, bOptLen);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"setsockopt for SO_KEEPALIVE failed with error: %u\n", WSAGetLastError());
    } else
        wprintf(L"Set SO_KEEPALIVE: ON\n");

    iResult = getsockopt(ListenSocket, SOL_SOCKET, SO_KEEPALIVE, (char *) &iOptVal, &iOptLen);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"getsockopt for SO_KEEPALIVE failed with error: %u\n", WSAGetLastError());
    } else
        wprintf(L"SO_KEEPALIVE Value: %ld\n", iOptVal);

    closesocket(ListenSocket);
    WSACleanup();
    return 0;
}

Catatan untuk Soket IrDA

Saat mengembangkan aplikasi menggunakan soket Windows untuk IrDA, perhatikan hal berikut:

File header Af_irda.h harus disertakan secara eksplisit.
IrDA menyediakan opsi soket berikut:

Nilai Jenis Makna

IRLMP_IAS_SET *IAS_SET Mengatur atribut IAS

Nilai	Jenis	Makna
IRLMP_IAS_SET	*IAS_SET	Mengatur atribut IAS

Opsi soket IRLMP_IAS_SET memungkinkan aplikasi untuk mengatur satu atribut dari satu kelas di IAS lokal. Aplikasi menentukan kelas yang akan diatur, atribut, dan jenis atribut. Aplikasi ini diharapkan mengalokasikan buffer dengan ukuran yang diperlukan untuk parameter yang diteruskan.

IrDA menyediakan database IAS yang menyimpan informasi berbasis IrDA. Akses terbatas ke database IAS tersedia melalui antarmuka Windows Sockets 2, tetapi akses tersebut biasanya tidak digunakan oleh aplikasi, dan ada terutama untuk mendukung koneksi ke perangkat non-Windows yang tidak sesuai dengan konvensi Windows Sockets 2 IrDA.

Struktur berikut, IAS_SET, digunakan dengan opsi setsockopt IRLMP_IAS_SET untuk mengelola database IAS lokal:


// #include <Af_irda.h> for this struct

typedef struct _IAS_SET {
    u_char      irdaClassName[IAS_MAX_CLASSNAME];
    char      irdaAttribName[IAS_MAX_ATTRIBNAME];
    u_long    irdaAttribType;
    union
    {
              LONG irdaAttribInt;
              struct
              {
                   u_long   Len;
                   u_char    OctetSeq[IAS_MAX_OCTET_STRING];
              } irdaAttribOctetSeq;
              struct
              {
                   u_long    Len;
                   u_long    CharSet;
                   u_char    UsrStr[IAS_MAX_USER_STRING];
              } irdaAttribUsrStr;
    } irdaAttribute;
} IAS_SET, *PIAS_SET, FAR *LPIASSET;

Struktur berikut, IAS_QUERY, digunakan dengan opsi setsockopt IRLMP_IAS_QUERY untuk mengkueri database IAS serekan:


// #include <Af_irda.h> for this struct

typedef struct _WINDOWS_IAS_QUERY {
        u_char   irdaDeviceID[4];
        char     irdaClassName[IAS_MAX_CLASSNAME];
        char     irdaAttribName[IAS_MAX_ATTRIBNAME];
        u_long   irdaAttribType;
        union
        {
                  LONG    irdaAttribInt;
                  struct
                  {
                          u_long  Len;
                          u_char  OctetSeq[IAS_MAX_OCTET_STRING];
                  } irdaAttribOctetSeq;
                  struct
                  {
                          u_long  Len;
                          u_long  CharSet;
                          u_char  UsrStr[IAS_MAX_USER_STRING];
                  } irdaAttribUsrStr;
        } irdaAttribute;
} IAS_QUERY, *PIAS_QUERY, FAR *LPIASQUERY;

Banyak opsi soket tingkat SO_ tidak bermakna bagi IrDA. Hanya SO_LINGER yang didukung secara khusus.

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	winsock.h (termasuk Winsock2.h)
Pustaka	Ws2_32.lib
DLL	Ws2_32.dll