setsockopt

Article
06/30/2006

This function sets a socket option.

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

Parameters

s
[in] Descriptor that identifies a socket.
level
[in] Level at which the option is defined; the supported levels include SOL_SOCKET, IPPROTO_TCP, and IPPROTO_IP.
optname
[in] Socket option for which the value is to be set.
optval
[in] Pointer to the buffer in which the value for the requested option is supplied.
optlen
[in] Size of the optval buffer.

Return Values

Zero indicates that no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

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.

There are two types of socket options: Boolean options that enable or disable a feature or behavior, and options that require an integer value or structure. To enable a Boolean option, optval points to a nonzero integer. To disable the option optval points to an integer equal to zero. The optlen parameter should be equal to 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 options are supported for setsockopt. For default values of these options, see the description. The Type identifies the type of data addressed by optval.

level = SOL_SOCKET

Value	Type	Description
SO_BROADCAST	BOOL	Allow transmission of broadcast messages on the socket.
SO_DONTLINGER	BOOL	Do 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_KEEPALIVE	BOOL	Send keepalives
SO_LINGER	struct LINGER	Linger on close if unsent data is present.
SO_REUSEADDR	BOOL	Allow the socket to be bound to an address that is already in use. (See bind.)
SO_SNDBUF	int	Specifies the total per-socket buffer space reserved for sends. In Windows CE, this value is used mostly for increasing the buffer size for extended large pipes, such as satellites. Setting this value too high or too low can have bad effects on performances. Windows CE does not support setting this value to 0.

level = IPPROTO_TCP

Value	Type	Description
TCP_NODELAY	BOOL	Disables the Nagle algorithm for send coalescing.

level = IPPROTO_IP

Value	Description
IP_MULTICAST_TTL	Time-to-live for a multicast packet. Specifies the maximum number of hops for which a multicast message survives before it is discarded. Use int for optval.
IP_MULTICAST_IF	Address of the outgoing multicast-capable interface. This address is used for subsequent multicasts. Use unsigned long for optval.
IP_ADD_MEMBERSHIP	The membership request structure used to request a particular multicast group's membership. Use struct ip_mreq for optval.
IP_DROP_MEMBERSHIP	The group whose membership is to be used. Use struct ip_mreq for optval.

Windows CE does not support setting the IP_MULTICAST_LOOP value for the IPPROTO_IP level.

BSD options not supported for setsockopt are:

Value	Type	Description
SO_ACCEPTCONN	BOOL	Socket is listening
SO_RCVLOWAT	Int	Receive low water mark
SO_SNDLOWAT	Int	Send low water mark
SO_SNDTIMEO	Int	Send time-out
SO_TYPE	Int	Type of the socket

SO_KEEPALIVE
An application can request that a TCP/IP provider enable the use of "keep-alive" packets on TCP connections by turning on the SO_KEEPALIVE socket option. A Windows Sockets provider need not support the use of keep-alives. If it does, the precise semantics are implementation-specific but should conform to section 4.2.3.6 of RFC 1122: Requirements for Internet HostsCommunication Layers. If a connection is dropped as the result of "keep-alives" the error value WSAENETRESET is returned to any calls in progress on the socket, and any subsequent calls will fail with WSAENOTCONN.
SO_LINGER
The SO_LINGER option controls the action taken when unsent data is queued on a socket and a closesocket is performed. See closesocket for a description of the way in which the SO_LINGER settings affect the semantics of closesocket. The application sets the desired behavior by creating a LINGER structure (pointed to by the optval parameter) with these members l_onoff and l_linger set appropriately.
SO_REUSEADDR
By default, a socket cannot be bound (see bind) to a local address that is already in use. On occasion, however, it can be necessary to "re-use" an address in this way. Since every connection is uniquely identified by the combination of local and remote addresses, there is no problem with having two sockets bound to the same local address as long as the remote addresses are different. To inform the Windows Sockets provider that a bind on a socket should not be disallowed because the desired address is already in use by another socket, the application should set the SO_REUSEADDR socket option for the socket before issuing the bind. The option is interpreted only at the time of the bind. It is therefore unnecessary and harmless to set the option on a socket that is not to be bound to an existing address. Setting or resetting the option after the bind has no effect on this or any other socket.
TCP_NODELAY
The TCP_NODELAY option is specific to TCP/IP service providers. The Nagle algorithm is disabled if the TCP_NODELAY option is enabled (and vice versa). The process involves buffering send data when there is unacknowledged data already "in flight" or buffering send data until a full-size packet can be sent. It is highly recommended that TCP/IP service providers enable the Nagle Algorithm by default, and for the vast majority of application protocols the Nagle Algorithm can deliver significant performance enhancements. However, for some applications this algorithm can impede performance, and TCP_NODELAY can be used to turn it off. These are applications where many small messages are sent, and the time delays between the messages are maintained. Application writers should not set TCP_NODELAY unless the impact of doing so is well-understood and desired because setting TCP_NODELAY can have a significant negative impact on network and application performance.

To set a socket to secure mode, the option level parameter, level, must set to SO_SOCKET, the option name, optname to SO_SECURE, and the option value, optval, must be a pointer to a DWORD containing SO_SEC_SSL. These settings ensure that the Unified Secure Sockets Layer (SSL) package be used. The following code example shows how to set a socket to secure mode.

DWORD optval = SO_SEC_SSL;
err = setsockopt(
Socket,
SOL_SOCKET,
SO_SECURE,
&optval,
sizeof(optval)
);.

For Infrared Sockets (IrSock), Af_irda.h must be explicitly included.

IrSock provides two settable socket options:

Value	Type	Description
IRLMP_IAS_SET	* IAS_SET	Sets IAS attributes.
IRLMP_IRLPT_MODE	* int	In non-zero, enables IrLPT mode for printing to IrDA printers.

The IRLMP_IAS_SET socket option allows the application to set a single attribute of a single class in the local IAS. The application specifies the class to set and the attribute and attribute type. The maximum length of an attribute name is 60 characters however, regardless of the set value for characters beyond the 60^th, Windows CE will set these to NULL. That is, these two arrays will be truncated at 60 characters.

The IRLMP_EXCLUSIVE_MODE socket option allows the application to switch between TinyTP mode and unreliable IrLMP mode. If it is not set, IrSockets are assumed to use TinyTP. This option is only available after issuing the socket function and before issuing any other Windows Sockets function.

Many SO_ level socket options are not meaningful to IrSockets. Only SO_LINGER is specifically supported.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	1.0 and later	Winsock.h

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

Last updated on Tuesday, July 13, 2004

setsockopt

Additional resources