listen

After successful socket binding to an IP address and port on the system, start listening on a passive socket for incoming connections.

The socket must be bound on a local port or the listen operation fails. Upon the call to the asynchronous listen function, response is received through the event SOCKET_MSG_LISTEN in the socket callback. A successful listen means the TCP server operation is active. If a connection is accepted, then the application socket callback function is notified with the new connected socket through the event SOCKET_MSG_ACCEPT. Hence there is no need to call the accept function after calling listen.

After a connection is accepted, the user is then required to call recv to receive any packets transmitted by the remote host or to receive notification of socket connection termination.

Functions
NMI_API sint8	listen (SOCKET sock, uint8 backlog)

NMI_API sint8 listen	(	SOCKET	sock,
		uint8	backlog
	)

After successfully binding a socket to an IP address and port on the system, start listening passively for incoming connections.
   The socket must be bound on a local port or the listen operation fails.
   Upon the call to the asynchronous listen function, response is received through the event @ref SOCKET_MSG_LISTEN
in the socket callback.

A successful listen means the TCP server operation is active. If a connection is accepted, then the application socket callback function is
notified with the new connected socket through the event @ref SOCKET_MSG_ACCEPT. Hence there is no need to call the @ref accept function
after calling @ref listen.

After a connection is accepted, the user is then required to call @ref recv to receive any packets transmitted by the remote host or to receive 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]	backlog	Not used by the current implementation.

Precondition

The bind function must be called to assign the port number and IP address to the socket before the listen operation.

See Also

bind

accept

recv

recvfrom

send

sendto

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 invalid arguments were passed, such as negative socket ID.
• SOCK_ERR_INVALID Indicate socket listen failure.

Example

This example demonstrates the call of the listen socket operation after a successful socket operation.

static void TCP_Socketcallback(SOCKET sock, uint8 u8Msg, void * pvMsg)
{
    int ret =-1;

    switch(u8Msg)
    {
    case SOCKET_MSG_BIND:
        {
            tstrSocketBindMsg   *pstrBind = (tstrSocketBindMsg*)pvMsg;
            if(pstrBind != NULL)
            {
                if(pstrBind->status == 0)
                {
                    ret = listen(sock, 0);

                    if(ret <0)
                        printf("Listen failure! Error = %d\n",ret);
                }
                else
                {
                    M2M_ERR("bind Failure!\n");
                    close(sock);
                }
            }
        }
        break;

    case SOCKET_MSG_LISTEN:
        {

            tstrSocketListenMsg *pstrListen = (tstrSocketListenMsg*)pvMsg;
            if(pstrListen != NULL)
            {
                if(pstrListen->status == 0)
                {
                    ret = accept(sock,NULL,0);
                }
                else
                {
                    M2M_ERR("listen Failure!\n");
                    close(sock);
                }
            }
        }
        break;

    case SOCKET_MSG_ACCEPT:
        {
            tstrSocketAcceptMsg *pstrAccept = (tstrSocketAcceptMsg*)pvMsg;

            if(pstrAccept->sock >= 0)
            {
                TcpNotificationSocket = pstrAccept->sock;
                recv(pstrAccept->sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT);
            }
            else
            {
                M2M_ERR("accept failure\n");
            }
        }
        break;

    default:
        break;
    }
}

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]	backlog	Not used by the current implementation.

Precondition

The bind function must be called to assign the port number and IP address to the socket before the listen operation.

See Also

bind

accept

recv

recvfrom

send

sendto

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.
• SOCK_ERR_INVALID Indicate socket listen failure.

Example

This example demonstrates the call of the listen socket operation after a successful socket operation.

static void TCP_Socketcallback(SOCKET sock, uint8 u8Msg, void * pvMsg)
{   
    int ret =-1;
    
    switch(u8Msg)
    {   
    case SOCKET_MSG_BIND:
        {
            tstrSocketBindMsg   *pstrBind = (tstrSocketBindMsg*)pvMsg;
            if(pstrBind != NULL)
            {
                if(pstrBind->status == 0)
                {
                    ret = listen(sock, 0);
                    
                    if(ret <0)
                        printf("Listen failure! Error = %d\n",ret);
                }
                else
                {
                    M2M_ERR("bind Failure!\n");
                    close(sock);
                }
            }
        }
        break;

    case SOCKET_MSG_LISTEN:
        {

            tstrSocketListenMsg *pstrListen = (tstrSocketListenMsg*)pvMsg;
            if(pstrListen != NULL)
            {
                if(pstrListen->status == 0)
                {
                    ret = accept(sock,NULL,0);
                }
                else
                {
                    M2M_ERR("listen Failure!\n");
                    close(sock);
                }
            }
        }
        break;

    case SOCKET_MSG_ACCEPT:
        {
            tstrSocketAcceptMsg *pstrAccept = (tstrSocketAcceptMsg*)pvMsg;
            
            if(pstrAccept->sock >= 0)
            {
                TcpNotificationSocket = pstrAccept->sock;
                recv(pstrAccept->sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT);
            }
            else
            {
                M2M_ERR("accept failure\n");
            }
        }
        break;
    
    default:
        break;
    }
}

References MAX_SOCKET, NULL, tstrListenCmd::sock, SOCK_ERR_INVALID, SOCK_ERR_INVALID_ARG, SOCK_ERR_NO_ERROR, SOCKET_CMD_LISTEN, SOCKET_REQUEST, tstrSocket::u16SessionID, tstrListenCmd::u16SessionID, and tstrListenCmd::u8BackLog.

Referenced by IperfTCP_ServerStart(), and prov_socket_cb().