idfxx::net::netconn::buffer Class Reference

Owning handle for a netconn buffer. More...

Classes
class	segment_view
	A forward range over a buffer's data segments. More...

Public Member Functions
	buffer () noexcept=default
	Default-constructs an empty (non-owning) buffer handle.
	~buffer ()
	Frees the buffer if owned.
	buffer (const buffer &)=delete
buffer &	operator= (const buffer &)=delete
	buffer (buffer &&other) noexcept
	Move construction transfers ownership.
buffer &	operator= (buffer &&other) noexcept
	Move assignment frees the current buffer and takes the other's.
::netbuf *	idf_handle () const noexcept
	Returns the underlying lwIP netbuf*, or nullptr if moved-from / empty.
bool	is_open () const noexcept
	Returns true if this buffer owns a netbuf (false after move-from).
size_t	len () const noexcept
	Returns the total length of all segments.
std::optional< endpoint >	from_endpoint () const noexcept
	Returns the source endpoint for a UDP receive.
segment_view	segments () const noexcept
	Returns a forward range over the buffer's data segments.
void	attach (std::span< const std::byte > data)
	Attaches an external (non-owned) buffer for sending.
size_t	copy_into (std::span< std::byte > dst) const noexcept
	Copies all segments into a destination buffer.
result< void >	try_attach (std::span< const std::byte > data)
	Attaches an external (non-owned) buffer for sending.

Static Public Member Functions
static result< buffer >	make ()
	Allocates an empty buffer.

Friends
class	stream_channel
class	datagram_channel
class	raw_channel
class	detail::connectionless_channel

Detailed Description

Owning handle for a netconn buffer.

A buffer holds the data returned by *_channel::try_recv and, for UDP, the source address and port. Data may span multiple segments — iterate segments() to walk them without copying, or copy_into() to gather into a contiguous buffer.

Ownership is exclusive: the buffer is non-copyable and move-only. A moved-from buffer 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 held buffer.

Warning

attach() references external memory rather than copying it; the referenced buffer must outlive the send (see the method documentation). To send a transient buffer without that obligation, prefer the copying datagram_channel::try_send(std::span) / raw_channel::try_send(std::span) overloads, which manage the buffer's lifetime internally.

Definition at line 60 of file buffer.hpp.

Constructor & Destructor Documentation

buffer() [1/3]

idfxx::net::netconn::buffer::buffer ( )

defaultnoexcept

Default-constructs an empty (non-owning) buffer handle.

~buffer()

idfxx::net::netconn::buffer::~buffer

(

)

Frees the buffer if owned.

buffer() [2/3]

idfxx::net::netconn::buffer::buffer ( const buffer &  )

delete

buffer() [3/3]

idfxx::net::netconn::buffer::buffer ( buffer &&  other )

noexcept

Move construction transfers ownership.

Member Function Documentation

attach()

void idfxx::net::netconn::buffer::attach ( std::span< const std::byte >  data )

inline

Attaches an external (non-owned) buffer for sending.

The data is referenced, not copied.

Warning

data must remain valid and unmodified until the buffer has been handed to and consumed by a send (netconn::datagram_channel::try_send / try_send_to or the raw equivalents). Sending a transient buffer is a use-after-free; for that case use the copying *_channel::try_send(std::span) overloads, which manage the buffer's lifetime internally.

Parameters

data	Buffer to reference.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

Exceptions

std::system_error

on failure.

Definition at line 203 of file buffer.hpp.

References idfxx::unwrap().

copy_into()

size_t idfxx::net::netconn::buffer::copy_into ( std::span< std::byte >  dst ) const

noexcept

Copies all segments into a destination buffer.

Parameters

dst	Destination buffer.

Returns

Number of bytes copied (≤ dst.size()).

from_endpoint()

std::optional< endpoint > idfxx::net::netconn::buffer::from_endpoint ( ) const

noexcept

Returns the source endpoint for a UDP receive.

Returns

The source endpoint, or std::nullopt if unavailable.

idf_handle()

::netbuf * idfxx::net::netconn::buffer::idf_handle ( ) const

inlinenoexcept

Returns the underlying lwIP netbuf*, or nullptr if moved-from / empty.

For observation and interop only: do not free or re-own the returned netbuf — doing so desynchronizes this handle's invariants.

Definition at line 90 of file buffer.hpp.

is_open()

bool idfxx::net::netconn::buffer::is_open ( ) const

inlinenoexcept

Returns true if this buffer owns a netbuf (false after move-from).

Definition at line 93 of file buffer.hpp.

len()

size_t idfxx::net::netconn::buffer::len ( ) const

noexcept

Returns the total length of all segments.

make()

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

static

Allocates an empty buffer.

Returns

The new buffer, or an error.

operator=() [1/2]

buffer & idfxx::net::netconn::buffer::operator= ( buffer &&  other )

noexcept

Move assignment frees the current buffer and takes the other's.

operator=() [2/2]

buffer & idfxx::net::netconn::buffer::operator= ( const buffer &  )

delete

segments()

segment_view idfxx::net::netconn::buffer::segments ( ) const

inlinenoexcept

Returns a forward range over the buffer's data segments.

Walk a multi-segment receive without copying:

for (auto seg : buf.segments()) {
    // process seg (std::span<const std::byte>) without copying
}

The range is safe to obtain from a moved-from or empty buffer — it is simply empty.

Returns

A segment_view spanning the buffer's segments in order.

Definition at line 183 of file buffer.hpp.

try_attach()

result< void > idfxx::net::netconn::buffer::try_attach

(

std::span< const std::byte >

data

)

Attaches an external (non-owned) buffer for sending.

The data is referenced, not copied.

Warning

data must remain valid and unmodified until the buffer has been handed to and consumed by a send (netconn::datagram_channel::try_send / try_send_to or the raw equivalents). Sending a transient buffer is a use-after-free; for that case use the copying *_channel::try_send(std::span) overloads, which manage the buffer's lifetime internally.

Parameters

data	Buffer to reference.

Returns

Success, or an error.

Friends And Related Symbol Documentation

datagram_channel

friend class datagram_channel

friend

Definition at line 233 of file buffer.hpp.

detail::connectionless_channel

friend class detail::connectionless_channel

friend

Definition at line 235 of file buffer.hpp.

raw_channel

friend class raw_channel

friend

Definition at line 234 of file buffer.hpp.

stream_channel

friend class stream_channel

friend

Definition at line 232 of file buffer.hpp.

---

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

• idfxx_net/include/idfxx/net/netconn/buffer.hpp