connect

Jump to: navigation, search

Table of Contents >> Programmer's Reference


#include <trsocket.h>


int connect (
int socketDescriptor,
const struct sockaddr * addressPtr,
int addressLength
);


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


Table of Contents >> Programmer's Reference