Export (0) Print
Expand All
Expand Minimize
0 out of 1 rated this helpful - Rate this topic

DisconnectEx function

The DisconnectEx function closes a connection on a socket, and allows the socket handle to be reused.

Note  This function is a Microsoft-specific extension to the Windows Sockets specification.

Syntax


BOOL DisconnectEx(
  _In_  SOCKET hSocket,
  _In_  LPOVERLAPPED lpOverlapped,
  _In_  DWORD dwFlags,
  _In_  DWORD reserved
);

Parameters

hSocket [in]

A handle to a connected, connection-oriented socket.

lpOverlapped [in]

A pointer to an OVERLAPPED structure. If the socket handle has been opened as overlapped, specifying this parameter results in an overlapped (asynchronous) I/O operation.

dwFlags [in]

A set of flags that customizes processing of the function call. When this parameter is set to zero, no flags are set. The dwFlags parameter can have the following value.

FlagMeaning
TF_REUSE_SOCKET

Prepares the socket handle to be reused. When the DisconnectEx request completes, the socket handle can be passed to the AcceptEx or ConnectEx function.

Note  The socket level disconnect is subject to the behavior of the underlying transport. For example, a TCP socket may be subject to the TCP TIME_WAIT state, causing the DisconnectEx call to be delayed.

 

reserved [in]

Reserved. Must be zero. If nonzero, WSAEINVAL is returned.

Return value

On success, the DisconnectEx function returns TRUE. On failure, the function returns FALSE. Use the WSAGetLastError function to get extended error information. If a call to the WSAGetLastError function returns ERROR_IO_PENDING, the operation initiated successfully and is in progress. Under such circumstances, the call may still fail when the operation completes.

Error codeDescription
WSAEFAULT

The system detected an invalid pointer address in attempting to use a pointer argument. This error is returned if an invalid pointer value was passed in the lpOverlapped parameter.

WSAEINVAL

The invalid parameter was passed. This error is returned if the dwFlags parameter was specified with a zero value other than TF_REUSE_SOCKET.

WSAENOTCONN

The socket is not connected. This error is returned if the socket s parameter was not in a connected state. This error can also be returned if the socket was in the transmit closing state from a previous request and the dwFlags parameter was not set to TF_REUSE_SOCKET to request a reuse of the socket.

 

Remarks

The DisconnectEx function does not support datagram sockets. Therefore, the socket specified by hSocket must be connection-oriented, such as a SOCK_STREAM, SOCK_SEQPACKET, or SOCK_RDM socket.

Note  The function pointer for the DisconnectEx function must be obtained at run time by making a call to the WSAIoctl function with the SIO_GET_EXTENSION_FUNCTION_POINTER opcode specified. The input buffer passed to the WSAIoctl function must contain WSAID_DISCONNECTEX, a globally unique identifier (GUID) whose value identifies the DisconnectEx extension function. On success, the output returned by the WSAIoctl function contains a pointer to the DisconnectEx function. The WSAID_DISCONNECTEX GUID is defined in the Mswsock.h header file.

When lpOverlapped is not NULL, overlapped I/O might not finish before DisconnectEx returns, resulting in the DisconnectEx function returning FALSE and a call to the WSAGetLastError function returning ERROR_IO_PENDING. This design enables the caller to continue processing while the disconnect operation completes. Upon completion of the request, Windows sets either the event specified by the hEvent member of the OVERLAPPED structure, or the socket specified by hSocket, to the signaled state.

Note   All I/O initiated by a given thread is canceled when that thread exits. For overlapped sockets, pending asynchronous operations can fail if the thread is closed before the operations complete. See ExitThread for more information.

The TIME_WAIT state determines the time that must elapse before TCP can release a closed connection and reuse its resources. This interval between closure and release is known as the TIME_WAIT state or 2MSL state. During this time, the connection can be reopened at much less cost to the client and server than establishing a new connection. The TIME_WAIT behavior is specified in RFC 793 which requires that TCP maintains a closed connection for an interval at least equal to twice the maximum segment lifetime (MSL) of the network. When a connection is released, its socket pair and internal resources used for the socket can be used to support another connection.

Windows TCP reverts to a TIME_WAIT state subsequent to the closing of a connection. While in the TIME_WAIT state, a socket pair cannot be re-used. The TIME_WAIT period is configurable by modifying the following DWORD registry setting that represents the TIME_WAIT period in seconds.

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\TCPIP\Parameters\TcpTimedWaitDelay

By default, the MSL is defined to be 120 seconds. The TcpTimedWaitDelay registry setting defaults to a value 240 seconds, which represents 2 times the maximum segment lifetime of 120 seconds or 4 minutes. However, you can use this entry to customize the interval. Reducing the value of this entry allows TCP to release closed connections faster, providing more resources for new connections. However, if the value is too low, TCP might release connection resources before the connection is complete, requiring the server to use additional resources to re-establish the connection. This registry setting can be set from 0 to 300 seconds.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Mswsock.h

See also

Winsock Reference
Winsock Functions
OVERLAPPED
ConnectEx
connect
AcceptEx
WSAGetLastError

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.