connect
Table of Contents >> Programmer's Reference
#include <trsocket.h> |
int connect | ( |
int socketDescriptor, | |
const struct sockaddr * addressPtr, | |
int addressLength | |
); |
Contents
Function Description
The parameter socketDescriptor is a socket. If it is of type SOCK_DGRAM, connect() specifies the peer with which the socket is to be associated; this address is the address to which datagrams are to be sent if a receiver is not explicitly designated; it is the only address from which datagrams are to be received. If the socket socketDescriptor is of type SOCK_STREAM, connect() attempts to make a connection to another socket (either local or remote). The other socket is specified by addressPtr. addressPtr is a pointer to the IP address and port number of the remote or local socket. If socketDescriptor is not bound, then it will be bound to an address selected by the underlying transport provider. Generally, stream sockets may successfully connect only once; datagram sockets may use connect() multiple times to change their association. Datagram sockets may dissolve the association by connecting to a null address. Note that a non-blocking connect() is allowed. In this case, if the connection has not been established, and not failed, connect() will return TM_SOCKET_ERROR, and tfGetSocketError() will return TM_EINPROGRESS error code indicating that the connection is pending. connect() should never be called more than once. Additional calls to connect() will fail with TM_EALREADY error code returned by tfGetSocketError().
Non-blocking connect() and select():
After issuing one non-blocking connect(), the user can call select() with the write mask set for that socket descriptor to check for connection completion. When select() returns with the write mask set for that socket, the user can call getsockopt() with the SO_ERROR option name. If the retrieved pending socket error is TM_ENOERROR, then the connection has been established, otherwise an error occurred on the connection as indicated by the retrieved pending socket error.
Non-blocking connect() and tfRegisterSocketCB():
Alternatively, the user could have issued a tfRegisterSocketCB() call with TM_CB_CONNECT_COMPLT | TM_CB_SOCKET_ERROR event flags prior to issuing a non-blocking connect() to get an asynchronous notification of the completion of the connect() call. If the TM_CB_SOCKET_ERROR flag is set when the call back function is called, the user can retrieve the pending socket error by calling getsockopt() with the SO_ERROR option name.
Non-blocking connect() and polling:
Alternatively, after the user issues a non-blocking connect() call that returns TM_SOCKET_ERROR, the user can poll for completion by calling tfGetSocketError() until it no longer returns TM_EINPROGRESS.
Warning: | If connect() fails, the socket is no longer usable and must be closed. connect() cannot be called again on the socket. |
Parameters
- socketDescriptor
- The socket descriptor to assign a name (port number) to.
- addressPtr
- The pointer to the structure containing the address to connect to for TCP or SCTP. For UDP, this is the default address to send packets to and the only address to receive from.
- addressLength
- The length of the address structure.
Returns
- TM_ENOERROR
- Success
- TM_SOCKET_ERROR
- Failure
Note: | TM_SOCKET_ERROR means that this socket call has failed and the errorCode has been set on the socket itself.
To retrieve the socket error the user must call tfGetSocketError(socketDescriptor). |
Possible socket errors
- TM_EADDRINUSE
- The socket address is already in use.
- TM_EADDRNOTAVAIL
- The specified address is not available on the remote/local machine.
- TM_EPFNOSUPPORT
- Addresses in the specified address family cannot be used with this socket.
- TM_EINPROGRESS
- The socket is non-blocking and the current connection attempt has not yet been completed.
- TM_EALREADY
- connect() has already been called on the socket. Only one connect() call is allowed on a socket.
- TM_EBADF
- The socket descriptor is invalid.
- TM_ECONNREFUSED
- The attempt to connect() was forcefully rejected. The calling program should close the socket descriptor and issue another socket() call to obtain a new descriptor before attempting another connect() call.
- TM_EPERM
- Cannot call connect() after listen().
- TM_EINVAL
- One of the parameters is invalid.
- TM_EHOSTUNREACH
- No route to the host we want to connect to. The calling program should close the socket descriptor and should issue another socket() call to obtain a new descriptor before attempting another connect() call.
- TM_ETIMEDOUT
- Connection establishment timed out without establishing a connection. The calling program should close the socket descriptor and issue another socket() call to obtain a new descriptor before attempting another connect() call.