 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. |
This function establishes a connection to a peer.
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
nameparameter.
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 WSACancelBlockingCallfunction; however, Windows CE returns the WSAEINTR error value if closesocketis called in the middle of executing a sockets call.
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, connectwill return SOCKET_ERROR, and WSAGetLastErrorwill return WSAEWOULDBLOCK. In this case, use the selectfunction 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 connecton 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 connectwhile 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 connectagain for the same socket.
Remarks
For Infrared Sockets (IrSock), this function has the following additional requirements and behaviors:
- The Af_irda.h file must be explicitly included.
- If WSAENETDOWN is returned, an existing IrDA connection was detected at the media access level.
- If WSAEADDRINUSE is returned, active connections to a device with a different address exist.
- If WSAEINPROGRESS is returned, IAS name resolution failed because another IAS query is in progress. Retry the operation at one second intervals.
- If WSAEISCONN is returned, the socket is already connected or
an exclusive/multiplexed mode change failed.
IrSock implements the connectfunction 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 connectfunction 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 bindand 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 nameparameter is all zeroes, connectwill 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 selectfunction, 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 connectis merely to establish a default destination address that can be used on subsequent sendand recvcalls. Any datagrams received from an address other than the destination address specified will be discarded. If the address member of the structure specifed by nameis all zeroes, the socket will be disconnected. Then, the default remote address will be indeterminate, so sendand recvcalls will return the error value WSAENOTCONN. However, sendtoand recvfromcan still be used. The default destination can be changed by simply calling connectagain, even if the socket is already connected. Any datagrams queued for receipt are discarded if nameis different from the previous connect.
For connectionless sockets, namecan indicate any valid address, including a broadcast address. However, to connect to a broadcast address, a socket must use setsockoptto enable the SO_BROADCAST option. Otherwise, connectwill 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.
Requirements
Runs on Versions Defined in Include Link to Windows CE OS 1.0 and later Winsock.h Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
See Also
accept, bind, getsockname, recv, socket, select, send