This is retired content. This content is outdated and is no
longer being maintained. It is provided as a courtesy for
individuals who are still using these technologies. This content
may contain URLs that were valid when originally published, but now
link to sites or pages that no longer exist.
[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
optvalbuffer.
Return Values
Zero indicates that no error occurred. SOCKET_ERROR indicates
failure. To get a specific error value, call
WSAGetLastError.
Remarks
The
setsockoptfunction 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,
optvalpoints to a nonzero integer. To disable the option
optvalpoints to an integer equal to zero. The
optlenparameter should be equal to
sizeof(int)for Boolean options. For other options,
optvalpoints to an integer or structure that contains the
desired value for the option, and
optlenis 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_onoffset to zero.
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
intfor
optval.
IP_MULTICAST_IF
Address of the outgoing multicast-capable
interface. This address is used for subsequent multicasts. Use
unsigned longfor
optval.
IP_ADD_MEMBERSHIP
The membership request structure used to request a
particular multicast group's membership. Use
struct ip_mreqfor
optval.
IP_DROP_MEMBERSHIP
The group whose membership is to be used. Use
struct ip_mreqfor
optval.
Windows CE does not support setting the IP_MULTICAST_LOOP value
for the IPPROTO_IP level.
BSD options not supported for
setsockoptare:
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 Hosts-Communication 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
closesocketis performed. See
closesocketfor 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
LINGERstructure (pointed to by the
optvalparameter) with these members
l_onoffand
l_lingerset 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
bindon 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
bindhas 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,
optnameto 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.
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.