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 another socket application and exchanges connect (Windows Sockets)data.

Syntax

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

Parameters

s

[in] Descriptor identifying an unconnected socket.

name

[in] Name of the socket in the other application to which to connect.

namelen

[in] Length of the name.

lpCallerData

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

lpCalleeData

[out] Pointer to the user data that is to be transferred back from the other socket during connection establishment.

lpSQOS

[in] Reserved.

lpGQOS

[in] Reserved.

Return Value

If no error occurs, this function returns zero. If an error occurs, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling the WSAGetLastErrorfunction. On a blocking socket, the return value indicates success or failure of the connection attempt.

Note:
The Windows Embedded CE default TCP/UDP service provider does not support the exchange of data at the time of connection for the default service provider. lpCalleeDataand lpCallerDatashould both be NULL.

With a nonblocking socket, the connection attempt cannot be completed immediately. In this case, WSAConnectwill return SOCKET_ERROR and WSAGetLastErrorwill return WSAEWOULDBLOCK. The application could perform the following actions:

  • Use selectto determine the completion of the connection request by checking if the socket is writeable.

  • If your application is using WSAEventSelectto indicate interest in connection events, then the associated event object will be signaled when the connectoperation is complete (successful or not).

For a nonblocking socket, until the connection attempt completes all subsequent calls to WSAConnecton the same socket will fail with the error code WSAEALREADY.

If the return error code indicates the connection attempt failed (that is, WSAECONNREFUSED, WSAENETUNREACH, or WSAETIMEDOUT), the application can call WSAConnectagain for the same socket. The following table shows a list of possible error codes.

Error code Description

WSANOTINITIALISED

A successful WSAStartupcall must occur before using this function.

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 the execution of the bind (Windows Sockets)function, but it could be delayed until the WSAConnectfunction if the bindfunction operates on a partially wildcard address (involving ADDR_ANY) and if a specific address needs to be "committed" at the time of the WSAConnectfunction.

WSAEINTR

The socket was closed.

WSAEINPROGRESS

A blocking Winsock call is in progress, or the service provider is still processing a callback function.

WSAEALREADY

A nonblocking connect/ WSAConnectcall is in progress on the specified socket.

WSAEADDRNOTAVAIL

The remote address is not a valid address (such as ADDR_ANY).

WSAEAFNOSUPPORT

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

WSAECONNREFUSED

The attempt to connectwas rejected.

WSAEFAULT

The nameor 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

The parameter sis a listening socket.

WSAEISCONN

The socket is already connected (connection-oriented sockets only).

WSAENETUNREACH

The network cannot be reached from this host at this time.

WSAENOBUFS

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

WSAENOTSOCK

The descriptor is not a socket.

WSAEOPNOTSUPP

The structures specified in lpSQOSand lpGQOScannot be satisfied.

WSAEPROTONOSUPPORT

The lpCallerDataargument is not supported by the service provider.

WSAETIMEDOUT

An attempt to connecttimed out without establishing a connection.

WSAEWOULDBLOCK

The socket is marked as nonblocking and the connection cannot be completed immediately.

WSAEACCES

An attempt to connectdatagram socket to broadcast address failed because setsockopt SO_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 connecttime. If socket sis 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 foreign host using name (an address in the name space of the socket). When this call completes successfully, the socket is ready to send and receive data. If the addressparameter of the namestructure is all zeroes, WSAConnectwill 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 cases, this function returns the error WSAEWOULDBLOCK. However, 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 the selectfunction, success is reported in the writefds set and failure is reported in the exceptfds set. If the client uses WSAEventSelect, 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 WSAConnectis merely to establish a default destination address so that the socket can be used on subsequent connection-oriented send and receive operations ( send, WSASend, recv, and WSARecv). Any datagrams received from an address other than the destination address specified will be discarded. If the entire namestructure is all zeros (not just the addressparameter of the namestructure), then the socket will be disconnected. Then, the default remote address will be indeterminate, so send/ WSASendand recv/ WSARecvcalls will return the error code WSAENOTCONN. However, sendto/ WSASendToand recvfrom/ WSARecvFromcan still be used. The default destination can be changed by simply calling WSAConnectagain, even if the socket is already connected. Any datagrams queued for receipt are discarded if name is different from the previous WSAConnectcall.

For connectionless sockets, name can indicate any valid address, including a broadcast address. However, to connectto a broadcast address, a socket must have setsockopt (Windows Sockets)SO_BROADCAST enabled. Otherwise, WSAConnectwill 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 application is responsible for allocating any memory space pointed to directly or indirectly by any of the parameters it specifies.

The lpCallerDataparameter is a value parameter that contains any user data that is to be sent along with the connection request. If lpCallerDatais NULL, no user data will be passed to the peer. The lpCalleeDataparameter is a result parameter that will contain any user data passed back from the other socket as part of the connection establishment in a WSABUFstructure. The lpCalleeData->lenmember initially contains the length of the buffer allocated by the application and pointed to by lpCalleeData-> buf. The lpCalleeData->lenmember will 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, the connection operation completes when WSAConnectreturns. For nonblocking sockets, completion 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 to which the socket belongs.

Requirements

Header winsock2.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