WSPGetSockOpt function

Article
06/19/2017

WSPGetSockOpt retrieves the current value of a socket option.

Syntax

int WSPGetSockOpt(
  _In_    SOCKET   s,
  _In_    int      level,
  _In_    int      optname,
  _Out_   char FAR *optval,
  _Inout_          optlen,
  _Out_   LPINT    lpErrno
);

Parameters

s [in]
Descriptor that identifies a socket.
level [in]
Level at which the option is defined. If the TCP_NODELAY option is specified in the optname parameter, level should be IPPROTO_TCP. For all of the other options, use the SOL_SOCKET level.
optname [in]
Socket option for which the value is to be retrieved. For a list of possible socket options, see the Remarks section.
optval [out]
Pointer to a buffer that receives the current value for the socket option that is specified in optname.
optlen [in, out]
Pointer to a variable that receives the size, in bytes, of the value at optval.
lpErrno [out]
Pointer to a variable that receives the error code.

Return value

Returns zero if successful; otherwise, returns SOCKET_ERROR and, at lpErrno, one of the following error codes:

Return code	Description
WSAENETDOWN	Network subsystem failed.
WSAEFAULT	The optval or optlen parameter is not a valid part of the user address space, or the optlen parameter is too small.
WSAEINVAL	The level is unknown or invalid.
WSAENOPROTOOPT	Option is unknown or unsupported by the socket's address family.
WSAENOTSOCK	Descriptor is not a socket.

Note that a SAN service provider does not support the WSAEINPROGRESS error code for WSPGetSockOpt.

Remarks

The Windows Sockets switch calls a SAN service provider's WSPGetSockOpt function to retrieve the current value of an option for a socket, in any state. Options affect socket operations, such as the amount of data that the switch can transfer on the socket for each data transfer operation.

The switch originally sets the integer value at optlen to the size of the buffer at optval. The WSPGetSockOpt function stores the current value for the specified socket option in the buffer at optval and the size, in bytes, of this value at optlen. For most socket options, the size of the option value is the size of an integer.

The switch must allocate any memory space pointed to directly or indirectly by any parameters it specifies.

If the switch never called the SAN service provider's WSPSetSockOpt function to assign a value to an option, the SAN service provider's WSPGetSockOpt function returns default values for options. These default values, along with data types for supported options, are described in the following table. A SAN service provider supports only the options described in this table.

Option	Value	Description
SO_DEBUG	FALSE	Debugging is enabled. Type is BOOL.
SO_GROUP_ID	NULL	Identifier of the socket's group. Type is GROUP.
SO_GROUP_ PRIORITY	0	Relative priority for the socket in its group. Type is Integer.
SO_MAX_MSG_ SIZE	Varies	Maximum outbound (send) size of a message for message-oriented socket types. No specified maximum inbound message size. Not applicable to stream-oriented sockets. Type is unsigned integer.
SO_MAX_RDMA_ SIZE	Varies	Maximum size of a RDMA transfer request. Type is unsigned integer.
SO_RDMA_ THRESHOLD_SIZE	Varies	Minimum size of a RDMA transfer request. Type is unsigned integer.

If the switch calls the SAN service provider's WSPGetSockOpt function with an unsupported option, the SAN service provider returns the WSAENOPROTOOPT error code.

The following list describes additional information for supported options:

SO_DEBUG
SAN service providers are encouraged, but not required, to supply output debug information if applications set the SO_DEBUG option. The mechanism for generating the debug information, and the form it takes, are beyond the scope of this section.
SO_GROUP_ID
This option is reserved for future use with socket groups. The switch currently ignores it. This option supplies the identifier of the group to which this socket belongs. Note that socket group identifiers are unique across all processes that use a SAN service provider. If this socket is not a group socket, the value of the option is NULL.
SO_GROUP_PRIORITY
This option is reserved for future use with socket groups. The switch currently ignores it. Group priority indicates the priority of the socket relative to other sockets within the group. Values are nonnegative integers, with zero corresponding to the highest priority. Priority values are a hint to the SAN service provider about how to allocate potentially scarce resources. 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.

A SAN service provider returns the WSAENOPROTOOPT error code for nongroup sockets, or if the SAN service provider does not support group sockets.
SO_MAX_MSG_SIZE
A socket option that indicates the maximum size of an outbound (send) message for message-oriented socket types as implemented by the SAN service provider. The switch does not pass send requests to the SAN service provider that exceed the size that the SAN service provider returns for the value of this option.

This option has no meaning for byte-stream oriented sockets where the switch assumes that the SAN service provider can send messages of any size.

There is no provision to determine the maximum inbound message size.
SO_MAX_RDMA_SIZE
A socket option that indicates the maximum size of RDMA transfer requests (read or write) as implemented by the SAN service provider. The switch does not pass RDMA transfer requests to the SAN service provider that exceed the size that the SAN service provider returns for the value of this option.
SO_RDMA_THRESHOLD_SIZE
A socket option that indicates the preferred minimum size of RDMA transfer requests (read or write). The switch can set the actual threshold to a value different from the value returned by the SAN service provider. The switch subsequently uses RDMA to transfer data blocks that exceed the size of this threshold and messages to transfer data blocks that are less than or equal to the size of this threshold.
SO_KEEPALIVE
An application can request that a TCP/IP provider enable the use of keep-alive packets on TCPconnections by turning on the SO_KEEPALIVE socket option. A Windows Sockets provider does not need to support the use of keep-alive packets. If a provider does support these packets, 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-alive packets, the WSAENETRESET error value is returned to any calls in progress on the socket, and any subsequent calls will fail with WSAENOTCONN.
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 the algorithm is enabled if this option is disabled). The Nagle algorithm involves buffering send data when unacknowledged data is already "in flight" or buffering send data until a full-size packet can be sent. We highly recommend that TCP/IP service providers enable the Nagle algorithm by default. For most 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. Such applications include those in which many small messages are sent and the time delays between the messages are maintained. You should not set TCP_NODELAY unless you understand what setting TCP_NODELAY involves, because setting TCP_NODELAY can have a significant negative impact on network and application performance.

Requirements

Target platform	Desktop
Version	Requires Windows Sockets version 2.0.
Header	Ws2spi.h (include Ws2spi.h)