4.8.0.0R6
Software Development Kit
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules

Data Structures

struct  input_stream_from_open_tcp_socket
 Concrete struct for a tcp input stream. More...
 
struct  ltrx_tcp_listener
 Abstract structure containing data for TCP listener. More...
 
struct  output_stream_from_open_tcp_socket
 Concrete struct for a tcp output stream. More...
 

Macros

#define LTRX_TCP_LISTENER__ANY_INTERFACE   0xff
 

Functions

bool ltrx_input_stream_init_from_open_abstract_socket (struct input_stream_from_open_abstract_socket *inStream, struct ltrx_ip_socket *lis, const struct ltrx_network_protocol *lnp, struct ltrx_network_protocol_handle *lnph)
 Construct input stream from an open socket. More...
 
bool ltrx_input_stream_init_from_open_tcp_socket (struct input_stream_from_open_tcp_socket *inStream, struct ltrx_ip_socket *lis)
 Construct input stream from an open TCP socket. More...
 
bool ltrx_output_stream_init_to_open_tcp_socket (struct output_stream_from_open_tcp_socket *outStream, struct ltrx_ip_socket *lis)
 Set up an output stream to an open TCP socket. More...
 
struct ltrx_ip_socket * ltrx_tcp_accept (struct ltrx_tcp_listener *listener, struct ltrx_trigger *optReceiveEventTrigger)
 Accept a connection request. More...
 
struct ltrx_ip_socket * ltrx_tcp_connect (uint16_t optLocalPort, const char *remoteAddress, uint16_t remotePort, struct ltrx_trigger *optReceiveEventTrigger)
 Make connection. More...
 
bool ltrx_tcp_listen (const struct ltrx_tcp_listener *listener, uint32_t blockTimeMsec)
 Begin listening. More...
 
bool ltrx_tcp_listener_begin (struct ltrx_tcp_listener *listener, uint8_t zeroBasedInterface, uint16_t localPort, uint8_t backlog, struct ltrx_trigger *optListenerTrigger)
 Begin listening. More...
 
void ltrx_tcp_listener_end (struct ltrx_tcp_listener *listener)
 End listening. More...
 
bool ltrx_tcp_socket_close (struct ltrx_ip_socket *socket, uint32_t lingerMsec)
 Close socket. More...
 
bool ltrx_tcp_socket_is_closed (struct ltrx_ip_socket *socket)
 Is TCP socket closed? More...
 
bool ltrx_tcp_socket_is_eof (struct ltrx_ip_socket *socket)
 Is receive at end of file? More...
 
bool ltrx_tcp_socket_send (struct ltrx_ip_socket *sock, const void *data, size_t length, bool push)
 Send data. More...
 
enum ltrx_network_return ltrx_tcp_socket_send_nonblocking (struct ltrx_ip_socket *socket, const void *data, size_t length, bool push, struct ltrx_trigger *sendTrigger)
 Send data non-blocking. More...
 
void ltrx_tcp_socket_shutdown (struct ltrx_ip_socket *socket)
 Socket shutdown. More...
 

Detailed Description

The Transmission Control Protocol (TCP) layer provides connection management, congestion control, and reliable data stream delivery.

Macro Definition Documentation

#define LTRX_TCP_LISTENER__ANY_INTERFACE   0xff

Specifies to listen on all interfaces.

Function Documentation

bool ltrx_input_stream_init_from_open_abstract_socket ( struct input_stream_from_open_abstract_socket inStream,
struct ltrx_ip_socket *  lis,
const struct ltrx_network_protocol lnp,
struct ltrx_network_protocol_handle *  lnph 
)

Construct input stream from an open socket.

Return values
trueSuccess.
falseFailed.
Parameters
[out]inStreamThe concrete input stream from open socket struct.
[in]lisThe open socket that will feed the stream.
[in]lnpThe abstract network protocol.
[in]lnphThe abstract network protocol instance.
bool ltrx_input_stream_init_from_open_tcp_socket ( struct input_stream_from_open_tcp_socket inStream,
struct ltrx_ip_socket *  lis 
)

Construct input stream from an open TCP socket.

Return values
trueSuccess.
falseFailed.
Parameters
[out]inStreamThe concrete input stream from open tcp socket struct.
[in]lisThe open TCP socket that will feed the stream.
bool ltrx_output_stream_init_to_open_tcp_socket ( struct output_stream_from_open_tcp_socket outStream,
struct ltrx_ip_socket *  lis 
)

Set up an output stream to an open TCP socket.

Return values
trueSuccess.
falseFailed.
Parameters
[out]outStreamYour tcp output stream struct to initialize.
[in]lisThe open TCP socket that will be fed by the stream.
struct ltrx_ip_socket* ltrx_tcp_accept ( struct ltrx_tcp_listener listener,
struct ltrx_trigger *  optReceiveEventTrigger 
)

Accept a connection request.

Blocks till the accept either succeeds or fails.

Returns
Socket pointer.
Return values
NULLFailed.
Parameters
[in,out]listenerListener structure.
[in]optReceiveEventTriggerIf present, the specified trigger will subsequently be signaled when data is received. Otherwise, fill it in NULL.
struct ltrx_ip_socket* ltrx_tcp_connect ( uint16_t  optLocalPort,
const char *  remoteAddress,
uint16_t  remotePort,
struct ltrx_trigger *  optReceiveEventTrigger 
)

Make connection.

Warning: Blocks till successful or failed to connect.

Returns
IP socket.
Return values
NULLFailed.
Parameters
[in]optLocalPortProvides the local port to use. If 0, a random unused TCP port number will be assigned.
[in]remoteAddressThe remote address to connect to. May be a DNS name or an IP address.
[in]remotePortThe remote port to connect to.
[in]optReceiveEventTriggerIf present, this trigger will be signalled when receive data is available. Otherwise, fill in NULL.
bool ltrx_tcp_listen ( const struct ltrx_tcp_listener listener,
uint32_t  blockTimeMsec 
)

Begin listening.

The listener was earlier initialized by ltrx_tcp_listener_begin().

One-shot calls this till it returns true, then can either accept or end.

Backlog calls this till it returns true, then can accept or end, and after accept can either listen again or end.

Return values
trueA connection request has arrived.
falseNothing yet.
Parameters
[in]listenerListener structure.
blockTimeMsecTime to wait in milliseconds. For no wait (non-blocking), use 0. To wait forever, use TIME_WAIT_FOREVER.
bool ltrx_tcp_listener_begin ( struct ltrx_tcp_listener listener,
uint8_t  zeroBasedInterface,
uint16_t  localPort,
uint8_t  backlog,
struct ltrx_trigger *  optListenerTrigger 
)

Begin listening.

Initializes listener and starts listening.

Return values
trueSuccess, listener in use.
falseFailed, listener not used.
Parameters
[out]listenerListener structure to be initialized.
[in]zeroBasedInterfaceSpecifies interface(s) to listen to.
  • NETS_SOFTAP_START for listening only to ap0.
  • NETS_WLAN_START for listening only to wlan0.
  • LTRX_TCP_LISTENER__ANY_INTERFACE for listening to all of them. HINT: It can succeed when just one interface is up, then will not be listening to the other if it comes up later.
[in]localPortLocal port number to listen on.
[in]backlogHow many requests may be queued and not yet serviced before further requests are rejected. Use 0 for "one-shot" behavior, to listen only for the first connection.
[in]optListenerTriggerOptional trigger. If present, the trigger will be signaled when a connection request is received. Otherwise fill it in with NULL.
void ltrx_tcp_listener_end ( struct ltrx_tcp_listener listener)

End listening.

Stops listening, listener is no longer used.

Parameters
[in,out]listenerListener structure.
bool ltrx_tcp_socket_close ( struct ltrx_ip_socket *  socket,
uint32_t  lingerMsec 
)

Close socket.

Return values
trueAll data and FIN was ACKed okay.
falseFailed.
Parameters
[in,out]socketThe socket.
[in]lingerMsecIf 0, close without sending any buffered data. If non-zero, send data, FIN, wait for ACK, send ACKs till timed out.
bool ltrx_tcp_socket_is_closed ( struct ltrx_ip_socket *  socket)

Is TCP socket closed?

Return values
trueThe socket is closed.
falseThe socket is open.
Parameters
[in]socketThe socket.
bool ltrx_tcp_socket_is_eof ( struct ltrx_ip_socket *  socket)

Is receive at end of file?

Checks if all receive data has been read and a FIN has been received. This may be called after the TCP connection has been established.

Return values
trueNo more receive data will be available.
falseMore data might become available.
Parameters
[in]socketthe socket.
bool ltrx_tcp_socket_send ( struct ltrx_ip_socket *  sock,
const void *  data,
size_t  length,
bool  push 
)

Send data.

This is called after the TCP connection has been established.

Caution: This function may block until it either succeeds or fails.

Return values
trueSuccess.
falseFailed.
Parameters
[in,out]sockThe socket.
[in]dataData to send.
[in]lengthLength of data to send.
[in]pushIf true, forces TCP to forward data now, unless no data has been buffered.
enum ltrx_network_return ltrx_tcp_socket_send_nonblocking ( struct ltrx_ip_socket *  socket,
const void *  data,
size_t  length,
bool  push,
struct ltrx_trigger *  sendTrigger 
)

Send data non-blocking.

This is called after the TCP connection has been established.

The caller must retain the integrity of data if it sees a return code of LTRX_NETWORK_RETURN__WORKING. In this case the caller must periodically call again with length of 0 until it sees LTRX_NETWORK_RETURN__SUCCESS or LTRX_NETWORK_RETURN__FAILURE returned. The caller may use sendTrigger to expedite this periodic calling.

Note that with push of false, a return code of LTRX_NETWORK_RETURN__SUCCESS does NOT imply that the data has been transmitted, but merely buffered. To transmit the data, you will need to either call this with push of true, or call ltrx_tcp_socket_close() with sufficient lingerMsec to send the data.

Return values
LTRX_NETWORK_RETURN__WORKINGOperation in progress.
LTRX_NETWORK_RETURN__SUCCESSSuccess.
LTRX_NETWORK_RETURN__FAILUREFailed.
Parameters
[in,out]socketThe socket.
[in]dataData to send.
[in]lengthLength of data to send.
[in]pushIf true, force TCP to forward data now, unless no data has been buffered.
[in]sendTriggerThis trigger may be signaled when the operation is complete.
void ltrx_tcp_socket_shutdown ( struct ltrx_ip_socket *  socket)

Socket shutdown.

Application will call ltrx_tcp_socket_close() later, and expect it not to wait even though called with a timeout.

Parameters
[in,out]socketThe socket.