recvfrom

Receives data from a UDP Socket.

The asynchronous recvfrom function is used to retrieve data from a UDP socket. The socket must already be bound to a local port before a call to the recvfrom function is made (i.e message SOCKET_MSG_BIND is received with successful status in the socket callback).

Upon calling the recvfrom function with a successful return code, the application is expected to receive a notification in the socket callback whenever a message is received through the SOCKET_MSG_RECVFROM event.

Receiving the SOCKET_MSG_RECVFROM message in the callback with zero, indicates that the socket is closed. Whereby a negative buffer length indicates one of the socket error codes such as socket timeout error SOCK_ERR_TIMEOUT

The recvfrom callback can also be used to show the IP address of the remote host that sent the frame by using the "strRemoteAddr" element in the tstrSocketRecvMsg structure. (refer to the code example)

Functions
NMI_API sint16	recvfrom (SOCKET sock, void *pvRecvBuf, uint16 u16BufLen, uint32 u32Timeoutmsec)

NMI_API sint16 recvfrom	(	SOCKET	sock,
		void *	pvRecvBuf,
		uint16	u16BufLen,
		uint32	u32Timeoutmsec
	)

Receives data from a UDP Socket.

The asynchronous recvfrom function is used to retrieve data from a UDP socket. The socket must already be bound to
a local port before a call to the recvfrom function is made (i.e message @ref SOCKET_MSG_BIND is received
with successful status in the socket callback).

Upon calling the recvfrom function with a successful return code, the application is expected to receive a notification
in the socket callback whenever a message is received through the @ref SOCKET_MSG_RECVFROM event.

Receiving the SOCKET_MSG_RECVFROM message in the callback with zero, indicates that the socket is closed.
Whereby a negative buffer length indicates one of the socket error codes such as socket timeout error @ref SOCK_ERR_TIMEOUT

The recvfrom callback can also be used to show the IP address of the remote host that sent the frame by
using the "strRemoteAddr" element in the @ref tstrSocketRecvMsg structure. (refer to the code example)

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]	pvRecvBuf	Pointer to a buffer that will hold the received data. The buffer shall be used in the recv callback to deliver the received data to the caller. The buffer must be resident in memory (heap or global buffer).
[in]	u16BufLen	The buffer size in bytes.
[in]	u32TimeoutSeconds	Timeout for the recv function in milli-seconds. If the value is set to ZERO, the timeout will be set to infinite (the recv function waits forever).

Precondition

• The socket function must be called to allocate a TCP socket before passing the socket ID to the recv function.
• The socket corresponding to the socket ID must be successfully bound to a local port through the call to a bind function.

See Also

socket bind 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 Receive buffer.
• SOCK_ERR_BUFFER_FULL Indicate socket receive failure.

Example

The example demonstrates a code snippet for the calling of the recvfrom function in the socket callback upon notification of a successful bind event, and the parsing of the received data when the SOCKET_MSG_RECVFROM event is received.

switch(u8Msg)
{

case SOCKET_MSG_BIND:
    {
        tstrSocketBindMsg   *pstrBind = (tstrSocketBindMsg*)pvMsg;

        if(pstrBind != NULL)
        {
            if(pstrBind->status == 0)
            {
                recvfrom(sock, gau8SocketTestBuffer, TEST_BUFFER_SIZE, 0);
            }
            else
            {
                M2M_ERR("bind\n");
            }
        }
    }
    break;


case SOCKET_MSG_RECVFROM:
    {
        tstrSocketRecvMsg   *pstrRx = (tstrSocketRecvMsg*)pvMsg;

        if(pstrRx->s16BufferSize > 0)
        {
            //get the remote host address and port number
            uint16 u16port = pstrRx->strRemoteAddr.sin_port;
            uint32 strRemoteHostAddr = pstrRx->strRemoteAddr.sin_addr.s_addr;

            printf("Received frame with size = %d.\tHost address=%x, Port number = %d\n\n",pstrRx->s16BufferSize,strRemoteHostAddr, u16port);

            ret = recvfrom(sock,gau8SocketTestBuffer,sizeof(gau8SocketTestBuffer),TEST_RECV_TIMEOUT);
        }
        else
        {
            printf("Socket recv Error: %d\n",pstrRx->s16BufferSize);
            ret = close(sock);
        }
    }
    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]	pvRecvBuf	Pointer to a buffer that will hold the received data. The buffer shall be used in the recv callback to deliver the received data to the caller. The buffer must be resident in memory (heap or global buffer).
[in]	u16BufLen	The buffer size in bytes.
[in]	u32TimeoutSeconds	Timeout for the recv function in milli-seconds. If the value is set to ZERO, the timeout will be set to infinite (the recv function waits forever).

Precondition

• The socket function must be called to allocate a UDP socket before passing the socket ID to the recvfrom function.
• The socket corresponding to the socket ID must be successfully bound to a local port through the call to a bind function.

See Also

socket bind 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 Receive buffer.
• SOCK_ERR_BUFFER_FULL Indicate socket receive failure.

Example

The example demonstrates a code snippet for the calling of the recvfrom function in the socket callback upon notification of a successful bind event, and the parsing of the received data when the SOCKET_MSG_RECVFROM event is received.

    switch(u8Msg)
    {   
    case SOCKET_MSG_BIND:
        {
            tstrSocketBindMsg   *pstrBind = (tstrSocketBindMsg*)pvMsg;

            if(pstrBind != NULL)
            {
                if(pstrBind->status == 0)
                {
                    recvfrom(sock, gau8SocketTestBuffer, TEST_BUFFER_SIZE, 0);
                }
                else
                {
                    M2M_ERR("bind\n");
                }
            }
        }
        break;

    case SOCKET_MSG_RECVFROM:
        {
            tstrSocketRecvMsg   *pstrRx = (tstrSocketRecvMsg*)pvMsg;
            
            if(pstrRx->s16BufferSize > 0)
            {
                //get the remote host address and port number
                uint16 u16port = pstrRx->strRemoteAddr.sin_port;
                uint32 strRemoteHostAddr = pstrRx->strRemoteAddr.sin_addr.s_addr;

                printf("Received frame with size = %d.\tHost address=%x, Port number = %d\n\n",pstrRx->s16BufferSize,strRemoteHostAddr, u16port);
                
                ret = recvfrom(sock,gau8SocketTestBuffer,sizeof(gau8SocketTestBuffer),TEST_RECV_TIMEOUT);           
            }
            else
            {
                printf("Socket recv Error: %d\n",pstrRx->s16BufferSize);
                ret = close(sock);
            }
        }
        break;
    
    default:
        break;
    }
}

References tstrSocket::bIsRecvPending, MAX_SOCKET, NM_BSP_B_L_32, NULL, tstrSocket::pu8UserBuffer, tstrRecvCmd::sock, SOCK_ERR_BUFFER_FULL, SOCK_ERR_INVALID_ARG, SOCK_ERR_NO_ERROR, SOCKET_CMD_RECVFROM, SOCKET_REQUEST, tstrRecvCmd::u16BufLen, tstrSocket::u16SessionID, tstrRecvCmd::u16SessionID, tstrSocket::u16UserBufferSize, and tstrRecvCmd::u32Timeoutmsec.

Referenced by demo_wifi_socket_handler(), handle_udp_serv_socket_cb(), IperfSocketEventHandler(), IperfUpdate(), m2m_wifi_socket_handler(), and socket_cb().