Synopsis

CTL_STATUS_t ctl_tcp_send(CTL_SOCKET_t s,
                          const void *buf,
                          size_t len,
                          CTL_TIMEOUT_t type,
                          CTL_TIME_t timeout,
                          unsigned flags);

Description

ctl_tcp_send sends len bytes from buf to socket s. Socket s must first be in the connected state, CTL_TCP_SOCKET_STATE_CONNECTED, or ctl_tcp_send fails.

Setting the timeout value ms to zero indicates a non-blocking call. In this case, as much data as possible will be passed to the MAC before returning. In a blocking call, multiple passes across the task synchronization between the network task and the calling task may be required before the entire len is sent.

Parameter flags may be zero or a bitwise combination of the following:

CTL_TCP_SEND_PUSH

Indicates the end of the current query or response to the remote TCP. In other words, this is the final call to ctl_tcp_send in a message.

CTL_TCP_SEND_URGENT

Send out-of-band data.

CTL_TCP_SEND_NOCOPY

Perform a zero-copy send of static data. This flag indicates that buf meets the target CPU's requirement for network DMA memory (if any) and that buf will remain in scope indefinitely. Buffer pointer buf will be passed through the stack directly to the MAC layer instead of copying its data to network memory first.

CTL_TCP_SEND_FREE

Perform a zero-copy send of dynamic data. This flag indicates that buf has been allocated by application code using ctl_net_mem_alloc_data and that the network library is to use ctl_net_mem_free to free it after the remote TCP acknowledges receipt.

Notes

Using the network library, the application layer has complete control over packet send coalescing. If the CTL_TCP_SEND_PUSH flag is not set, then an outgoing packet is only sent when a complete TCP segment has been built up. The CTL_TCP_SEND_PUSH flag will cause the buf and any previous queued send data to be sent to the remote TCP.

If flags is CTL_TCP_SEND_PUSH, buf may be null or len may be zero; in that case all previous queued data is sent on its way to the remote TCP.

Return Value

ctl_tcp_send returns the count of bytes actually sent for success or a negative value for fail. A non-blocking call (timeout is zero) that sent at least one byte but less than len bytes is considered successful.

ctl_tcp_send should not be invoked from the network task with a non-zero timeout value. In other words, do not use the blocking version of this function in a TCP server callback.

See Also

ctl_net_mem_alloc_data, ctl_net_mem_free, ctl_tcp_get_socket_state, ctl_tcp_get_socket_error