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:

Note that a SAN service provider does not support the following error codes for WSPConnect:

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

See also

WSABUF

WSPBind

WSPEnumNetworkEvents

WSPEventSelect

WSPIoctl

WSPRecv

WSPSocket

Send comments about this topic to Microsoft