NetSock_RxData / NetSock_RxDataFrom

Copy up to a specified number of bytes received from a remote socket into an application memory buffer.

Files

net_sock.h/net_sock.c net_bsd.h/net_bsd.c

Prototypes

NET_SOCK_RTN_CODE NetSock_RxData    (NET_SOCK_ID         sock_id,
                                     void               *p_data_buf,
                                     CPU_INT16U          data_buf_len,
                                     CPU_INT16S          flags,
                                     NET_ERR            *p_err);

NET_SOCK_RTN_CODE NetSock_RxDataFrom(NET_SOCK_ID         sock_id,
                                     void               *p_data_buf,
                                     CPU_INT16U          data_buf_len,
                                     CPU_INT16S          flags,
                                     NET_SOCK_ADDR      *p_addr_remote,
                                     NET_SOCK_ADDR_LEN  *p_addr_len,
                                     void               *p_ip_opts_buf,
                                     CPU_INT08U          ip_opts_buf_len,
                                     CPU_INT08U         *p_ip_opts_len,
                                     NET_ERR            *p_err);

ssize_t           recv              (int                 sock_id,
                                     void               *p_data_buf,
                                     _size_t             data_buf_len,
                                     int                 flags);

ssize_t           recvfrom          (       int          sock_id,
                                            void        *p_data_buf,
                                            _size_t      data_buf_len,
                                            int          flags,
                                     struct sockaddr    *p_addr_remote,
                                            socklen_t   *p_addr_len);

Arguments

sock_id

This is the socket ID returned by NetSock_Open()/socket() when the socket was created or by NetSock_Accept()/accept() when a connection was accepted.

p_data_buf

Pointer to the application memory buffer to receive data.

data_buf_len

Size of the destination application memory buffer (in bytes).

flags

Flag to select receive options; bit-field flags logically OR’d:

NET_SOCK_FLAG_NONE/0

No socket flags selected

NET_SOCK_FLAG_RX_DATA_PEEK/MSG_PEEK

Receive socket data without consuming it

NET_SOCK_FLAG_RX_NO_BLOCK/MSG_DONTWAIT

Receive socket data without blocking

In most cases, this flag would be set to NET_SOCK_FLAG_NONE/0.

p_addr_remote

Pointer to a socket address structure (see section Network Sockets Concepts) to return the remote host address that sent the received data.

p_addr_len

Pointer to the size of the socket address structure which must be passed the size of the socket address structure [e.g., sizeof(NET_SOCK_ADDR_IP)]. Returns size of the accepted connection’s socket address structure, if no errors; returns 0, otherwise.

p_ip_opts_buf

Pointer to buffer to receive possible IP options.

p_ip_opts_len

Pointer to variable that will receive the return size of any received IP options.

p_err

Pointer to variable that will receive the return error code from this function:

NET_SOCK_ERR_NONE NET_ERR_FAULT_NULL_PTR NET_SOCK_ERR_NULL_SIZE NET_SOCK_ERR_NOT_USED NET_SOCK_ERR_CLOSED NET_SOCK_ERR_INVALID_SOCK NET_SOCK_ERR_INVALID_FAMILY NET_SOCK_ERR_INVALID_PROTOCOL NET_SOCK_ERR_INVALID_TYPE NET_SOCK_ERR_INVALID_STATE NET_SOCK_ERR_INVALID_OP NET_SOCK_ERR_INVALID_FLAG NET_SOCK_ERR_INVALID_ADDR_LEN NET_SOCK_ERR_INVALID_DATA_SIZE NET_SOCK_ERR_CONN_FAIL NET_SOCK_ERR_FAULT NET_SOCK_ERR_RX_Q_EMPTY NET_SOCK_ERR_RX_Q_CLOSED NET_ERR_RX NET_CONN_ERR_NOT_USED NET_CONN_ERR_INVALID_CONN NET_CONN_ERR_INVALID_ADDR_LEN NET_CONN_ERR_ADDR_NOT_USED NET_INIT_ERR_NOT_COMPLETED NET_ERR_FAULT_LOCK_ACQUIRE

Returned Value

Positive number of bytes received, if successful;

NET_SOCK_BSD_RTN_CODE_CONN_CLOSED/0, if the socket is closed;

NET_SOCK_BSD_ERR_RX/-1, otherwise.

Blocking vs Non-Blocking

The default setting for µC/TCP-IP is blocking. However, this setting can be changed at compile time by setting the NET_SOCK_DFLT_NO_BLOCK_EN to DEF_ENABLED or DEF_DISABLED. (see net_cfg.h file).

DEF_DISABLED sets the blocking mode to blocking. This means that a socket receive function will wait forever, until at least one byte of data is available to return or the socket connection is closed, unless a timeout is specified by NetSock_CfgTimeoutRxQ_Set() [See function NetSock_CfgTimeoutRxQ_Set()].

DEF_ENABLED sets the blocking mode to non-blocking. This means that a socket receive function will not wait but immediately return either any available data, socket connection closed, or an error indicating no available data or other possible socket faults. Your application will have to “poll” the socket on a regular basis to receive data.

The current version of µC/TCP-IP selects blocking or non-blocking at compile time for all sockets. A future version may allow the selection of blocking or non-blocking at the individual socket level. However, each socket receive call can pass the NET_SOCK_FLAG_RX_NO_BLOCK/MSG_DONTWAIT flag to disable blocking on that call.

Required Configuration

None.

Notes / Warnings

TCP sockets typically use NetSock_RxData()/recv(), whereas UDP sockets typically use NetSock_RxDataFrom()/recvfrom().

For stream sockets (i.e., TCP), bytes are guaranteed to be received in the same order as they were transmitted, without omissions.

For datagram sockets (i.e., UDP), each receive returns the data from exactly one send but datagram order and delivery is not guaranteed. Also, if the application memory buffer is not big enough to receive an entire datagram, the datagram’s data is truncated to the size of the memory buffer and the remaining data is discarded.

Only some receive flag options are implemented. If other flag options are requested, an error is returned so that flag options are not silently ignored.