setsockopt (Windows Sockets)

Article
11/18/2015

A version of this page is also available for

4/8/2010

This function sets a socket option.

Syntax

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:

IPPROTO_IP

IPPROTO_IPV6

IPPROTO_TCP

IPPROTO_UDP

SOL_SOCKET

SOL_IRLMP

IPPROTO_RAW

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 Value

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 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.

To view SOL_SOCKET options that are are supported for setsockopt, see SOL_SOCKET.

To view IPPROTO_TCP options that are are supported for setsockopt, see IPPROTO_TCP.

To view IPPROTO_IP options that are are supported for setsockopt, see IPPROTO_IP.

To view IPPROTO_IPv6 options that are are supported for setsockopt, see IPPROTO_IPV6.

To view IPPROTO_RAW options that are are supported for setsockopt, see Windows Mobile topic IPPROTO_RAW.

To view SOL_IRLMP options that are are supported for setsockopt, see SOL_IRLMP.

The following list shows BSD options that are not supported for setsockopt .

SO_ACCEPTCONN

SO_RCVLOWAT

SO_RCVTIMEO

SO_SNDLOWAT

SO_SNDTIMEO

SO_TYPE

Notes for IrDA Sockets

The Af_irda.h header file must be explicitly included.
IrDA provides a settable socket options. For more information, see SOL_IRLMP.
Many SO_ level socket options are not meaningful to IrDA. Only SO_LINGER is specifically supported.

For more inforamtion about IrDA support in Windows Embedded CE, see Infrared Communications.

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;

Requirements

Header	winsock2.h
Library	Ws2.lib
Windows Embedded CE	Windows CE 1.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later