TCP/TLS Client/Server
Protocols

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] interface Interface to open connection
[in] host hostname or IPv4 address of remote server
[in] port Listening port of remote TCP server
[out] handle_ptr Stream handle of connection
Returns
result of api, see gos_result_t
Examples:
network/tcp_client/main.c , network/uart_tcp_client/main.c , test/throughput/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] config Connection configuration, see gos_tcp_config_t
[out] handle_ptr Stream handle of connection
Returns
result of api, see gos_result_t
Examples:
cloud/dps_demo/main.c .

◆ 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] handle Handle of stream to close
Returns
gos_result_t result of api call
Examples:
cloud/dps_demo/main.c , network/tcp_client/main.c , network/tcp_echo_server/main.c , network/uart_tcp_client/main.c , test/throughput/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] handle Client stream handle
[in] host_buffer Buffer to hold client host domain or IP address string
[in] host_buffer_len Length of host_buffer
[in] local_port_ptr Pointer to hold client's local port, leave NULL to ignore
[in] remote_port_ptr Pointer 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] interface Interface to start server
[in] port Listening 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 , network/tcp_multiclient/main.c , and test/throughput/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] handle Handle of stream to poll
[out] rx_bytes_available Pointer to hold number of bytes available to read
[out] tx_bytes_available Pointer 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] handle Stream handle returned by API call
[out] data Buffer to hold read data
[in] max_size Maximum amount of data to read
[out] bytes_read Pointer 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 , test/throughput/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
handle Stream handle
buffer Buffer 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] handle Client stream handle
[in] disconnect Client disconnect event handler
[in] receive Client 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] connect client connect event handler
[in] disconnect client disconnect event handler
[in] receive client data received event handler
Examples:
network/softap_tcp_server/main.c , network/tcp_echo_server/main.c , network/tcp_multiclient/main.c , and test/throughput/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
Examples:
test/throughput/main.c .

◆ 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] handle Stream handle returned by API call
[in] data Data to write to stream
[in] size Size of data in bytes to write
[in] auto_flush If 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 , test/throughput/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] interface Interface to open connection
[in] host hostname or IPv4 address of remote server
[in] port Listening port of TCP server
[out] handle_ptr Stream 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] interface Interface to start server
[in] port Listening 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