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
...
Code Block |
---|
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.
pdatap_data_buf
Pointer to the application memory buffer to receive data.
...
In most cases, this flag would be set to NET_SOCK_FLAG_NONE/0
.
paddrp_addr_remote
Pointer to a socket address structure (see section 8-2 “Socket Interface” Network Sockets Concepts) to return the remote host address that sent the received data.
paddrp_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.
pipp_ip_opts_buf
Pointer to buffer to receive possible IP options.
pipp_ip_opts_len
Pointer to variable that will receive the return size of any received IP options.
perr
p_err
Pointer to variable that will receive the return error code from this function:
NET_SOCK_ERR_NONE
NET_SOCKERR_ERRFAULT_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_NULL_PTR
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_INITNOT_INCOMPLETECOMPLETED
NET_OSERR_ERRFAULT_LOCK_ACQUIRE
Returned Value
Positive number of bytes received, if successful;
...
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_CFGNO_BLOCK_SEL
(see section D-15-3) to one of the following values:
NET_SOCK_BLOCK_SEL_DFLT
sets blocking mode to the default, or blocking, unless modified by run-time options.
NET_SOCK_BLOCK_SEL_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 section C-13-27function NetSock_CfgTimeoutRxQ_Set()].
NET_SOCK_BLOCK_SEL_NO_BLOCK
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
NetSock_RxData()/NetSock_RxDataFrom()
is available only if NET_CFG_TRANSPORT_LAYER_SEL
is configured for TCP (see section D-12-1) and/or NET_UDP_CFG_APP_API_SEL
is configured for sockets (see section D-13-1).
In addition, recv()/recvfrom()
is available only if NET_BSD_CFG_API_EN
is enabled (see section D-17-1)None.
Notes / Warnings
TCP sockets typically use NetSock_RxData()/recv()
, whereas UDP sockets typically use NetSock_RxDataFrom()/recvfrom()
.
...