connect

Establishes a TCP connection with a remote server.

The asynchronous connect function must be called after receiving a valid socket ID from the socket function. The application socket callback function is notified of the result of the connection attempt through the event SOCKET_MSG_CONNECT, along with a structure tstrSocketConnectMsg. If socket connection fails, the application should call close(). A successful connect means the TCP session is active. The application is then required to make a call to the recv to receive any packets transmitted by the remote server, unless the application is interrupted by a notification of socket connection termination.

Functions
NMI_API sint8	connect (SOCKET sock, struct sockaddr *pstrAddr, uint8 u8AddrLen)

NMI_API sint8 connect	(	SOCKET	sock,
		struct sockaddr *	pstrAddr,
		uint8	u8AddrLen
	)

Establishes a TCP connection with a remote server.
The asynchronous connect function must be called after receiving a valid socket ID from the @ref socket function.
The application socket callback function is notified of the result of the connection attempt through the event @ref SOCKET_MSG_CONNECT,
along with a structure @ref tstrSocketConnectMsg.
If socket connection fails, the application should call @ref close().
A successful connect means the TCP session is active. The application is then required to make a call to the @ref recv function
to receive any packets transmitted by the remote server, unless the application is interrupted by a notification of socket connection
termination.

Parameters

[in]	sock	Socket ID, must hold a non negative value. A negative value will return a socket error SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
[in]	pstrAddr	Address of the remote server.
[in]	u8AddrLen	Size of the given socket address structure in bytes. Not currently used, implemented for BSD compatibility only.

Precondition

The socket function must be called to allocate a TCP socket before passing the socket ID to the bind function. If the socket is not bound, you do NOT have to call bind before the "connect" function.

See Also

socket recv send close

Returns

The function returns ZERO for successful operations and a negative value otherwise. The possible error values are:

• SOCK_ERR_NO_ERROR Indicating that the operation was successful.
• SOCK_ERR_INVALID_ARG Indicating passing invalid arguments such as negative socket ID or NULL socket address structure.
• SOCK_ERR_INVALID Indicate socket connect failure.

Example

The example demonstrates a TCP application, showing how the asynchronous call to the connect function is made through the main function and how the callback function handles the SOCKET_MSG_CONNECT event.

Main Function

struct sockaddr_in  Serv_Addr;
SOCKET TcpClientSocket =-1;
int ret = -1

TcpClientSocket = socket(AF_INET,SOCK_STREAM,SOCKET_CONFIG_DEFAULT);
Serv_Addr.sin_family = AF_INET;
Serv_Addr.sin_port = _htons(1234);
Serv_Addr.sin_addr.s_addr = inet_addr(SERVER);
printf("Connected to server via socket %u\n",TcpClientSocket);

do
{
    ret = connect(TcpClientSocket,(sockaddr_in*)&Serv_Addr,sizeof(Serv_Addr));
    if(ret != 0)
    {
        printf("Connection Error\n");
    }
    else
    {
        printf("Connection successful.\n");
        break;
    }
}while(1)

Socket Callback

if(u8Msg == SOCKET_MSG_CONNECT)
{
    tstrSocketConnectMsg    *pstrConnect = (tstrSocketConnectMsg*)pvMsg;
    if(pstrConnect->s8Error == 0)
    {
        uint8   acBuffer[GROWL_MSG_SIZE];
        uint16  u16MsgSize;

        printf("Connect success!\n");

        u16MsgSize = FormatMsg(u8ClientID, acBuffer);
        send(sock, acBuffer, u16MsgSize, 0);
        recv(pstrNotification->Socket, (void*)au8Msg,GROWL_DESCRIPTION_MAX_LENGTH, GROWL_RX_TIMEOUT);
        u8Retry = GROWL_CONNECT_RETRY;
    }
    else
    {
        M2M_DBG("Connection Failed, Error: %d\n",pstrConnect->s8Error");
        close(pstrNotification->Socket);
    }
}

Parameters

[in]	sock	Socket ID, must hold a non negative value. A negative value will return a socket error SOCK_ERR_INVALID_ARG. Indicating that an invalid argument is passed in.
[in]	pstrAddr	Address of the remote server.
[in]	pstrAddr	Pointer to socket address structure sockaddr_in.
[in]	u8AddrLen	Size of the given socket address structure in bytes. Not currently used, implemented for BSD compatibility only.

Precondition

The socket function must be called to allocate a TCP socket before passing the socket ID to the bind function. If the socket is not bound, you do NOT have to call bind before the "connect" function.

See Also

socket recv send close

Returns

The function returns ZERO for successful operations and a negative value otherwise. The possible error values are:

• SOCK_ERR_NO_ERROR Indicating that the operation was successful.
• SOCK_ERR_INVALID_ARG Indicating passing invalid arguments such as negative socket ID or NULL socket address structure.
• SOCK_ERR_INVALID Indicate socket connect failure.

Example

The example demonstrates a TCP application, showing how the asynchronous call to the connect function is made through the main function and how the callback function handles the SOCKET_MSG_CONNECT event.

Main Function

struct sockaddr_in  Serv_Addr;
SOCKET TcpClientSocket =-1;
int ret = -1

TcpClientSocket = socket(AF_INET,SOCK_STREAM,0);
Serv_Addr.sin_family = AF_INET;
Serv_Addr.sin_port = _htons(1234);
Serv_Addr.sin_addr.s_addr = inet_addr(SERVER);
printf("Connected to server via socket %u\n",TcpClientSocket);

do
{
    ret = connect(TcpClientSocket,(sockaddr_in*)&Serv_Addr,sizeof(Serv_Addr));
    if(ret != 0)
    {
        printf("Connection Error\n");
    }
    else
    {
        printf("Connection successful.\n");
        break;
    }
}while(1)   

Socket Callback

if(u8Msg == SOCKET_MSG_CONNECT)
{
    tstrSocketConnectMsg    *pstrConnect = (tstrSocketConnectMsg*)pvMsg;
    if(pstrConnect->s8Error == 0)
    {
        uint8   acBuffer[GROWL_MSG_SIZE];
        uint16  u16MsgSize;

        printf("Connect success!\n");
        
        u16MsgSize = FormatMsg(u8ClientID, acBuffer);
        send(sock, acBuffer, u16MsgSize, 0);
        recv(pstrNotification->Socket, (void*)au8Msg,GROWL_DESCRIPTION_MAX_LENGTH, GROWL_RX_TIMEOUT);
        u8Retry = GROWL_CONNECT_RETRY;
    }
    else
    {
        M2M_DBG("Connection Failed, Error: %d\n",pstrConnect->s8Error");
        close(pstrNotification->Socket);
    }
}

References m2m_memcpy(), MAX_SOCKET, NULL, tstrConnectCmd::sock, SOCK_ERR_INVALID, SOCK_ERR_INVALID_ARG, SOCK_ERR_NO_ERROR, SOCKET_CMD_CONNECT, SOCKET_CMD_SSL_CONNECT, SOCKET_REQUEST, SSL_FLAGS_ACTIVE, tstrConnectCmd::strAddr, tstrSocket::u16SessionID, tstrConnectCmd::u16SessionID, tstrSocket::u8SSLFlags, and tstrConnectCmd::u8SslFlags.

Referenced by IperfTCP_ClientStart(), main(), and sslConnect().