Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages

An asynchronous receive function, used to retrieve data from a TCP stream.

Before calling the recv function, a successful socket connection status must have been received through any of the two socket events SOCKET_MSG_CONNECT or SOCKET_MSG_ACCEPT, from the socket callback. Hence, indicating that the socket is already connected to a remote host. The application receives the required data in response to this asynchronous call through the reception of the event SOCKET_MSG_RECV in the socket callback.

Receiving the SOCKET_MSG_RECV message in the callback with zero or negative buffer length indicates the following: SOCK_ERR_NO_ERROR : Socket connection closed. The application should now call close(). SOCK_ERR_CONN_ABORTED : Socket connection aborted. The application should now call close(). SOCK_ERR_TIMEOUT : Socket receive timed out. The socket connection remains open. The application code is expected to close the socket through the call to the close function upon the appearance of the above mentioned errors.

Functions

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

NMI_API sint16 recv ( SOCKET  sock,
void *  pvRecvBuf,
uint16  u16BufLen,
uint32  u32Timeoutmsec 
)
An asynchronous receive function, used to retrieve data from a TCP stream.
Before calling the recv function, a successful socket connection status must have been received through any of the two socket events
[SOCKET_MSG_CONNECT] or [SOCKET_MSG_ACCEPT], from the socket callback. Hence, indicating that the socket is already connected to a remote
host.
The application receives the required data in response to this asynchronous call through the reception of the event @ref SOCKET_MSG_RECV in the
socket callback.

Receiving the SOCKET_MSG_RECV message in the callback with zero or negative buffer length indicates the following:
- @ref SOCK_ERR_NO_ERROR        : Socket connection closed. The application should now call @ref close().
- @ref SOCK_ERR_CONN_ABORTED    : Socket connection aborted. The application should now call @ref close().
- @ref SOCK_ERR_TIMEOUT         : Socket receive timed out. The socket connection remains open.
Parameters
[in]sockSocket 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]pvRecvBufPointer to a buffer that will hold the received data. The buffer is 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]u16BufLenThe buffer size in bytes.
[in]u32TimeoutmsecTimeout 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). If the timeout period is elapsed with no data received, the socket will get a timeout error.
Precondition
  • The socket function must be called to allocate a TCP socket before passing the socket ID to the recv function.
  • The socket in a connected state is expected to receive data through the socket interface.
See Also
socket
connect
bind
listen
recvfrom
close
Returns
The function returns ZERO for successful operations and a negative value otherwise. The possible error values are:

Example

The example demonstrates a code snippet for the calling of the recv function in the socket callback upon notification of the accept or connect events, and the parsing of the received data when the SOCKET_MSG_RECV event is received.

switch(u8Msg)
{
{
if(pstrAccept->sock >= 0)
{
recv(pstrAccept->sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT);
}
else
{
M2M_ERR("accept\n");
}
}
break;
{
if(pstrRx->s16BufferSize > 0)
{
recv(sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT);
}
else
{
printf("Socket recv Error: %d\n",pstrRx->s16BufferSize);
close(sock);
}
}
break;
default:
break;
}
Parameters
[in]sockSocket 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]pvRecvBufPointer to a buffer that will hold the received data. The buffer is 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]u16BufLenThe buffer size in bytes.
[in]u32TimeoutmsecTimeout 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). If the timeout period is elapsed with no data received, the socket will get a timeout error.
Precondition
  • The socket function must be called to allocate a TCP socket before passing the socket ID to the recv function.
  • The socket in a connected state is expected to receive data through the socket interface.
See Also
socket
connect
bind
listen
recvfrom
close
Returns
The function returns ZERO for successful operations and a negative value otherwise. The possible error values are:

Example

The example demonstrates a code snippet for the calling of the recv function in the socket callback upon notification of the accept or connect events, and the parsing of the received data when the SOCKET_MSG_RECV event is received.

switch(u8Msg)
{
{
if(pstrAccept->sock >= 0)
{
recv(pstrAccept->sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT);
}
else
{
M2M_ERR("accept\n");
}
}
break;
{
if(pstrRx->s16BufferSize > 0)
{
recv(sock,gau8RxBuffer,sizeof(gau8RxBuffer),TEST_RECV_TIMEOUT);
}
else
{
printf("Socket recv Error: %d\n",pstrRx->s16BufferSize);
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_RECV, SOCKET_CMD_SSL_RECV, SOCKET_REQUEST, SSL_FLAGS_ACTIVE, SSL_FLAGS_DELAY, tstrRecvCmd::u16BufLen, tstrSocket::u16SessionID, tstrRecvCmd::u16SessionID, tstrSocket::u16UserBufferSize, tstrRecvCmd::u32Timeoutmsec, and tstrSocket::u8SSLFlags.

Referenced by _http_client_recv_packet(), GROWL_APPSocketEventHandler(), handle_tcp_socket_cb(), handle_transaction(), iot_tls_read(), IperfSocketEventHandler(), prov_socket_cb(), smtpSendRecv(), socket_cb(), and WINC1500_read().