connect (Windows Sockets)

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function establishes a connection to a specified socket.

Syntax

int connect(
  SOCKET s,
  const struct sockaddr FAR* name,
  int namelen
);

Parameters

• s
  [in] Descriptor identifying an unconnected socket.

• name
  [in] Name of the socket to which the connection should be established.

• namelen
  [in] Length of the name.

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 WSAGetLastError.

On a blocking socket, the return value indicates success or failure of the connection attempt.

With a nonblocking socket, the connection attempt cannot be completed immediately. In this case, this function will return SOCKET_ERROR and WSAGetLastError will return WSAEWOULDBLOCK. The following list shows the three scenarios that are possible in this case:

• Use the select function to determine the completion of the connection request by checking to see if the socket is writeable.
• If the application is using WSAEventSelect to indicate interest in connection events, then the associated event object will be signaled indicating that the connect operation is complete (successfully or not).

Until the connection attempt completes on a nonblocking socket, all subsequent calls to connect on the same socket will fail with the error code WSAEALREADY and with WSAEISCONN when the connection completes successfully. Due to ambiguities in the Winsock, error codes returned from connect while a connection is already pending may vary among implementations. As a result, it is not recommended that applications use multiple calls to connect to detect connection completion. If they do, they must be prepared to handle WSAEINVAL and WSAEWOULDBLOCK error codes the same way that they handle WSAEALREADY to ensure robust execution.

If the error code returned indicates the connection attempt failed (that is, WSAECONNREFUSED, WSAENETUNREACH, or WSAETIMEDOUT), the application can call connect again for the same socket.

Remarks

This function is used to create a connection to the specified destination. If 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 foreign host using name (an address in the name space of the socket; for a detailed description, see bind (Windows Sockets) and sockaddr.

When the socket call completes successfully, the socket is ready to send and receive data. If the address member of the structure specified by the name parameter is all zeroes, connect will 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 the error WSAEWOULDBLOCK; however, the operation proceeds.

When the success or failure outcome becomes known, the way in which it is reported depends on how the client registers for notification. The following list shows the way in which it can be reported:

• If the client uses the select function, success is reported in the writefds set and failure is reported in the exceptfds set.
• If the client uses the WSAEventSelect function, 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 connect is merely to establish a default destination address that can be used on subsequent send/WSASend and recv/WSARecv calls. Any datagrams received from an address other than the destination address specified will be discarded. If the address member of the structure specified by name is all zeroes, the socket will be disconnected. Then, the default remote address will be indeterminate, so send /WSASend and recv /WSARecv calls will return the error code WSAENOTCONN. However, sendto/WSASendTo and recvfrom/WSARecvFrom can still be used. The default destination can be changed by simply calling connect again, even if the socket is already connected. Any datagrams queued for receipt are discarded if name is different from the previous connect.

For connectionless sockets, name can indicate any valid address, including a broadcast address. However, to connect to a broadcast address, a socket must use setsockopt (Windows Sockets) to enable the SO_BROADCAST option. Otherwise, connect will fail with the error code WSAEACCES.

When a connection between sockets is broken, the sockets should be discarded and recreated. When a problem develops on a connected socket, the application must discard and recreate the needed sockets to return to a stable point.

Notes for IrDA Sockets

• The Af_irda.h header file must be explicitly included.
• If an existing IrDA connection is detected at the media-access level, WSAENETDOWN is returned.
• If active connections to a device with a different address exist, WSAEADDRINUSE is returned.
• If the socket is already connected or an exclusive/multiplexed mode change failed, WSAEISCONN is returned.
• If the socket was previously bound to a local service name to accept incoming connections using bind, WSAEINVAL is returned. Note that once a socket is bound, it cannot be used for establishing an outbound connection.

IrDA implements the connect function with addresses of the form sockaddr_irda. Typically, a client application will create a socket with the socket (Windows Sockets) function, scan the immediate vicinity for IrDA devices with the IRLMP_ENUMDEVICES socket option, choose a device from the returned list, form an address, and call connect. There is no difference between blocking and nonblocking semantics.

For more inforamtion about IrDA support in Windows Embedded CE, see Infrared Communications.

The following table shows a list of possible error codes.

Notes for Bluetooth Sockets

• The ws2bth.h header file must be explicitly included.
• If the port is set to 0 in the SOCKADDR_BTH address, then serviceClassId is used in the SDP query before the connection attempt is made to determine server channel identifier. Use getpeername on the connected socket to retrieve it.

Requirements

See Also

Reference

accept (Windows Sockets)
bind (Windows Sockets)
getsockname (Windows Sockets)
recv
recvfrom
select
send
sendto
setsockopt (Windows Sockets)
sockaddr
socket (Windows Sockets)
WSAConnect
WSAEventSelect
WSAGetLastError
WSARecv
WSARecvFrom
WSASend
WSASendTo
WSAStartup