Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function establishes a connection to a peer, and exchanges connect data.

Syntax

int WSPConnect(
  SOCKET 
s,
  const struct sockaddr FAR* 
name,
  int 
namelen,
  LPWSABUF
 lpCallerData,
  LPWSABUF
 lpCalleeData,
  LPQOS 
lpSQOS,
  LPQOS 
lpGQOS,
  LPINT 
lpErrno 
);

Parameters

s

[in] Descriptor identifying an unconnected socket.

name

[in] Name of the peer to which the socket is to be connected.

namelen

[in] Length of the name.

lpCallerData

[in] Pointer to the user data that is to be transferred to the peer during connection establishment.

lpCalleeData

[out] Pointer to a buffer into which any user data received from the peer during connection establishment can be copied.

lpSQOS

[in] Reserved.

lpGQOS

[in] Reserved.

lpErrno

[out] Pointer to the error code.

Return Value

If no error occurs, this function returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code is available in lpErrno.

Note:
The Windows Embedded CE version of this function does not support the exchange of data at the time of connection for the default service provider. The default value for lpCalleeDataand lpCallerDatashould both be NULL.

On a blocking socket, the return value indicates success or failure of the connection attempt. If the return error code indicates the connection attempt failed (that is, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the Windows Sockets SPI client can call WSPConnectagain for the same socket.

The following table shows the possible error codes.

Error value Description

WSAENETDOWN

Network subsystem has failed.

WSAEADDRINUSE

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 at the time of bind, but could be delayed until this function if the bindwas to a partially wildcard address (involving ADDR_ANY) and if a specific address needs to be committed at the time of this function.

WSAEINPROGRESS

Blocking Windows Sockets call is in progress or the service provider is still processing a callback function.

WSAEALREADY

Nonblocking WSPConnectcall is in progress on the specified socket.

In order to preserve backward compatibility, this error is reported as WSAEINVAL to Winsock 1.1 applications that link to either Winsock.dll or Wsock32.dll.

WSAEADDRNOTAVAIL

Remote address is not a valid address (for example, ADDR_ANY).

WSAEAFNOSUPPORT

Addresses in the specified family cannot be used with this socket.

WSAECONNREFUSED

Attempt to connect was rejected.

WSAEFAULT

Nameor the namelenparameter is not a valid part of the user address space, the namelenparameter is too small, the buffer length for lpCalleeDatais too small, or the buffer length for lpCallerDatais too large.

WSAEINVAL

Parameter sis a listening socket.

WSAEISCONN

Socket is already connected (connection-oriented sockets only).

WSAENETUNREACH

Network cannot be reached from this host at this time.

WSAENOBUFS

No buffer space is available. The socket cannot be connected.

WSAENOTSOCK

Descriptor is not a socket.

WSAEOPNOTSUPP

Flow specifications cannot be satisfied.

WSAEPROTONOSUPPORT

The lpCallerDataaugment is not supported by the service provider.

WSAETIMEDOUT

Attempt to connect timed out without establishing a connection.

WSAEWOULDBLOCK

Socket is marked as nonblocking and the connection cannot be completed immediately. It is possible to select the socket using the WSPSelectfunction while it is connecting by using the WSPSelectfunction to select it for writing.

WSAEACCES

Attempt to connect datagram socket to broadcast address failed because WSPSetSockOptSO_BROADCAST is not enabled.

Remarks

This function is used to create a connection to the specified destination and to perform a number of other ancillary operations that occur at connect time as well. If the socket, s, is unbound, unique values are assigned to the local association by the system and the socket is marked as bound.

For connection-oriented sockets (for example, type SOCK_STREAM), an active connection is initiated to the specified host using name(an address in the name space of the socket. (For a detailed description, see WSPBind.) When this call completes successfully, the socket is ready to send and receive data. If the address member of the namestructure is all zeroes, WSPConnectwill return the error WSAEADDRNOTAVAIL. Any attempt to reconnect an active connection will fail with the error code WSAEISCONN.

For connection-oriented, nonblocking sockets it is often not possible to complete the connection immediately. In such a case, this function returns with the error WSAEWOULDBLOCK but the operation proceeds. When the success or failure outcome becomes known, it may be reported in one of several ways depending on how the client registers for notification. If the client uses WSPSelect, success is reported in the writefdsset and failure is reported in the exceptfdsset. If the client uses WSPEventSelect, the notification is announced with FD_CONNECT and the error code associated with the FD_CONNECT indicates either success or a specific reason for failure.

For a connectionless socket (for example, type SOCK_DGRAM), the operation performed by WSPConnectis to establish a default destination address so the socket can be used with subsequent connection-oriented send and receive operations ( WSPSend, WSPRecv). Any datagrams received from an address other than the destination address specified will be discarded. If the address member of the namestructure is all zeroes, the socket will be disconnected— the default remote address will be indeterminate, so WSPSendand WSPRecvcalls will return the error code WSAENOTCONN. However, WSPSendToand WSPRecvFromcan still be used. The default destination can be changed by simply calling WSPConnectagain, even if the socket is already connected. Any datagrams queued for receipt are discarded if nameis different from the previous WSPConnect.

For connectionless sockets, namecan indicate any valid address, including a broadcast address. However, to connect to a broadcast address, a socket must have WSPSetSockOptSO_BROADCAST enabled. Otherwise, WSPConnectwill fail with the error code WSAEACCES.

On connectionless sockets, exchange of user-to-user data is not possible and the corresponding parameters will be silently ignored.

The Windows Sockets SPI client is responsible for allocating any memory space pointed to directly or indirectly by any of the parameters it specifies.

The lpCallerDatais a value parameter that contains any user data to be sent along with the connection request. If lpCallerDatais NULL, no user data will be passed to the peer. The lpCalleeDatais a result parameter that will reference any user data passed back from the peer as part of the connection establishment. The lpCalleeData->leninitially contains the length of the buffer allocated by the Windows Sockets SPI client and pointed to by lpCalleeData->buf. The lpCalleeData->lenwill be set to zero if no user data has been passed back. The lpCalleeDatainformation will be valid when the connection operation is complete. For blocking sockets, this will be when the WSPConnectfunction returns. For nonblocking sockets, this will be after the FD_CONNECT notification has occurred. If lpCalleeDatais NULL, no user data will be passed back. The exact format of the user data is specific to the address family the socket belongs to and/or the applications involved.

Requirements

Header ws2spi.h
Library Ws2.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also