linger_state() [2/2]

socket & xtd::net::sockets::socket::linger_state

(

const xtd::net::sockets::linger_option &

value

)

Sets a value that specifies whether the xtd::net::sockets::socket will delay closing a socket in an attempt to send all pending data.

Parameters

value

A xtd::net::sockets::sockets::linger_option that specifies how to linger while closing a socket.

Returns

This current instance.

Exceptions

xtd::net::sockets::socket_exception	This option is valid for a datagram socket only.
xtd::object_closed_exception	The xtd::net::sockets::socket has been closed.

Remarks

The xtd::net::sockets::socket::linger_state property changes the way xtd::net::sockets::socket::close method behaves. This property when set modifies the conditions under which the connection can be reset by Winsock. Connection resets can still occur based on the IP protocol behavior.

This property controls the length of time that a connection-oriented connection will remain open after a call to xtd::net::sockets::socket::close when data remains to be sent.

When you call methods to send data to a peer, this data is placed in the outgoing network buffer. This property can be used to ensure that this data is sent to the remote host before the xtd::net::sockets::socket::close method drops the connection.

To enable lingering, create a xtd::net::sockets::linger_option instance containing the desired values, and set the xtd::net::sockets::socket::linger_state property to this instance.

The following table describes the behavior of the xtd::net::sockets::socket::close method for the possible values of the xtd::net::sockets::inger_option::enabled property and the xtd::net::sockets::linger_option::linger_time property stored in the xtd::net::sockets::socket::linger_state property.

xtd::net::sockets::linger_state::enabled	xtd::net::sockets::linger_state::linger_time	Behavior
false (disabled), the default value	The time-out is not applicable, (default).	Attempts to send pending data until the default IP protocol time-out expires.
true (enabled)	A nonzero time-out.	Attempts to send pending data until the specified time-out expires, and if the attempt fails, then Winsock resets the connection.
true (enabled)	A zero time-out.	Discards any pending data. For connection-oriented socket (TCP, for example), Winsock resets the connection.

The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a socket when the xtd::net::sockets::socket::linger_state property is not set.

When the xtd::net::sockets::linger_option::linger_time property stored in the xtd::net::sockets::socket::linger_state property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and override.

Note

If you receive a xtd::net::sockets::socket_exception exception, use the xtd::net::sockets::socket_exception::error_code property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation in the MSDN library for a detailed description of the error.