Socket (TCP / UDP client)

Generic outbound byte-stream / datagram transport for plugin protocols. More...

Macros
#define	HOST_SOCK_TCP   0
	Protocol selector for host_socket_open.
#define	HOST_SOCK_UDP   1

Functions
int	host_socket_open (uint8_t proto, const char *host, uint16_t port, uint32_t timeout_ms)
	Open an outbound connection to a single remote endpoint.
int	host_socket_write (int handle, const uint8_t *data, size_t len, uint32_t timeout_ms)
	Write bytes to the stream / send a datagram to the connected peer.
int	host_socket_read (int handle, uint8_t *out, size_t cap, uint32_t timeout_ms)
	Read bytes from the stream / receive a datagram from the connected peer.
int	host_socket_close (int handle)
	Close a socket handle.

Detailed Description

Generic outbound byte-stream / datagram transport for plugin protocols.

Opens a connection to a single remote endpoint, reads/writes bytes, and closes the handle. Both protocols are connected: UDP fixes the peer at open time, so write/read behave like the TCP path (no per-call address). Requires manifest capability "socket" and an active network connection. The host owns DNS resolution, timeouts, socket limits, and cleanup of leaked handles when a plugin unloads.

Macro Definition Documentation

HOST_SOCK_TCP

#define HOST_SOCK_TCP   0

Protocol selector for host_socket_open.

Definition at line 380 of file host_api.h.

Referenced by host_socket_open().

HOST_SOCK_UDP

#define HOST_SOCK_UDP   1

Definition at line 381 of file host_api.h.

Referenced by host_socket_open().

Function Documentation

host_socket_close()

int host_socket_close

(

int

handle

)

Close a socket handle.

Definition at line 196 of file host_api_socket.cpp.

References HOST_ERR_INVALID_ARG, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_socket_close().

host_socket_open()

int host_socket_open	(	uint8_t	proto,
		const char *	host,
		uint16_t	port,
		uint32_t	timeout_ms )

Open an outbound connection to a single remote endpoint.

Parameters

proto	HOST_SOCK_TCP or HOST_SOCK_UDP.
host	Hostname or numeric IP address.
port	Remote port.
timeout_ms	Connect timeout (TCP handshake; ignored for UDP).

Returns

Handle > 0 on success, negative HostError on failure.

Definition at line 113 of file host_api_socket.cpp.

References cdc::plugin_manager::SlotTable< T, N >::allocate(), HOST_ERR_GENERIC, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NO_MEMORY, HOST_ERR_NOT_FOUND, HOST_OK, HOST_SOCK_TCP, HOST_SOCK_UDP, LOG_W, plg_get_active_plugin(), and TAG.

Referenced by cdc::plugin_manager::w_host_socket_open().

host_socket_read()

int host_socket_read	(	int	handle,
		uint8_t *	out,
		size_t	cap,
		uint32_t	timeout_ms )

Read bytes from the stream / receive a datagram from the connected peer.

Returns

Number of bytes read, 0 on EOF (TCP), or negative HostError on failure.

Definition at line 179 of file host_api_socket.cpp.

References HOST_ERR_GENERIC, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, and HOST_ERR_TIMEOUT.

Referenced by cdc::plugin_manager::w_host_socket_read().

host_socket_write()

int host_socket_write	(	int	handle,
		const uint8_t *	data,
		size_t	len,
		uint32_t	timeout_ms )

Write bytes to the stream / send a datagram to the connected peer.

Returns

Number of bytes written, or negative HostError on failure.

Definition at line 162 of file host_api_socket.cpp.

References HOST_ERR_GENERIC, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, and HOST_ERR_TIMEOUT.

Referenced by cdc::plugin_manager::w_host_socket_write().