TCP/TLS Client/Server

TCP/TLS client/server functions. More...

Modules

Types
TCP client/server types.
 

Functions

gos_result_t gos_tcp_connect (gos_interface_t interface, const char *host, uint16_t port, gos_handle_t *handle_ptr)
 Connect to remote TCP server. More...
 
gos_result_t gos_tls_connect (gos_interface_t interface, const char *host, uint16_t port, gos_handle_t *handle_ptr)
 Connect to remote TCP server with TLS security. More...
 
gos_result_t gos_tcp_connect_with_config (const gos_tcp_config_t *config, gos_handle_t *handle_ptr)
 Connect to remote TCP/TLS server with configuration. More...
 
gos_result_t gos_tcp_listen (gos_interface_t interface, uint16_t port)
 Start TCP server. More...
 
gos_result_t gos_tcp_stop_listening (void)
 Stop TCP server. More...
 
gos_result_t gos_tls_listen (gos_interface_t interface, uint16_t port)
 Start TCP server with TLS security. More...
 
gos_result_t gos_tls_stop_listening (void)
 Stop TLS server. More...
 
gos_result_t gos_tcp_disconnect (gos_handle_t handle)
 Close TCP/TLS stream. More...
 
gos_result_t gos_tcp_read (gos_handle_t handle, void *data, uint32_t max_size, uint32_t *bytes_read)
 Read TCP/TLS stream data. More...
 
gos_result_t gos_tcp_read_with_buffer (gos_handle_t handle, gos_buffer_t *buffer)
 Read TCP stream data into buffer. More...
 
gos_result_t gos_tcp_write (gos_handle_t handle, const void *data, uint32_t size, bool auto_flush)
 Write TCP/TLS stream data. More...
 
gos_result_t gos_tcp_poll (gos_handle_t handle, uint32_t *rx_bytes_available, uint32_t *tx_bytes_available)
 Poll TCP/TLS stream for RX data. More...
 
gos_result_t gos_tcp_register_client_event_handlers (gos_handle_t handle, gos_stream_event_handler_t disconnect, gos_stream_event_handler_t receive)
 Register TCP/TLS client event handlers. More...
 
void gos_tcp_register_server_event_handlers (gos_stream_event_handler_t connect, gos_stream_event_handler_t disconnect, gos_stream_event_handler_t receive)
 Register TCP/TLS server event handlers. More...
 
gos_result_t gos_tcp_trigger_server_event_handlers (void)
 Trigger any pending TCP server event handlers. More...
 
gos_result_t gos_tcp_get_client_info (gos_handle_t handle, char *host_buffer, uint32_t host_buffer_len, uint16_t *local_port_ptr, uint16_t *remote_port_ptr)
 Get TCP/TLS client info. More...
 

Detailed Description

TCP/TLS client/server functions.

Function Documentation

◆ gos_tcp_connect()

gos_result_t gos_tcp_connect ( gos_interface_t  interface,
const char *  host,
uint16_t  port,
gos_handle_t handle_ptr 
)

Connect to remote TCP server.

See Gecko OS Command API documentation: tcp_client.

Parameters
[in]interfaceInterface to open connection
[in]hosthostname or IPv4 address of remote server
[in]portListening port of remote TCP server
[out]handle_ptrStream handle of connection
Returns
result of api, see gos_result_t
Examples:
network/tcp_client/main.c, network/uart_tcp_client/main.c, and utility/msgpack/read_write_stream.c.

◆ gos_tcp_connect_with_config()

gos_result_t gos_tcp_connect_with_config ( const gos_tcp_config_t config,
gos_handle_t handle_ptr 
)

Connect to remote TCP/TLS server with configuration.

See Gecko OS Command API documentation: tcp_client.

See gos_tcp_register_client_event_handlers() for registering event handlers.

Parameters
[in]configConnection configuration, see gos_tcp_config_t
[out]handle_ptrStream handle of connection
Returns
result of api, see gos_result_t

◆ gos_tcp_disconnect()

gos_result_t gos_tcp_disconnect ( gos_handle_t  handle)

Close TCP/TLS stream.

See Gecko OS Command API documentation: stream_close.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in]handleHandle of stream to close
Returns
gos_result_t result of api call
Examples:
network/tcp_client/main.c, network/tcp_echo_server/main.c, network/uart_tcp_client/main.c, and utility/msgpack/read_write_stream.c.

◆ gos_tcp_get_client_info()

gos_result_t gos_tcp_get_client_info ( gos_handle_t  handle,
char *  host_buffer,
uint32_t  host_buffer_len,
uint16_t *  local_port_ptr,
uint16_t *  remote_port_ptr 
)

Get TCP/TLS client info.

See Gecko OS Command API documentation: stream_list.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in]handleClient stream handle
[in]host_bufferBuffer to hold client host domain or IP address string
[in]host_buffer_lenLength of host_buffer
[in]local_port_ptrPointer to hold client's local port, leave NULL to ignore
[in]remote_port_ptrPointer to hold client's remote port, leave NULL to ignore
Returns
gos_result_t result of api call
Examples:
network/softap_tcp_server/main.c.

◆ gos_tcp_listen()

gos_result_t gos_tcp_listen ( gos_interface_t  interface,
uint16_t  port 
)

Start TCP server.

See Gecko OS Command API documentation: tcp_server start.

See gos_tcp_register_server_event_handlers() for registering client event handlers.

Parameters
[in]interfaceInterface to start server
[in]portListening port of TCP server
Returns
result of api, see gos_result_t
Examples:
network/softap_tcp_server/main.c, network/tcp_echo_server/main.c, and network/tcp_multiclient/main.c.

◆ gos_tcp_poll()

gos_result_t gos_tcp_poll ( gos_handle_t  handle,
uint32_t *  rx_bytes_available,
uint32_t *  tx_bytes_available 
)

Poll TCP/TLS stream for RX data.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in]handleHandle of stream to poll
[out]rx_bytes_availablePointer to hold number of bytes available to read
[out]tx_bytes_availablePointer to hold available TX buffer space
Returns
gos_result_t result of api call
Examples:
network/softap_tcp_server/main.c, network/tcp_client/main.c, network/tcp_echo_server/main.c, and network/uart_tcp_client/main.c.

◆ gos_tcp_read()

gos_result_t gos_tcp_read ( gos_handle_t  handle,
void *  data,
uint32_t  max_size,
uint32_t *  bytes_read 
)

Read TCP/TLS stream data.

See Gecko OS Command API documentation: stream_read.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in]handleStream handle returned by API call
[out]dataBuffer to hold read data
[in]max_sizeMaximum amount of data to read
[out]bytes_readPointer to hold actual amount of data read (set NULL if not used)
Returns
gos_result_t result of api call
Examples:
network/tcp_echo_server/main.c, and utility/msgpack/read_write_stream.c.

◆ gos_tcp_read_with_buffer()

gos_result_t gos_tcp_read_with_buffer ( gos_handle_t  handle,
gos_buffer_t buffer 
)

Read TCP stream data into buffer.

See gos_read_with_buffer() for more information.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
handleStream handle
bufferBuffer to specify how much data to read, then return how much data was read with pointer to data
Returns
gos_result_t result of api call
Examples:
network/softap_tcp_server/main.c, network/tcp_client/main.c, network/tcp_multiclient/main.c, and network/uart_tcp_client/main.c.

◆ gos_tcp_register_client_event_handlers()

gos_result_t gos_tcp_register_client_event_handlers ( gos_handle_t  handle,
gos_stream_event_handler_t  disconnect,
gos_stream_event_handler_t  receive 
)

Register TCP/TLS client event handlers.

The client connection should have been previously opened with:

Note
The event handlers execute in the app thread context
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in]handleClient stream handle
[in]disconnectClient disconnect event handler
[in]receiveClient receive data event handler
Returns
gos_result_t result of api call
Examples:
network/tcp_client/main.c, and network/uart_tcp_client/main.c.

◆ gos_tcp_register_server_event_handlers()

void gos_tcp_register_server_event_handlers ( gos_stream_event_handler_t  connect,
gos_stream_event_handler_t  disconnect,
gos_stream_event_handler_t  receive 
)

Register TCP/TLS server event handlers.

Register event handlers for TCP server client events. The TCP server must first be started with:

Note
The event handlers execute in the app thread context
Parameters
[in]connectclient connect event handler
[in]disconnectclient disconnect event handler
[in]receiveclient data received event handler
Examples:
network/softap_tcp_server/main.c, network/tcp_echo_server/main.c, and network/tcp_multiclient/main.c.

◆ gos_tcp_stop_listening()

gos_result_t gos_tcp_stop_listening ( void  )

Stop TCP server.

See Gecko OS Command API documentation: tcp_server stop.

Returns
result of api, see gos_result_t

◆ gos_tcp_trigger_server_event_handlers()

gos_result_t gos_tcp_trigger_server_event_handlers ( void  )

Trigger any pending TCP server event handlers.

Returns
gos_result_t result of api call

◆ gos_tcp_write()

gos_result_t gos_tcp_write ( gos_handle_t  handle,
const void *  data,
uint32_t  size,
bool  auto_flush 
)

Write TCP/TLS stream data.

See Gecko OS Command API documentation: stream_write.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in]handleStream handle returned by API call
[in]dataData to write to stream
[in]sizeSize of data in bytes to write
[in]auto_flushIf true, only flush data when the internal buffer is full, false flush the data immediately
Returns
gos_result_t result of api call
Examples:
network/softap_tcp_server/main.c, network/tcp_client/main.c, network/tcp_echo_server/main.c, network/tcp_multiclient/main.c, network/uart_tcp_client/main.c, and utility/msgpack/read_write_stream.c.

◆ gos_tls_connect()

gos_result_t gos_tls_connect ( gos_interface_t  interface,
const char *  host,
uint16_t  port,
gos_handle_t handle_ptr 
)

Connect to remote TCP server with TLS security.

See Gecko OS Command API documentation: tls_client.

See gos_tcp_register_client_event_handlers() for registering event handlers.

Parameters
[in]interfaceInterface to open connection
[in]hosthostname or IPv4 address of remote server
[in]portListening port of TCP server
[out]handle_ptrStream handle of connection
Returns
result of api, see gos_result_t

◆ gos_tls_listen()

gos_result_t gos_tls_listen ( gos_interface_t  interface,
uint16_t  port 
)

Start TCP server with TLS security.

See Gecko OS Command API documentation: tls_server start.

See gos_tcp_register_server_event_handlers() for registering client event handlers.

Parameters
[in]interfaceInterface to start server
[in]portListening port of TLS server
Returns
result of api, see gos_result_t

◆ gos_tls_stop_listening()

gos_result_t gos_tls_stop_listening ( void  )

Stop TLS server.

See Gecko OS Command API documentation: tls_server stop.

Returns
result of api, see gos_result_t