WSPGetSockOpt
The WSPGetSockOpt function retrieves a socket option.
int WSPGetSockOpt (
SOCKET s,
int level,
int optname,
char FAR * optval,
LPINT 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 retrieved.
-
optval
-
[out] A pointer to the buffer in which the value for the requested option is to be returned.
-
optlen
-
[in/out] A pointer to the size of the optval buffer.
-
lpErrno
-
[out] A pointer to the error code.
Remarks
WSPGetSockOpt retrieves the current value for a socket option associated with a socket of any type, in any state, and stores the result in optval. Options can exist at multiple protocol levels, but they are always present at the uppermost "socket'' level. Options affect socket operations, such as the routing of packets and out-of-band data transfer.
The value associated with the selected option is returned in the buffer optval. The integer pointed to by optlen should originally contain the size of this buffer; on return, it will be set to the size of the value returned. For SO_LINGER, this will be the size of a structure linger; for most other options it will be the size of an integer.
The Windows Sockets SPI client is responsible for allocating any memory space pointed to directly or indirectly by any of the parameters it specifies.
If the option was never set with WSPSetSockOpt, then WSPGetSockOpt returns the default value for the option.
level = SOL_SOCKET
Value |
Type |
Meaning |
Default |
SO_ACCEPTCONN |
BOOL |
Socket is WSPListening. |
FALSE unless a WSPListen has been performed |
SO_BROADCAST |
BOOL |
Socket is configured for the transmission of broadcast messages. |
FALSE |
SO_DEBUG |
BOOL |
Debugging is enabled. |
FALSE |
SO_DONTLINGER |
BOOL |
If true, the SO_LINGER option is disabled. |
TRUE |
SO_DONTROUTE |
BOOL |
Routing is disabled. |
FALSE |
SO_ERROR |
int |
Retrieve error status and clear. |
0 |
SO_GROUP_ID |
GROUP |
Reserved for future use with socket groups: The identifier of the group to which this socket belongs. |
NULL |
SO_GROUP_PRIORITY |
int |
Reserved for future use with socket groups: The relative priority for sockets that are part of a socket group. |
0 |
SO_KEEPALIVE |
BOOL |
Keepalives are being sent. |
FALSE |
SO_LINGER |
struct linger |
Returns the current linger options. |
1 is on (default), 0 is off |
SO_MAX_MSG_SIZE |
unsigned int |
Maximum size of a message for message-oriented socket types (for example, SOCK_DGRAM). Has no meaning for stream oriented sockets. |
Implementation dependent |
SO_OOBINLINE |
BOOL |
Out-of-band data is being received in the normal data stream. |
FALSE |
SO_PROTOCOL_INFO |
WSA
PROTOCOL
_INFO |
Description of protocol info for protocol that is bound to this socket. |
protocol dependent |
SO_RCVBUF |
int |
Total per-socket buffer space reserved for receives. This is unrelated to SO_MAX_MSG_SIZE or the size of a TCP window. |
Implementation dependent |
SO_REUSEADDR |
BOOL |
The socket can be bound to an address which is already in use. |
FALSE |
SO_SNDBUF |
int |
Total per-socket buffer space reserved for sends. This is unrelated to SO_MAX_MSG_SIZE or the size of a TCP window. |
Implementation dependent |
SO_TYPE |
int |
The type of the socket (for example, SOCK_STREAM). |
As created with socket. |
PVD_CONFIG |
Service Provider Dependent |
An "opaque" data structure object from the service provider associated with socket s. This object stores the current configuration information of the service provider. The exact format of this data structure is service provider specific. |
Implementation dependent |
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_ERROR
-
The SO_ERROR option returns and resets the per-socket based error code (which is not necessarily the same as the per-thread error code that is maintained by the WS2_32.DLL). A successful Windows Sockets call on the socket does not reset the socket-based error code returned by the SO_ERROR option.
-
SO_GROUP_ID
-
Reserved for future use with socket groups: This is a get-only socket option which supplies the identifier of the group this socket belongs to. Note that socket group IDs are unique across all processes for a give service provider. If this socket is not a group socket, the value is NULL.
-
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 code 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 service 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 obtains 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;
}
-
SO_MAX_MSG_SIZE
-
This is a get-only socket option which indicates the maximum size of an outbound send message for message-oriented socket types (for example, SOCK_DGRAM) as implemented by the service provider. It has no meaning for byte stream oriented sockets. There is no provision to determine the maximum inbound message size.
-
SO_PROTOCOL_INFOW
-
This is a get-only option which supplies the WSAPROTOCOL_INFO structure associated with this socket. See WSCEnumProtocols for more information about this structure.
-
SO_SNDBUF
-
When a Windows Sockets service provider supports the SO_RCVBUF and SO_SNDBUF options, a Windows Sockets SPI client can use WSPSetSockOpt to 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 this function with the same option to check the buffer size actually provided.
-
SO_REUSEADDR
-
By default, a socket can not 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.
-
PVD_CONFIG
-
This option retrieves an "opaque" data structure object from the service provider associated with socket s. This object stores the current configuration information of the service provider. The exact format of this data structure is service provider specific.
Return Values
If no error occurs, WSPGetSockOpt returns zero. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code is available in lpErrno.
Error Codes
WSAENETDOWN |
The network subsystem has failed. |
WSAEFAULT |
One of the optval or the optlen arguments is not a valid part of the user address space, or the optlen argument is too small. |
WSAEINVAL |
level is unknown or invalid. |
WSAEINPROGRESS |
The function is invoked when a callback is in progress. |
WSAENOPROTOOPT |
The option is unknown or unsupported by the indicated protocol family. |
WSAENOTSOCK |
The descriptor is not a socket. |
QuickInfo
Windows NT: Yes
Windows: Yes
Windows CE: Unsupported.
Header: Declared in ws2spi.h.
See Also
WSPSetSockOpt, WSPSocket