WSPSetSockOpt

The WSPSetSockOpt function sets a socket option.

int WSPSetSockOpt (
  SOCKET s,                  
  int level,                 
  int optname,               
  const char FAR * optval,   
  int optlen,                
  LPINT lpErrno              
);
 

Parameters

s

[in] A descriptor identifying a socket.

level

[in] The level at which the option is defined; the supported levels include SOL_SOCKET. (See annex for more protocol-specific levels.)

optname

[in] The socket option for which the value is to be set.

optval

[in] A pointer to the buffer in which the value for the requested option is supplied.

optlen

[in] The size of the optval buffer.

lpErrno

[out] A pointer to the error code.

Remarks

WSPSetSockOpt 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 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 which 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. optlen should be equal to sizeof(int) for Boolean options. For other options, optval points to the an integer or structure that contains the desired value for the option, and optlen is the length of the integer or structure.

level = SOL_SOCKET

Calling WSPGetSockOpt with an unsupported option will result in an error code of WSAENOPROTOOPT being returned in lpErrno.

SO_DEBUG

Windows Sockets service providers are encouraged (but not required) to supply output debug information if the SO_DEBUG option is set by a Windows Sockets SPI client. The mechanism for generating the debug information and the form it takes are beyond the scope of this specification.

SO_GROUP_PRIORITY

Reserved for future use with socket groups: Group priority indicates the priority of the specified socket relative to other sockets within the socket group. Values are non-negative integers, with zero corresponding to the highest priority. Priority values represent a hint to the service provider about how potentially scarce resources should be allocated. For example, whenever two or more sockets are both ready to transmit data, the highest priority socket (lowest value for SO_GROUP_PRIORITY) should be serviced first, with the remainder serviced in turn according to their relative priorities.

The WSAENOPROTOOPT error is indicated for non group sockets or for service providers which do not support group sockets.

SO_KEEPALIVE

A Windows Sockets SPI client 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

SO_LINGER controls the action taken when unsent data is queued on a socket and a WSPCloseSocket is performed. See WSPCloseSocket for a description of the way in which the SO_LINGER settings affect the semantics of WSPCloseSocket. The Windows Sockets SPI client sets the desired behavior by creating a struct linger (pointed to by the optval argument) with the following elements:

struct linger {
    u_short    l_onoff;
    u_short    l_linger;
}
 

To enable SO_LINGER, a Windows Sockets SPI client should set l_onoff to a nonzero value, set l_linger to zero or the desired time-out (in seconds), and call WSPSetSockOpt. To enable SO_DONTLINGER (that is, disable SO_LINGER) l_onoff should be set to zero and WSPSetSockOpt should be called. Note that enabling SO_LINGER with a nonzero time-out on a nonblocking socket is not recommended (see section 4.1.7. WSPCloseSocket for details).

Enabling SO_LINGER also disables SO_DONTLINGER, and vice versa. Note that if SO_DONTLINGER is DISABLED (that is, SO_LINGER is ENABLED) then no time-out value is specified. In this case, the time-out used is implementation dependent. If a previous time-out has been established for a socket (by enabling SO_LINGER), then this time-out value should be reinstated by the service provider.

SO_REUSEADDR

By default, a socket cannot be bound (see WSPBind) to a local address which is already in use. On occasion, however, it may be desirable 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 WSPBind on a socket should be allowed to bind to a local address that is already in use by another socket, the Windows Sockets SPI client should set the SO_REUSEADDR socket option for the socket before issuing the WSPBind. Note that the option is interpreted only at the time of the WSPBind: it is therefore unnecessary (but harmless) to set the option on a socket which is not to be bound to an existing address, and setting or resetting the option after the WSPBind has no effect on this or any other socket.

SO_SNDBUF

When a Windows Sockets implementation supports the SO_RCVBUF and SO_SNDBUF options, a Windows Sockets SPI client can request different buffer sizes (larger or smaller). The call can succeed even though the service provider did not make available the entire amount requested. A Windows Sockets SPI client must call WSPGetSockOpt with the same option to check the buffer size actually provided.

PVD_CONFIG

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.

Return Values

If no error occurs, WSPSetSockOpt returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code is available in lpErrno.

Error Codes

QuickInfo

  Windows NT: Yes
  Windows: Yes
  Windows CE: Unsupported.
  Header: Declared in ws2spi.h.

See Also

WSPBind, WSPGetSockOpt, WSPIoctl, WSPSocket, WSPEventSelect