The setsockopt function sets a socket option.
int setsockopt( SOCKET s, int level, int optname, const char *optval, int optlen );
A descriptor that identifies a socket.
The level at which the option is defined (for example, SOL_SOCKET).
The socket option for which the value is to be set (for example, SO_BROADCAST). The optname parameter must be a socket option defined within the specified level, or behavior is undefined.
A pointer to the buffer in which the value for the requested option is specified.
The size, in bytes, of the buffer pointed to by the optval parameter.
If no error occurs, setsockopt returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.
|A successful WSAStartup call must occur before using this function.|
|The network subsystem has failed.|
|The buffer pointed to by the optval parameter is not in a valid part of the process address space or the optlen parameter is too small.|
|A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.|
|The level parameter is not valid, or the information in the buffer pointed to by the optval parameter is not valid.|
|The connection has timed out when SO_KEEPALIVE is set.|
|The option is unknown or unsupported for the specified provider or socket (see SO_GROUP_PRIORITY limitations).|
|The connection has been reset when SO_KEEPALIVE is set.|
|The descriptor is not a socket.|
The setsockopt function sets the current value for a socket option associated with a socket of any type, in any state. Although options can exist at multiple protocol levels, they are always present at the uppermost socket level. Options affect socket operations, such as whether expedited data (OOB data for example) is received in the normal data stream, and whether broadcast messages can be sent on the socket.
sizeof(int)for Boolean options. For other options, optval points to an integer or structure that contains the desired value for the option, and optlen is the length of the integer or structure.
The following tables list some of the common options supported by the setsockopt function. The Type column identifies the type of data addressed by optval parameter. The Description column provides some basic information about the socket option. For more complete lists of socket options and more detailed information (default values, for example), see the detailed topics under Socket Options.
level = SOL_SOCKET
|SO_BROADCAST||BOOL||Configures a socket for sending broadcast data.|
|SO_CONDITIONAL_ACCEPT||BOOL||Enables incoming connections are to be accepted or rejected by the application, not by the protocol stack.|
|SO_DEBUG||BOOL||Enables debug output. Microsoft providers currently do not output any debug information.|
|SO_DONTLINGER||BOOL||Does not block close waiting for unsent data to be sent. Setting this option is equivalent to setting SO_LINGER with l_onoff set to zero.|
|SO_DONTROUTE||BOOL||Sets whether outgoing data should be sent on interface the socket is bound to and not a routed on some other interface. This option is not supported on ATM sockets (results in an error).|
|SO_KEEPALIVE||BOOL||Enables sending keep-alive packets for a socket connection. Not supported on ATM sockets (results in an error).|
|SO_LINGER||LINGER||Lingers on close if unsent data is present.|
|SO_OOBINLINE||BOOL||Indicates that out-of-bound data should be returned in-line with regular data. This option is only valid for connection-oriented protocols that support out-of-band data. For a discussion of this topic, see Protocol Independent Out-Of-band Data.|
|SO_RCVBUF||int||Specifies the total per-socket buffer space reserved for receives.|
|SO_REUSEADDR||BOOL||Allows the socket to be bound to an address that is already in use. For more information, see bind. Not applicable on ATM sockets.|
|SO_EXCLUSIVEADDRUSE||BOOL||Enables a socket to be bound for exclusive access. Does not require administrative privilege.|
|SO_RCVTIMEO||DWORD||Sets the timeout, in milliseconds, for blocking receive calls.|
|SO_SNDBUF||int||Specifies the total per-socket buffer space reserved for sends.|
|SO_SNDTIMEO||DWORD||The timeout, in milliseconds, for blocking send calls.|
|SO_UPDATE_ACCEPT_CONTEXT||int||Updates the accepting socket with the context of the listening socket.|
|PVD_CONFIG||Service Provider Dependent||This object stores the configuration information for the service provider associated with socket s. The exact format of this data structure is service provider specific.|
For more complete and detailed information about socket options for level = SOL_SOCKET, see SOL_SOCKET Socket Options.
level = IPPROTO_TCP
|TCP_NODELAY||BOOL||Disables the Nagle algorithm for send coalescing.This socket option is included for backward compatibility with Windows Sockets 1.1|
For more complete and detailed information about socket options for level = IPPROTO_TCP, see IPPROTO_TCP Socket Options.
level = NSPROTO_IPX
|IPX_PTYPE||int||Sets the IPX packet type.|
|IPX_FILTERPTYPE||int||Sets the receive filter packet type|
|IPX_STOPFILTERPTYPE||int||Stops filtering the filter type set with IPX_FILTERTYPE|
|IPX_DSTYPE||int||Sets the value of the data stream field in the SPX header on every packet sent.|
|IPX_EXTENDED_ADDRESS||BOOL||Sets whether extended addressing is enabled.|
|IPX_RECVHDR||BOOL||Sets whether the protocol header is sent up on all receive headers.|
|IPX_RECEIVE_BROADCAST||BOOL||Indicates broadcast packets are likely on the socket. Set to TRUE by default. Applications that do not use broadcasts should set this to FALSE for better system performance.|
|IPX_IMMEDIATESPXACK||BOOL||Directs SPX connections not to delay before sending an ACK. Applications without back-and-forth traffic should set this to TRUE to increase performance.|
For more complete and detailed information about socket options for level = NSPROTO_IPX, see NSPROTO_IPX Socket Options.
BSD options not supported for setsockopt are shown in the following table.
|SO_ACCEPTCONN||BOOL||Returns whether a socket is in listening mode. This option is only Valid for connection-oriented protocols. This socket option is not supported for the setting.|
|SO_RCVLOWAT||int||A socket option from BSD UNIX included for backward compatibility. This option sets the minimum number of bytes to process for socket input operations.|
|SO_SNDLOWAT||int||A socket option from BSD UNIX included for backward compatibility. This option sets the minimum number of bytes to process for socket output operations.|
|SO_TYPE||int||Returns the socket type for the given socket (SOCK_STREAM or SOCK_DGRAM, for example This socket option is not supported for the setting the socket type.|
#ifndef UNICODE #define UNICODE #endif
When developing applications using Windows sockets for IrDA, note the following:
- The Af_irda.h header file must be explicitly included.
- IrDA provides the following socket option:
Value Type Meaning IRLMP_IAS_SET *IAS_SET Sets IAS attributes
The IRLMP_IAS_SET socket option enables the application to set a single attribute of a single class in the local IAS. The application specifies the class to set, the attribute, and attribute type. The application is expected to allocate a buffer of the necessary size for the passed parameters.
IrDA provides an IAS database that stores IrDA-based information. Limited access to the IAS database is available through the Windows Sockets 2 interface, but such access is not normally used by applications, and exists primarily to support connections to non-Windows devices that are not compliant with the Windows Sockets 2 IrDA conventions.
The following structure, IAS_SET, is used with the IRLMP_IAS_SET setsockopt option to manage the local IAS database:
// #include <Af_irda.h> for this struct
// #include <Af_irda.h> for this struct
Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.
|Minimum supported client||Windows 8.1, Windows Vista [desktop apps | UWP apps]|
|Minimum supported server||Windows Server 2003 [desktop apps | UWP apps]|
|Header||winsock.h (include Winsock2.h)|