LPFN_CONNECTEX callback function (mswsock.h)

The ConnectEx function establishes a connection to a specified socket, and optionally sends data once the connection is established. The ConnectEx function is only supported on connection-oriented sockets.

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

 

Syntax

LPFN_CONNECTEX LpfnConnectex;

BOOL LpfnConnectex(
  [in]           SOCKET s,
  [in]           const sockaddr *name,
  [in]           int namelen,
  [in, optional] PVOID lpSendBuffer,
  [in]           DWORD dwSendDataLength,
  [out]          LPDWORD lpdwBytesSent,
  [in]           LPOVERLAPPED lpOverlapped
)
{...}

Parameters

[in] s

A descriptor that identifies an unconnected, previously bound socket. See Remarks for more information.

[in] name

A pointer to
a sockaddr structure that specifies the address to which to connect. For IPv4, the sockaddr contains AF_INET for the address family, the destination IPv4 address, and the destination port. For IPv6, the sockaddr structure contains AF_INET6 for the address family, the destination IPv6 address, the destination port, and may contain additional IPv6 flow and scope-id information.

[in] namelen

The length, in bytes, of the sockaddr structure pointed to by the name parameter.

[in, optional] lpSendBuffer

A pointer to the buffer to be transferred after a connection is established. This parameter is optional. If the TCP_FASTOPEN option is enabled on s before ConnectEx is called, then some of this data may be sent during connection establishment.

[in] dwSendDataLength

The length, in bytes, of data pointed to by the lpSendBuffer parameter. This parameter is ignored when the lpSendBuffer parameter is NULL.

[out] lpdwBytesSent

On successful return, this parameter points to a DWORD value that indicates the number of bytes that were sent after the connection was established. The bytes sent are from the buffer pointed to by the lpSendBuffer parameter. This parameter is ignored when the lpSendBuffer parameter is NULL.

[in] lpOverlapped

An OVERLAPPED structure used to process the request. The lpOverlapped parameter must be specified, and cannot be NULL.

Return value

On success, the ConnectEx 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 overlapped operation completes.

If the error code returned is WSAECONNREFUSED, WSAENETUNREACH, or WSAETIMEDOUT, the application can call ConnectEx, WSAConnect, or connect again on the same socket.

Error code Description
WSANOTINITIALISED
A successful WSAStartup function call must occur before using ConnectEx.
WSAENETDOWN
The network subsystem has failed.
WSAEADDRINUSE
The local address of the socket is already in use, and the socket was not marked to allow address reuse with SO_REUSEADDR. This error usually occurs during a bind operation, but the error could be delayed until a ConnectEx function call, if the bind function was called with a wildcard address (INADDR_ANY or in6addr_any) specified for the local IP address. A specific IP address needs to be implicitly bound by the ConnectEx function.
WSAEALREADY
A nonblocking connect, WSAConnect, or ConnectEx function call is in progress on the specified socket.
WSAEADDRNOTAVAIL
The remote address is not a valid address, such as ADDR_ANY (the ConnectEx function is only supported for connection-oriented sockets).
WSAEAFNOSUPPORT
Addresses in the specified family cannot be used with this socket.
WSAECONNREFUSED
The attempt to connect was rejected.
WSAEFAULT
The name, lpSendBuffer, or lpOverlapped parameter is not a valid part of the user address space, or namelen is too small.
WSAEINVAL
The parameter s is an unbound or a listening socket.
WSAEISCONN
The socket is already connected.
WSAENETUNREACH
The network cannot be reached from this host at this time.
WSAEHOSTUNREACH
A socket operation was attempted to an unreachable host.
WSAENOBUFS
No buffer space is available; the socket cannot be connected.
WSAENOTSOCK
The descriptor is not a socket.
WSAETIMEDOUT
The attempt to connect timed out without establishing a connection.

Remarks

The ConnectEx function combines several socket functions into a single API/kernel transition. The following operations are performed when a call to the ConnectEx function completes successfully:

  • A new connection is established.
  • An optional block of data is sent after the connection is established.

For applications targeted to Windows Vista and later, consider using the WSAConnectByList or WSAConnectByName function which greatly simplify client application design.

The ConnectEx function can only be used with connection-oriented sockets. The socket passed in the s parameter must be created with a socket type of SOCK_STREAM, SOCK_RDM, or SOCK_SEQPACKET.

The lpSendBuffer parameter points to a buffer of data to send after the connection is established. The dwSendDataLength parameter specifies the length in bytes of this data to send. An application can request to send a large buffer of data using the ConnectEx in the same way that the send and WSASend functions can be used. But developers are strongly advised against sending a huge buffer in a single call using ConnectEx, because this operation uses a large amount of system memory resources until the whole buffer has been sent.

If the ConnectEx function is successful, a connection was established and all of the data pointed to by the lpSendBuffer parameter was sent to the address specified in the sockaddr structure pointed to by the name parameter.

Note  The function pointer for the ConnectEx 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_CONNECTEX, a globally unique identifier (GUID) whose value identifies the ConnectEx extension function. On success, the output returned by the WSAIoctl function contains a pointer to the ConnectEx function. The WSAID_CONNECTEX GUID is defined in the Mswsock.h header file.
 

The ConnectEx function uses overlapped I/O. As a result, the ConnectEx function enables an application to service a large number of clients with relatively few threads. In contrast, the WSAConnect function, which does not use overlapped I/O, usually requires a separate thread to service each connection request when simultaneous requests are received.

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.

 

Connection-oriented sockets are often unable to complete their connection immediately, and therefore the operation is initiated and the function immediately returns with the ERROR_IO_PENDING or WSA_IO_PENDING error. When the connect operation completes and success or failure is achieved, status is reported using the completion notification mechanism indicated in lpOverlapped. As with all overlapped function calls, you can use events or completion ports as the completion notification mechanism. The lpNumberOfBytesTransferred parameter of the GetQueuedCompletionStatus or GetOverlappedResult or WSAGetOverlappedResult function indicates the number of bytes sent in the request.

When the ConnectEx function successfully completes, socket handle s can be passed to only the following functions:

If the TransmitFile function is called on a previously connected socket with both TF_DISCONNECT and TF_REUSE_SOCKET flags, the specified socket is returned to a state in which it is not connected, but still bound. In such cases, the handle of the socket can be passed to the ConnectEx function in its s parameter, but the socket cannot be reused in an AcceptEx function call. Similarly, the accepted socket reused using the TransmitFile function cannot be used in a call to ConnectEx. Note that in the case of a reused socket, ConnectEx 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 ConnectEx call to be delayed.

When the ConnectEx function returns TRUE, the socket s is in the default state for a connected socket. The socket s does not enable previously set properties or options until SO_UPDATE_CONNECT_CONTEXT is set on the socket. Use the setsockopt function to set the SO_UPDATE_CONNECT_CONTEXT option.

For example:

//Need to #include <mswsock.h> for SO_UPDATE_CONNECT_CONTEXT

int iResult = 0;

iResult = setsockopt( s, SOL_SOCKET, SO_UPDATE_CONNECT_CONTEXT, NULL, 0 );

The getsockopt function can be used with the SO_CONNECT_TIME socket option to check whether a connection has been established while ConnectEx is in progress. If a connection has been established, the value returned in the optval parameter passed to the getsockopt function is the number of seconds the socket has been connected. If the socket is not connected, the returned optval parameter contains 0xFFFFFFFF. Checking a connection in this manner is necessary to determine whether connections have been established for a period of time without sending any data; in such cases, it is recommended that such connections be terminated.

For example:


//Need to #include <mswsock.h> for SO_CONNECT_TIME

int seconds;
int bytes = sizeof(seconds);
int iResult = 0;

iResult = getsockopt( s, SOL_SOCKET, SO_CONNECT_TIME,
                      (char *)&seconds, (PINT)&bytes );
if ( iResult != NO_ERROR ) {
    printf( "getsockopt(SO_CONNECT_TIME) failed with error: %u\n", 
        WSAGetLastError() );
}
else {
    if (seconds == 0xFFFFFFFF)
        printf("Connection not established yet\n");
    else
       printf("Connection has been established %ld seconds\n",
           seconds);
}

Note  If a socket is opened, a setsockopt call is made, and then a sendto call is made, Windows Sockets performs an implicit bind function call.
 

If the address parameter of the sockaddr structure pointed to in the name parameter is all zeros, ConnectEx returns the error WSAEADDRNOTAVAIL. Any attempt to reconnect an active connection will fail with the error code WSAEISCONN.

When a connected socket becomes closed for any reason, it is recommended that the socket be discarded and a new socket created. The reasoning for this is that it is safest to assume that when things go awry on a connected socket for any reason, the application must discard the socket and create the needed socket again in order to return to a stable point.

If the DisconnectEx function is called with the TF_REUSE_SOCKET flag, the specified socket is returned to a state in which it is not connected, but still bound. In such cases, the handle of the socket can be passed to the ConnectEx function in its s parameter.

The interval of time that must elapse before TCP can release a closed connection and reuse its resources is known as the TIME_WAIT state or the 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 reused. 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.

Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Requirements

Requirement Value
Minimum supported client Windows 8.1, Windows Vista [desktop apps | UWP apps]
Minimum supported server Windows Server 2003 [desktop apps | UWP apps]
Target Platform Windows
Header mswsock.h

See also

AcceptEx

DisconnectEx

ExitThread

GetOverlappedResult

GetQueuedCompletionStatus

OVERLAPPED

ReadFile

TransmitFile

WSAConnect

WSAConnectByList

WSAConnectByName

WSAGetLastError

WSAIoctl

WSARecv

WSASend

WSAStartup

Winsock Functions

Winsock Reference

WriteFile

bind

closesocket

connect

getsockopt

recv

send

sendto

setsockopt

sockaddr