WSPConnect function
WSPConnect establishes the connection of a socket to a peer, exchanges connect data, and specifies required quality of service based on the supplied flow specification.
Syntax
int WSPConnect(
_In_ SOCKET s,
_In_ const struct sockaddr FAR *name,
_In_ int namelen,
_In_ LPWSABUF lpCallerData,
_Out_ LPWSABUF lpCalleeData,
_In_ LPQOS lpSQOS,
_In_ LPQOS lpGQOS,
_Out_ LPINT lpErrno
);
Parameters
s [in]
Descriptor that identifies an unconnected socket.name [in]
Pointer to a sockaddr structure that contains the address of the remote peer to which the socket connects. The SAN service provider does not strictly interpret the name parameter as a pointer to a sockaddr structure. The name parameter is cast this way for Windows Sockets compatibility. The SAN service provider interprets the actual structure as a sockaddr_in structure, which is used with the TCP/IP protocol. For more information about sockaddr and sockaddr_in, see the Microsoft Windows SDK documentation.namelen [in]
Size, in bytes, of the buffer at name.lpCallerData [in]
Pointer to a WSABUF structure that contains any user data that the SAN service provider transmits to the remote peer during connection establishment.lpCalleeData [out]
Pointer to a WSABUF structure that receives any user data that the SAN service provider receives from the remote peer during connection establishment.lpSQOS [in]
Pointer to a QoS structure that contains flow specifications for socket S, one for each direction. For information about QoS, see the Windows SDK documentation.lpGQOS [in]
Reserved.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. |
| WSAEALREADY | Nonblocking WSPConnect call is in progress on the specified socket.
Note In order to preserve backward compatibility, this error is reported as WSAEINVAL to Windows Sockets version 1.1 applications that link to either Winsock.dll or Wsock32.dll.
|
| WSAEADDRNOTAVAIL | Remote address is not a valid address (for example, ADDR_ANY). |
| WSAECONNREFUSED | The attempt to connect was rejected by the remote Windows Sockets switch or the remote SAN provider because of insufficient hardware resources or for any other reason. |
| WSAECONNRESET | The underlying provider-level connection has been torn down. |
| WSAEHOSTUNREACH | Remote host does not exist on the SAN subnet. The switch does not attempt to use the TCP/IP service provider to establish the connection. |
| WSAEFAULT | The name or namelen parameter is not a valid part of the user address space, the namelen parameter is too small, the buffer length for the lpCalleeData, lpSQOS, or lpGQOS parameter is too small, or the buffer length for lpCallerData parameter is too large. |
| WSAEINVAL | Parameter S identifies a listening socket. |
| WSAEISCONN | Socket is already connected. |
| WSAENETUNREACH | Network cannot currently be reached from the host. |
| WSAENOBUFS | No buffer space available; the socket cannot be connected. |
| WSAENOTSOCK | Descriptor is not a socket. |
| WSAEOPNOTSUPP | Flow specifications specified in the lpSQOS parameter cannot be satisfied. |
| WSAEPROTONOSUPPORT | SAN service provider does not support the lpCallerData parameter. |
| WSAETIMEDOUT | Attempt to connect timed out without establishing a connection. |
| WSAEWOULDBLOCK | Socket is marked as nonblocking and the connection cannot be completed immediately. |
| WSAEADDRINUSE | There is an existing connection that uses the same 4-tuple (local IP address, local port number, remote IP address, remote port number) that is specified for the attempted connection. The switch does not attempt to use the TCP/IP service provider to establish the connection. |
Note that a SAN service provider does not support the following error codes for WSPConnect:
| Return code | Description |
|---|---|
| WSAEINTR | The Windows Sockets switch never issues cancel blocking calls to a SAN service provider. |
| WSAEINPROGRESS | The Windows Sockets switch never issues cancel blocking calls to a SAN service provider. |
| WSAEAFNOSUPPORT | All addresses in the WSK address families can be used with this socket. |
| WSAEACCES | The current version of Windows Sockets Direct does not support SAN service providers handling sockets that receive datagrams. Also, broadcast addresses are not supported. |
Remarks
The Windows Sockets switch calls a SAN service provider's WSPConnect function to create a connection from a local socket to the specified destination address and to perform other ancillary operations that occur at connect time. Before calling the WSPConnect function, the switch always calls the SAN service provider's WSPBind function to bind the local socket to a local IP address that is associated with one of the network interface cards (NICs) serviced by the SAN service provider. This IP address is fully qualified; that is, the sin_port and sin_addr members of its sockaddr_in structure are both set to nonzero values.
To establish the connection from a local socket to a remote peer, WSPConnect requires that the name parameter point to a fully qualified IP address that specifies the address of that remote peer (that is, the name of that remote peer). After the WSPConnect call completes successfully, the switch can use the socket to send and receive data. If the switch calls WSPConnect to reconnect a socket that is already connected to a peer, the call fails and returns the WSAEISCONN error code.
The Windows Sockets switch always requests a connection to a local socket in nonblocking mode. To inform the SAN service provider that any subsequent WSPConnect call executes in nonblocking mode and to request notification of connection events, the switch calls the SAN service provider's WSPEventSelect function and passes the FD_CONNECT code and the event object to be associated with that code.
If the SAN service provider's WSPConnect function cannot complete a connection request immediately, the SAN service provider's connection operation proceeds. However, WSPConnect returns with the error WSAEWOULDBLOCK to indicate that the socket is marked as nonblocking and that the connection operation cannot be completed immediately. After the connection operation completes, the SAN service provider can call the Win32 SetEvent function to signal the event object that was previously registered in the WSPEventSelect call. The switch then calls the SAN service provider's WSPEnumNetworkEvents function to obtain the result of the connection operation. To indicate success or the reason for failure of the connection operation, the SAN service provider returns a WSANETWORKEVENTS structure that contains an FD_CONNECT event and possibly an error code associated with FD_CONNECT. For more information about SetEvent, see the Microsoft Windows SDK documentation.
The switch is responsible for allocating memory that is directly or indirectly pointed to by any of the parameters that it specifies.
A SAN service provider can optionally support the following:
Passing user data for the connection to and from the peer
The exact format of the user data is specific to the WSK address families and the applications involved. If the lpCallerData parameter is NULL, the SAN service provider does not send any user data to the peer. The lpCalleeData parameter points to a WSABUF structure that contains user data that the peer supplied to establish the connection. The switch initially sets the len member of WSABUF to the maximum number of bytes of data that the SAN service provider can copy into the buffer to which the buf member of WSABUF points. If the SAN service provider does not receive any user data from the peer, it sets the len member of this WSABUF structure to zero. The information to which lpCalleeData points is valid after the connection operation completes. The FD_CONNECT code notifies that a connection operation completed.
Quality of service (QoS)
If a SAN service provider supports QoS, the switch can use QoS parameters in a connection request to override any previous QoS specification made for the socket through the WSPIoctl function with either the SIO_SET_QOS or SIO_SET_GROUP_QOS codes.
The lpSQOS parameter specifies the flow specifications for socket S, one for each direction, followed by any additional provider-specific parameters. If either the SAN service provider in general or the socket in particular cannot honor the QoS request, the SAN service provider returns the WSAEOPNOTSUPP error code. The sending or receiving flow specification values are ignored, respectively, for any unidirectional sockets. If the switch does not supply provider-specific parameters, it sets the buf and len members of the ProviderSpecific member of the QoS structure to which the lpSQOS points to NULL and zero, respectively. The switch sets the lpSQOS parameter to NULL if it does not supply or forward QoS information.
If a SAN service provider fails the connection request, the switch attempts to use the TCP/IP provider to establish the connection unless the SAN service provider returned one of the following error codes as the result of its connection operation:
WSAECONNRESET
Indicates that no application is listening on the specified port at the destination address.WSAECONNREFUSED
Indicates that the remote application actively refused the connection request.WSAEHOSTUNREACH
Indicates that the destination address does not exist on the SAN subnet.
Requirements
Target platform |
Desktop |
Version |
Requires Windows Sockets version 2.0. |
Header |
Ws2spi.h (include Ws2spi.h) |
See also