setsockopt (Windows Sockets)

Article
06/30/2006

This function sets a socket option.

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

Parameters

s
[in] Descriptor identifying a socket.
level
[in] Level at which the option is defined; the supported levels include SOL_SOCKET and IPPROTO_TCP.
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

If no error occurs, this function returns zero. If an error occurs, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

The following table shows a list of possible error codes.

Error code	Description
WSANOTINITIALISED	A successful WSAStartup call must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The optval parameteris not in a valid part of the process address space or the optlen parameter is too small.
WSAEINPROGRESS	A blocking Winsock call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	The level parameteris not valid, or the information in optval is not valid.
WSAENETRESET	The connection has timed out when SO_KEEPALIVE is set.
WSAENOPROTOOPT	The option is unknown or unsupported for the specified provider or the socket.
WSAENOTCONN	The connection has been reset when SO_KEEPALIVE is set.
WSAENOTSOCK	The descriptor is not a socket.

Remarks

This 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 (out of band (OOB) data for example) is received in the usual data stream and whether broadcast messages can be sent on the socket.

Note If this function is called before the bind (Windows Sockets) function, TCP/IP options will not be checked with TCP/IP until the bind occurs. In this case, the setsockopt function call will always succeed, but the bind function call may fail because of an early setsockopt failing.

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 the 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 column. The Type column identifies the type of data addressed by optval.

level= SOL_SOCKET

Value	Type	Description
SO_BROADCAST	BOOL	Allows transmission of broadcast messages on the socket.
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_GROUP_PRIORITY	int	Reserved.
SO_KEEPALIVE	BOOL	Sends keep-alives. Not supported on ATM sockets (results in an error).
SO_LINGER structure	LINGER	Lingers on close if unsent data is present.
SO_OOBINLINE	BOOL	Receives OOB data in the usual data stream.
SO_RCVBUF	int	Specifies the total per-socket buffer space reserved for receives. For Windows CE .NET 4.1 and later, the default buffer space is set to 8192 bytes. You can change the per-socket buffer space by calling setsockopt. Note This option is only supported for SOCK_DGRAM sockets.
SO_REUSEADDR	BOOL	Allows the socket to be bound to an address that is already in use. (See the bind (Windows Sockets) function.) Not applicable on ATM sockets.
SO_SNDBUF	int	Specifies the total per-socket buffer space reserved for sends. This is unrelated to SO_MAX_MSG_SIZE or the size of a TCP window. Care should be taken when setting the SO_SNDBUF value as setting this value either too high or too low can have a negative effect on performance. It is also important to note that a value of 0 is not supported for SO_SNDBUF.

level = IPPROTO_TCP1

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

1 included for backward compatibility with Winsock 1.1*.*

level= NSPROTO_IPX

Note Windows CE .NET does not support IPX.

The following table shows BSD options not supported for setsockopt .

Value	Type	Description
SO_ACCEPTCONN	BOOL	Sets socket listening.
SO_RCVLOWAT	int	Sets recv low watermark.
SO_RCVTIMEO	int	Sets time-out for recv.
SO_SNDLOWAT	int	Sets send low watermark.
SO_SNDTIMEO	int	Sets time-out value for send.
SO_TYPE	Int	Sets socket type.

SO_CONDITIONAL_ACCEPT

Setting the SO_CONDITIONAL_ACCEPT socket option to TRUE delays the acknowledgment of a connection until after the WSAAccept condition function is called. If FALSE, the connection may be accepted before the condition function is called, but the connection will be disconnected if the condition function rejects the call. This option must be set before calling the listen function, otherwise WSAEINVAL is returned. SO_CONDITIONAL_ACCEPT is only supported for TCP and ATM.

TCP sets SO_CONDITIONAL_ACCEPT to FALSE by default, and therefore by default the connection will be accepted before WSAAccept is called. When set to TRUE, the conditional decision must be made within the TCP connection time-out. CF_DEFER connections are still subject to the time-out.

ATM sets SO_CONDITIONAL_ACCEPT to TRUE by default.

SO_DEBUG

Windows Sockets service providers are encouraged, but not required, to supply output debug information if the SO_DEBUG option is set by an application. The mechanism for generating the debug information and the form it takes are beyond the scope of this document.

SO_GROUP_PRIORITY

Reserved.

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 code 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 function is performed. See the closesocket function 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 the l_onoff and l_linger members set appropriately.

SO_REUSEADDR

By default, a socket cannot be bound (see the bind (Windows Sockets) function) to a local address that is already in use. On occasion, however, it can be necessary to reuse an address in this way. Because 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.

SO_RCVBUF and SO_SNDBUF

When a Windows Sockets implementation supports the SO_RCVBUF and SO_SNDBUF options, an application can request different buffer sizes (larger or smaller) by calling setsockopt. The call to setsockopt can succeed even when the implementation did not provide the whole amount requested. An application must call getsockopt (Windows Sockets) with the same option to check the buffer size actually provided.

PVD_CONFIG

The PVD_CONFIG object stores the configuration information for the service provider associated with the socket specified in the s parameter. The exact format of this data structure is specific to each service provider.

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.

Notes for IrDA Sockets

The Af_irda.h header file must be explicitly included.
IrDA provides a settable socket option. The following table shows this option.

Value Type Description

IRLMP_IAS_SET *IAS_SET Sets IAS attributes

Value	Type	Description
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 Winsock interface, but such access is not typically used by applications and exists primarily to support connections to non-Windows devices that are not compliant with the Winsock IrDA conventions.

The following structure shows IAS_SET used with the IRLMP_IAS_SET setsockopt option to manage the local IAS database.

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

The following structure shows IAS_QUERY used with the IRLMP_IAS_QUERY setsockopt option to query a peer's IAS database.

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 *LPIAS_QUERY;

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

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Winsock2.h.
Link Library: Ws2.lib.