NetSock_TxData

Copy bytes from an application memory buffer into a socket to send to a remote socket.

Files

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

Prototypes

NET_SOCK_RTN_CODE NetSock_TxData  (NET_SOCK_ID         sock_id,
                                   void               *p_data,
                                   CPU_INT16U          data_len,
                                   CPU_INT16S          flags,
                                   NET_ERR            *p_err);

NET_SOCK_RTN_CODE NetSock_TxDataTo(NET_SOCK_ID         sock_id,
                                   void               *p_data,
                                   CPU_INT16U          data_len,
                                   CPU_INT16S          flags,
                                   NET_SOCK_ADDR      *p_addr_remote,
                                   NET_SOCK_ADDR_LEN   addr_len,
                                   NET_ERR            *p_err);

ssize_t           send            (int                 sock_id,
                                   void               *p_data,
                                   _size_t             data_len,
                                   int                 flags);

ssize_t           sendto          (       int          sock_id,
                                          void        *p_data,
                                          _size_t      data_len,
                                          int          flags,
                                   struct sockaddr    *p_addr_remote,
                                          socklen_t    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
Pointer to the application data memory buffer to send.

data_len
Size of the application data memory buffer (in bytes).

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

NET_SOCK_FLAG_NONE/0
NET_SOCK_FLAG_TX_NO_BLOCK/

No socket flags selected

MSG_DONTWAIT

Send 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) which contains the remote socket address to send data to.

addr_len
Size of the socket address structure which must be passed the size of the socket address structure [e.g., sizeof(NET_SOCK_ADDR_IPv4)].

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_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_DATA_SIZE
NET_SOCK_ERR_INVALID_CONN
NET_SOCK_ERR_INVALID_ADDR
NET_SOCK_ERR_INVALID_ADDR_LEN
NET_SOCK_ERR_INVALID_PORT_NBR
NET_SOCK_ERR_ADDR_IN_USE
NET_SOCK_ERR_PORT_NBR_NONE_AVAIL
NET_SOCK_ERR_CONN_FAIL
NET_SOCK_ERR_FAULT
NET_ERR_TX
NET_IF_ERR_INVALID_IF
NET_IP_ERR_ADDR_NONE_AVAIL
NET_IP_ERR_ADDR_CFG_IN_PROGRESS
NET_CONN_ERR_NOT_USED
NET_CONN_ERR_INVALID_CONN
NET_CONN_ERR_INVALID_FAMILY
NET_CONN_ERR_INVALID_TYPE
NET_CONN_ERR_INVALID_PROTOCOL_IX
NET_CONN_ERR_INVALID_ADDR_LEN
NET_CONN_ERR_ADDR_IN_USE
NET_INIT_ERR_NOT_COMPLETED
NET_ERR_FAULT_LOCK_ACQUIRE

Returned Value

Positive number of bytes (queued to be) sent, if successful;

NET_SOCK_BSD_RTN_CODE_CONN_CLOSED/0, if the socket is closed;

NET_SOCK_BSD_ERR_TX/-1, otherwise.

Note that a positive return value does not mean that the message was successfully delivered to the remote socket, just that it was sent or queued for sending.

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_TxData()/send(), whereas UDP sockets typically use NetSock_TxDataTo()/sendto().

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 receive memory buffer is not large 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.

For datagram sockets (i.e., UDP), all data is sent atomically – i.e., each call to send data must be sent in a single, complete datagram. Since µC/TCP-IP does not currently support IP transmit fragmentation, if a datagram socket attempts to send data greater than a single datagram, then the socket send is aborted and no socket data is sent.

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