File syn_port_socket.h¶

FileList > port > syn_port_socket.h

TCP socket port interface — implement these for your platform. More...

#include "../common/syn_defs.h"
#include <stddef.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_SockAddr

Public Types¶

Type	Name
typedef int	SYN_Socket

Public Functions¶

Type	Name
SYN_Socket	syn_port_sock_accept (SYN_Socket listener, uint32_t timeout_ms) Accept an incoming connection on a listener socket.
void	syn_port_sock_close (SYN_Socket sock) Close a socket and release resources.
SYN_Socket	syn_port_sock_connect (const SYN_SockAddr * addr) Connect to a remote host by IP address.
SYN_Socket	syn_port_sock_connect_host (const char * host, uint16_t port) Connect to a remote host by hostname.
SYN_Socket	syn_port_sock_listen (uint16_t port, int backlog) Create a listening TCP socket on the given port.
int	syn_port_sock_recv (SYN_Socket sock, void * buf, size_t max_len, uint32_t timeout_ms) Receive data from a connected socket.
int	syn_port_sock_send (SYN_Socket sock, const void * data, size_t len) Send data over a connected socket.
int	syn_port_sock_send_all (SYN_Socket sock, const void * data, size_t len) Send all data over a connected socket.
SYN_Status	syn_port_udp_join_multicast (SYN_Socket sock, const char * multicast_ip) Join a multicast group.
SYN_Socket	syn_port_udp_open (uint16_t port) Open a UDP socket bound to the given port.
int	syn_port_udp_recvfrom (SYN_Socket sock, void * buf, size_t max_len, SYN_SockAddr * from, uint32_t timeout_ms) Receive a UDP packet.
int	syn_port_udp_sendto (SYN_Socket sock, const void * data, size_t len, const SYN_SockAddr * to) Send a UDP packet to a destination address.

Macros¶

Type	Name
define	SYN_SOCKET_INVALID `(-1)` Sentinel value for an invalid/uninitialized socket.

Detailed Description¶

Minimal BSD-like socket abstraction for TCP client connections. Higher-level modules (HTTP client, MQTT, OTA) use this interface without knowing the underlying TCP/IP stack.

Implement these functions by wrapping your platform's socket API: * lwIP (raw or socket mode) * ESP-IDF (POSIX sockets via lwIP) * POSIX (Linux/macOS for development) * Vendor TCP/IP stack

** **

SYN_Socket sock = syn_port_sock_connect_host("example.com", 80);
if (sock < 0) { handle error }

syn_port_sock_send(sock, "GET / HTTP/1.1\r\n\r\n", 18);

uint8_t buf[256];
int n = syn_port_sock_recv(sock, buf, sizeof(buf), 5000);

syn_port_sock_close(sock);

Public Types Documentation¶

typedef SYN_Socket¶

typedef int SYN_Socket;

Socket handle. Negative values indicate error / invalid.

Public Functions Documentation¶

function syn_port_sock_accept¶

Accept an incoming connection on a listener socket.

SYN_Socket syn_port_sock_accept (
    SYN_Socket listener,
    uint32_t timeout_ms
)

Blocks until a connection arrives or the timeout expires.

Parameters:

listener Listener socket from syn_port_sock_listen().
timeout_ms Timeout in milliseconds (0 = block indefinitely).

Returns:

Connected socket handle, or SYN_SOCKET_INVALID on timeout/error.

function syn_port_sock_close¶

Close a socket and release resources.

void syn_port_sock_close (
    SYN_Socket sock
)

Parameters:

sock Socket handle to close.

function syn_port_sock_connect¶

Connect to a remote host by IP address.

SYN_Socket syn_port_sock_connect (
    const SYN_SockAddr * addr
)

Opens a TCP connection. Blocking.

Parameters:

addr Remote address (IPv4 + port).

Returns:

Socket handle on success, SYN_SOCKET_INVALID on failure.

function syn_port_sock_connect_host¶

Connect to a remote host by hostname.

SYN_Socket syn_port_sock_connect_host (
    const char * host,
    uint16_t port
)

Performs DNS resolution and opens a TCP connection. Blocking.

Parameters:

host Hostname or dotted-decimal IP string.
port Port number.

Returns:

Socket handle on success, SYN_SOCKET_INVALID on failure.

function syn_port_sock_listen¶

Create a listening TCP socket on the given port.

SYN_Socket syn_port_sock_listen (
    uint16_t port,
    int backlog
)

Binds to all interfaces and begins listening for connections.

Parameters:

port Port number to listen on.
backlog Maximum pending connections (typically 1–5).

Returns:

Listener socket handle, or SYN_SOCKET_INVALID on failure.

function syn_port_sock_recv¶

Receive data from a connected socket.

int syn_port_sock_recv (
    SYN_Socket sock,
    void * buf,
    size_t max_len,
    uint32_t timeout_ms
)

Returns available data up to max_len. Blocks up to timeout_ms.

Parameters:

sock Socket handle.
buf Receive buffer.
max_len Buffer capacity.
timeout_ms Timeout in milliseconds (0 = non-blocking).

Returns:

Number of bytes received, 0 if connection closed, -1 on error/timeout.

function syn_port_sock_send¶

Send data over a connected socket.

int syn_port_sock_send (
    SYN_Socket sock,
    const void * data,
    size_t len
)

May send fewer bytes than requested (partial send).

Parameters:

sock Socket handle.
data Data to send.
len Number of bytes to send.

Returns:

Number of bytes sent, or -1 on error.

function syn_port_sock_send_all¶

Send all data over a connected socket.

int syn_port_sock_send_all (
    SYN_Socket sock,
    const void * data,
    size_t len
)

Loops internally until all bytes are sent or an error occurs.

Parameters:

sock Socket handle.
data Data to send.
len Number of bytes to send.

Returns:

Number of bytes sent (== len on success), or -1 on error.

function syn_port_udp_join_multicast¶

Join a multicast group.

SYN_Status syn_port_udp_join_multicast (
    SYN_Socket sock,
    const char * multicast_ip
)

Parameters:

sock UDP socket handle.
multicast_ip Multicast IP string (e.g. "224.0.0.251").

Returns:

SYN_OK on success, SYN_ERROR on failure.

function syn_port_udp_open¶

Open a UDP socket bound to the given port.

SYN_Socket syn_port_udp_open (
    uint16_t port
)

Parameters:

port Local port to bind to, or 0 for ephemeral.

Returns:

Socket handle on success, SYN_SOCKET_INVALID on failure.

function syn_port_udp_recvfrom¶

Receive a UDP packet.

int syn_port_udp_recvfrom (
    SYN_Socket sock,
    void * buf,
    size_t max_len,
    SYN_SockAddr * from,
    uint32_t timeout_ms
)

Parameters:

sock Socket handle.
buf Receive buffer.
max_len Buffer capacity.
from [out] Source address.
timeout_ms Receive timeout in milliseconds. If 0, must return immediately (non-blocking poll). Cooperative tasks (protothreads) rely on this to avoid blocking the scheduler. Port implementations MUST NOT treat 0 as "block forever."

Returns:

Number of bytes received, 0 if no data available (non-blocking), or -1 on error.

function syn_port_udp_sendto¶

Send a UDP packet to a destination address.

int syn_port_udp_sendto (
    SYN_Socket sock,
    const void * data,
    size_t len,
    const SYN_SockAddr * to
)

Parameters:

sock Socket handle.
data Payload to send.
len Payload length.
to Destination address (IP + port).

Returns:

Number of bytes sent, or -1 on error.

Macro Definition Documentation¶

define SYN_SOCKET_INVALID¶

Sentinel value for an invalid/uninitialized socket.

#define SYN_SOCKET_INVALID `(-1)`

The documentation for this class was generated from the following file src/syntropic/port/syn_port_socket.h