A TCP netconn channel. More...

Inheritance diagram for idfxx::net::netconn::stream_channel:

Public Member Functions
	stream_channel ()
	Creates a TCP netconn with default address family (IPv4).

	stream_channel (address_family fam)
	Creates a TCP netconn for the given address family.

void	connect (const endpoint &peer)
	Connects to the given remote endpoint.

result< void >	try_connect (const endpoint &peer)
	Connects to the given remote endpoint.

void	close ()
	Closes the netconn.

result< void >	try_close ()
	Closes the netconn.

void	shutdown ()
	Shuts down both directions on the netconn.

result< void >	try_shutdown ()
	Shuts down both directions on the netconn.

void	shutdown (direction dir)
	Shuts down one direction on the netconn (half-close).

result< void >	try_shutdown (direction dir)
	Shuts down one direction on the netconn (half-close).

size_t	send (std::span< const std::byte > data, idfxx::flags< write_flag > flags={})
	Sends a buffer on the TCP netconn.

result< size_t >	try_send (std::span< const std::byte > data, idfxx::flags< write_flag > flags={})
	Sends a buffer on the TCP netconn.

size_t	send (std::string_view data, idfxx::flags< write_flag > flags={})
	Sends a string view on the TCP netconn.

result< size_t >	try_send (std::string_view data, idfxx::flags< write_flag > flags={})
	Sends a string view on the TCP netconn.

buffer	recv ()
	Receives the next buffer from the connection.

result< buffer >	try_recv ()
	Receives the next buffer from the connection.

std::span< std::byte >	recv (std::span< std::byte > buf)
	Receives data into a caller-provided buffer.

result< std::span< std::byte > >	try_recv (std::span< std::byte > buf)
	Receives data into a caller-provided buffer.

endpoint	peer_endpoint () const
	Returns the remote endpoint the channel is connected to.

result< endpoint >	try_peer_endpoint () const
	Returns the remote endpoint the channel is connected to.

Static Public Member Functions
static result< stream_channel >	make ()
	Creates a TCP netconn with default address family (IPv4).

static result< stream_channel >	make (address_family fam)
	Creates a TCP netconn for the given address family.

Friends
class	listener

Detailed Description

A TCP netconn channel.

Use idfxx::net::netconn::listener to accept inbound connections; this class is for outbound client connections and for the per-connection channel returned by the listener.

Ownership is exclusive: the channel is non-copyable and move-only. A moved-from channel may only be destroyed, move-assigned, or queried via is_open() (→ false) and idf_handle() (→ nullptr); calling any other method on it is undefined behavior. The destructor releases the channel if open.

Definition at line 80 of file stream_channel.hpp.

Constructor & Destructor Documentation

◆ stream_channel() [1/2]

idfxx::net::netconn::stream_channel::stream_channel ( )

Creates a TCP netconn with default address family (IPv4).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

◆ stream_channel() [2/2]

idfxx::net::netconn::stream_channel::stream_channel ( address_family fam )

explicit

Creates a TCP netconn for the given address family.

Parameters

fam	Address family.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Member Function Documentation

◆ close()

void idfxx::net::netconn::stream_channel::close ( )

inline

Closes the netconn.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 150 of file stream_channel.hpp.

References idfxx::unwrap().

◆ connect()

void idfxx::net::netconn::stream_channel::connect ( const endpoint & peer )

inline

Connects to the given remote endpoint.

Parameters

peer	Remote endpoint to connect to.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 132 of file stream_channel.hpp.

References idfxx::unwrap().

◆ make() [1/2]

static result< stream_channel > idfxx::net::netconn::stream_channel::make ( )

static

Creates a TCP netconn with default address family (IPv4).

Returns: The new channel, or an error.

◆ make() [2/2]

static result< stream_channel > idfxx::net::netconn::stream_channel::make ( address_family fam )

static

Creates a TCP netconn for the given address family.

Parameters

fam	Address family.

Returns: The new channel, or an error.

◆ peer_endpoint()

endpoint idfxx::net::netconn::stream_channel::peer_endpoint ( ) const

inline

Returns the remote endpoint the channel is connected to.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure (e.g. the channel is not connected).

Returns: The peer's endpoint.

Definition at line 368 of file stream_channel.hpp.

References idfxx::unwrap().

◆ recv() [1/2]

buffer idfxx::net::netconn::stream_channel::recv ( )

inline

Receives the next buffer from the connection.

On graceful peer close the returned buffer is non-owning (is_open() == false); this is the loop termination signal and is not an error.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Returns: The received buffer, or an empty buffer on graceful close.

Definition at line 320 of file stream_channel.hpp.

References idfxx::unwrap().

◆ recv() [2/2]

std::span< std::byte > idfxx::net::netconn::stream_channel::recv ( std::span< std::byte > buf )

inline

Receives data into a caller-provided buffer.

On graceful peer close the returned span is empty; this is the loop termination signal and is not an error.

Parameters

buf	Destination buffer.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Returns: Sub-span of buf covering the bytes actually received, or an empty span on graceful close.

Definition at line 345 of file stream_channel.hpp.

References idfxx::unwrap().

◆ send() [1/2]

size_t idfxx::net::netconn::stream_channel::send	(	std::span< const std::byte >	data,
		idfxx::flags< write_flag >	flags = `{}`
	)

inline

Sends a buffer on the TCP netconn.

By default the data is copied into the stack's buffers, so data may be reused or destroyed as soon as this call returns. Pass write_flag::no_copy to reference the caller's buffer instead.

In the default blocking mode the full buffer is sent or an error is thrown. The returned byte count is informational and only diverges from data.size() when write_flag::dont_block is set; for that partial-write accounting use try_send.

Warning: With write_flag::no_copy set, data must remain valid and unmodified until the data has been transmitted and acknowledged by the peer — not merely until this call returns. Use only for storage that outlives the connection (e.g. static or flash-resident data).

Parameters

data	Data to send.
flags	Flags controlling copy behaviour and PSH suppression.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Returns: Number of bytes accepted.

Definition at line 236 of file stream_channel.hpp.

◆ send() [2/2]

size_t idfxx::net::netconn::stream_channel::send	(	std::string_view	data,
		idfxx::flags< write_flag >	flags = `{}`
	)

inline

Sends a string view on the TCP netconn.

By default the data is copied into the stack's buffers, so data may be reused or destroyed as soon as this call returns. Pass write_flag::no_copy to reference the caller's buffer instead.

In the default blocking mode the full buffer is sent or an error is thrown. The returned byte count is informational and only diverges from data.size() when write_flag::dont_block is set; for that partial-write accounting use try_send.

Warning: With write_flag::no_copy set, data must remain valid and unmodified until the data has been transmitted and acknowledged by the peer — not merely until this call returns.

Parameters

data	Data to send.
flags	Flags controlling copy behaviour and PSH suppression.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Returns: Number of bytes accepted.

Definition at line 285 of file stream_channel.hpp.

◆ shutdown() [1/2]

void idfxx::net::netconn::stream_channel::shutdown ( )

inline

Shuts down both directions on the netconn.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 167 of file stream_channel.hpp.

References idfxx::unwrap().

◆ shutdown() [2/2]

void idfxx::net::netconn::stream_channel::shutdown ( direction dir )

inline

Shuts down one direction on the netconn (half-close).

The two directions are independent: after shutdown(direction::send) the peer sees end-of-stream but recv keeps returning data the peer sends until it closes; after shutdown(direction::receive) further reads return the empty-buffer close signal while sends still succeed.

Parameters

dir	Direction to shut down.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error on failure.

Definition at line 191 of file stream_channel.hpp.

References idfxx::unwrap().

◆ try_close()

result< void > idfxx::net::netconn::stream_channel::try_close ( )

Closes the netconn.

Returns: Success, or an error.

◆ try_connect()

result< void > idfxx::net::netconn::stream_channel::try_connect ( const endpoint & peer )

Connects to the given remote endpoint.

Parameters

peer	Remote endpoint to connect to.

Returns: Success, or an error.

◆ try_peer_endpoint()

result< endpoint > idfxx::net::netconn::stream_channel::try_peer_endpoint ( ) const

inline

Returns the remote endpoint the channel is connected to.

Returns: The peer's endpoint, or an error.

Definition at line 376 of file stream_channel.hpp.

◆ try_recv() [1/2]

result< buffer > idfxx::net::netconn::stream_channel::try_recv ( )

Receives the next buffer from the connection.

Returns: The received buffer (empty on graceful close), or an error.

◆ try_recv() [2/2]

result< std::span< std::byte > > idfxx::net::netconn::stream_channel::try_recv ( std::span< std::byte > buf )

Receives data into a caller-provided buffer.

Parameters

buf	Destination buffer.

Returns: Sub-span of buf covering the bytes actually received (empty on graceful close), or an error.

◆ try_send() [1/2]

result< size_t > idfxx::net::netconn::stream_channel::try_send	(	std::span< const std::byte >	data,
		idfxx::flags< write_flag >	flags = `{}`
	)

Sends a buffer on the TCP netconn.

By default the data is copied into the stack's buffers, so data may be reused or destroyed as soon as this call returns. Pass write_flag::no_copy to reference the caller's buffer instead.

Warning: With write_flag::no_copy set, data must remain valid and unmodified until the data has been transmitted and acknowledged by the peer — not merely until this call returns. Use only for storage that outlives the connection (e.g. static or flash-resident data).

Parameters

data	Data to send.
flags	Flags controlling copy behaviour and PSH suppression.

Returns: Number of bytes accepted, or an error.

◆ try_send() [2/2]

result< size_t > idfxx::net::netconn::stream_channel::try_send	(	std::string_view	data,
		idfxx::flags< write_flag >	flags = `{}`
	)

Sends a string view on the TCP netconn.

By default the data is copied into the stack's buffers, so data may be reused or destroyed as soon as this call returns. Pass write_flag::no_copy to reference the caller's buffer instead.

Warning: With write_flag::no_copy set, data must remain valid and unmodified until the data has been transmitted and acknowledged by the peer — not merely until this call returns.

Parameters

data	Data to send.
flags	Flags controlling copy behaviour and PSH suppression.

Returns: Number of bytes accepted, or an error.

◆ try_shutdown() [1/2]

result< void > idfxx::net::netconn::stream_channel::try_shutdown ( )

Shuts down both directions on the netconn.

Returns: Success, or an error.

◆ try_shutdown() [2/2]

result< void > idfxx::net::netconn::stream_channel::try_shutdown ( direction dir )

Shuts down one direction on the netconn (half-close).

The two directions are independent: after shutdown(direction::send) the peer sees end-of-stream but recv keeps returning data the peer sends until it closes; after shutdown(direction::receive) further reads return the empty-buffer close signal while sends still succeed.

Parameters

dir	Direction to shut down.

Returns: Success, or an error.

Friends And Related Symbol Documentation

◆ listener

friend class listener

friend

Definition at line 379 of file stream_channel.hpp.

The documentation for this class was generated from the following file:

idfxx_net/include/idfxx/net/netconn/stream_channel.hpp

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ stream_channel() [1/2]

◆ stream_channel() [2/2]

Member Function Documentation

◆ close()

◆ connect()

◆ make() [1/2]

◆ make() [2/2]

◆ peer_endpoint()

◆ recv() [1/2]

◆ recv() [2/2]

◆ send() [1/2]

◆ send() [2/2]

◆ shutdown() [1/2]

◆ shutdown() [2/2]

◆ try_close()

◆ try_connect()

◆ try_peer_endpoint()

◆ try_recv() [1/2]

◆ try_recv() [2/2]

◆ try_send() [1/2]

◆ try_send() [2/2]

◆ try_shutdown() [1/2]

◆ try_shutdown() [2/2]

Friends And Related Symbol Documentation

◆ listener