The Windows Sockets WSAConnect
function establishes a connection to a peer, exchanges connect data, and
specifies needed quality of service based on the supplied flow specification.
int WSAConnect (
| SOCKET s,
| const struct sockaddr FAR * name,
| int namelen,
| LPWSABUF lpCallerData,
| LPWSABUF lpCalleeData,
| LPQOS lpSQOS,
| LPQOS lpGQOS
[in] A descriptor identifying an unconnected socket.
[in] The name of the peer to which the socket is to be connected.
[in] The length of the name
[in] A pointer to the user data that is to be transferred to the peer during
[out] A pointer to the user data that is to be transferred back from the peer
during connection establishment.
[in] A pointer to the flow specifications for socket s
, one for each direction.
[in] A pointer to the flow specifications for the socket group (if applicable).
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 foreign host using name
(an address in the name space of the socket; for a detailed description,
please see bind
). When this call completes successfully, the socket is ready to send/receive
data. If the address field of the name
structure is all zeroes, WSAConnect
will return the error WSAEADDRNOTAVAIL. Any attempt to reconnect an active
connection will fail with the error code WSAEISCONN.
For a connectionless socket (for example, type SOCK_DGRAM), the operation
erformed by WSAConnect
is merely to establish a default destination address so that the socket may
be used on subsequent connection-oriented send and receive operations (send, WSASend, recv, WSARecv)
. Any datagrams received from an address other than the destination address
specified will be discarded. If the address field of the name
structure is all zeroes, the socket will be "dis-connected." Then, the
default remote address will be indeterminate, so send/WSASend
calls will return the error code WSAENOTCONN. However, sendto/WSASendTo
can still be used. The default destination may be changed by simply calling WSAConnect
again, even if the socket is already "connected". Any datagrams queued for
receipt are discarded if name
is different from the previous WSAConnect
For connectionless sockets, name
may indicate any valid address, including a broadcast address. However, to
connect to a broadcast address, a socket must have setsockopt
SO_BROADCAST enabled. Otherwise, WSAConnect
will 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.
is a value parameter which contains any user data that is to be sent along
with the connection request. If lpCallerData
is NULL, no user data will be passed to the peer. The lpCalleeData
is a result parameter which will contain any user data passed back from the
peer as part of the connection establishment. lpCalleeData->len
initially contains the length of the buffer allocated by the application and
pointed to by lpCalleeData->buf
will be set to zero if no user data has been passed back. The lpCalleeData
information will be valid when the connection operation is complete. For
blocking sockets, this will be when the WSAConnect
function returns. For nonblocking sockets, this will be after the FD_CONNECT
notification has occurred. If lpCalleeData
is 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.
At connect time, an application may use the lpSQOS
parameters to override any previous QOS specification made for the socket
with either the SIO_SET_QOS or SIO_SET_GROUP_QOS opcodes.
specifies the flow specifications for socket s
, one for each direction, followed by any additional provider-specific
parameters. If either the associated transport provider in general or the specific
type of socket in particular cannot honor the QOS request, an error will be
returned as indicated below. The sending or receiving flow specification values will
be ignored, respectively, for any unidirectional sockets. If no
provider-specific parameters are supplied, the buf
fields of lpSQOS->ProviderSpecific
should be set to NULL and zero, respectively. A NULL value for lpSQOS
indicates no application supplied QOS.
specifies the flow specifications for the socket group (if applicable), one
for each direction, followed by any additional provider-specific parameters. If
no provider-specific parameters are supplied, the buf
fields of lpSQOS->ProviderSpecific
should be set to NULL and zero, respectively. A NULL value for lpGQOS
indicates no application-supplied group QOS. This parameter will be ignored
is not the creator of the socket group.
When connected sockets break (that is, become closed for whatever reason),
they should be discarded and recreated. It is safest to assume that when things go
awry for any reason on a connected socket, the application must discard and
recreate the needed sockets in order to return to a stable point.
If no error occurs, WSAConnect
returns zero. Otherwise, it returns SOCKET_ERROR, and a specific error code
may be retrieved by calling WSAGetLastError
. On a blocking socket, the return value indicates success or failure of the
With a nonblocking socket, the connection attempt may not be completed
immediately. In this case, WSAConnect
will return SOCKET_ERROR, and WSAGetLastError
will return WSAEWOULDBLOCK. In this case, the application may:
- Use select to determine the completion of the connection request by checking if the
socket is writeable, or
- If your application is using WSAAsyncSelect to indicate interest in connection events, then your application will receive
an FD_CONNECT notification when the connect operation is complete, or
- If your application is using WSAEventSelect to indicate interest in connection events, then the associated event object
will be signaled when the connect operation is complete.
For a nonblocking socket, until the connection attempt completes all
subsequent calls to WSAConnect
on the same socket will fail with the error code WSAEALREADY.
If the return error code indicates the connection attempt failed (that is,
WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the application may call WSAConnect
again for the same socket.
||A successful WSAStartup must occur before using this function.
||The network subsystem has failed.
||The specified address is already in use.
||The (blocking) call was canceled through WSACancelBlockingCall.
||A blocking Windows Sockets 1.1 call is in progress, or the service provider is
still processing a callback function.
||A nonblocking connect/WSAConnect call is in progress on the specified socket.
||The specified address is not available from the local machine.
||Addresses in the specified family cannot be used with this socket.
||The attempt to connect was rejected.
||The name or the namelen argument is not a valid part of the user address space, the namelen argument is too small, the buffer length for lpCalleeData, lpSQOS, and lpGQOS are too small, or the buffer length for lpCallerData is too large.
||The parameter s is a listening socket, or the destination address specified is not consistent
with that of the constrained group the socket belongs to.
||The socket is already connected (connection-oriented sockets only).
||The network cannot be reached from this host at this time.
||No buffer space is available. The socket cannot be connected.
||The descriptor is not a socket.
||The flow specifications specified in lpSQOS and lpGQOS cannot be satisfied.
||The lpCallerData augment is not supported by the service provider.
||Attempt to connect timed out without establishing a connection.
||The socket is marked as nonblocking and the connection cannot be completed
immediately. It is possible to select the socket while it is connecting by selecting it for writing.
||Attempt to connect datagram socket to broadcast address failed because setsockopt SO_BROADCAST is not enabled.
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages