This function establishes a connection to a peer.
At a Glance
| Header file: | Winsock.h |
| Windows CE versions: | 1.0 and later |
Syntax
int connect (SOCKET s, const struct sockaddr *name, int namelen);
Parameters
s
[in] Descriptor that identifies an unconnected socket.
name
[in] Name of the socket to connect to.
namelen
[in] Length of the name parameter.
Return Values
Zero indicates that no error occurred. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.
Windows CE does not support the WSAEINTR error value.
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, connect will return SOCKET_ERROR, and WSAGetLastError will return WSAEWOULDBLOCK. In this case, use the select function to determine the completion of the connection request by checking to see if the socket is writeable.
Until the connection attempt completes on a nonblocking socket, all subsequent calls to connect on the same socket will fail with the error value WSAEALREADY, and WSAEISCONN when the connection completes successfully. Due to ambiguities the Windows Sockets Specification 1.1, error values 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 values the same way that they handle WSAEALREADY, to assure robust execution.
If the error value returned indicates the connection attempt failed (that is, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the application can call connect again for the same socket.
Remarks
For Infrared Sockets (IrSock), this function has the following additional requirements and behaviors:
IrSock implements the connect function with addresses of the form sockaddr_irda. Typically, a client application will create a socket with the socket 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 in blocking and non-blocking semantics.
The connect function is used to create a connection to the specified destination. 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 foreign host using name (an address in the name space of the socket; for a detailed description, please see bind 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 re-connect an active connection will fail with the error value 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 and the client uses the select function, success is reported in the writefds set and failure is reported in the exceptfds set.
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 and recv calls. Any datagrams received from an address other than the destination address specified will be discarded. If the address member of the structure specifed by name is all zeroes, the socket will be disconnected. Then, the default remote address will be indeterminate, so send and recv calls will return the error value WSAENOTCONN. However, sendto and recvfrom 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 to enable the SO_BROADCAST option. Otherwise, connect will fail with the error value 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 in order to return to a stable point.
See Also