Input and Output (IO) types and functionality. More...

Classes
class	jau::io::ByteInStream
	Abstract byte input stream object. More...

class	jau::io::ByteInStream_Feed
	Ringbuffer-Based byte input stream with an externally provisioned data feed. More...

class	jau::io::ByteInStream_File
	File based byte input stream, including named file descriptor. More...

class	jau::io::ByteInStream_Recorder
	Wrapped byte input stream with the capability to record the read byte stream at will. More...

class	jau::io::ByteInStream_SecMemory
	Secure Memory-Based byte input stream. More...

class	jau::io::ByteInStream_URL
	Ringbuffer-Based byte input stream with a URL connection provisioned data feed. More...

class	jau::io::ByteOutStream
	Abstract byte output stream object, to write data to a sink. More...

class	jau::io::ByteOutStream_File
	File based byte output stream, including named file descriptor. More...

class	jau::io::iostate_func
	Supporting std::basic_ios's iostate functionality for all ByteInStream implementations. More...

class	jau::io::url_header_sync
	Synchronization for URL header completion as used by asynchronous read_url_stream(). More...

Typedefs
typedef jau::ringbuffer< uint8_t, size_t >	jau::io::ByteRingbuffer

typedef jau::ordered_atomic< async_io_result_t, std::memory_order_relaxed >	jau::io::relaxed_atomic_async_io_result_t

typedef std::basic_string< char, std::char_traits< char >, jau::callocator_sec< char > >	jau::io::secure_string

template<typename T >
using	jau::io::secure_vector = std::vector< T, jau::callocator_sec< T > >

typedef jau::function< bool(secure_vector< uint8_t > &, bool)>	jau::io::StreamConsumerFunc
	Stream consumer function. More...

Enumerations
enum class	jau::io::async_io_result_t : int8_t { jau::io::async_io_result_t::FAILED = -1 , jau::io::async_io_result_t::NONE = 0 , jau::io::async_io_result_t::SUCCESS = 1 }
	Asynchronous I/O operation result value. More...

enum class	jau::io::io_dir_t : int8_t { jau::io::io_dir_t::READ = 0 , jau::io::io_dir_t::WRITE = 1 }
	I/O direction, read or write. More...

enum class	jau::io::iostate : uint32_t { jau::io::iostate::none = 0 , jau::io::iostate::goodbit = 0 , jau::io::iostate::badbit = 1 << 0 , jau::io::iostate::eofbit = 1 << 1 , jau::io::iostate::failbit = 1 << 2 , jau::io::iostate::timeout = 1 << 3 }
	Mimic std::ios_base::iostate for state functionality, see iostate_func. More...

Functions
std::string_view	jau::io::uri_tk::get_scheme (const std::string_view &uri) noexcept
	Returns the valid uri-scheme from given uri, which is empty if no valid scheme is included. More...

bool	jau::io::uri_tk::is_httpx_protocol (const std::string_view &uri) noexcept
	Returns true if the uri-scheme of given uri matches the `http` or `https` protocol, i.e. More...

bool	jau::io::uri_tk::is_local_file_protocol (const std::string_view &uri) noexcept
	Returns true if the uri-scheme of given uri matches the local `file` protocol, i.e. More...

constexpr uint32_t	jau::io::number (const iostate rhs) noexcept

constexpr bool	jau::io::operator!= (const iostate lhs, const iostate rhs) noexcept

constexpr iostate	jau::io::operator& (const iostate lhs, const iostate rhs) noexcept

constexpr iostate &	jau::io::operator&= (iostate &lhs, const iostate rhs) noexcept

constexpr bool	jau::io::operator== (const iostate lhs, const iostate rhs) noexcept

constexpr iostate	jau::io::operator^ (const iostate lhs, const iostate rhs) noexcept

constexpr iostate &	jau::io::operator^= (iostate &lhs, const iostate rhs) noexcept

constexpr iostate	jau::io::operator\| (const iostate lhs, const iostate rhs) noexcept

constexpr iostate &	jau::io::operator\|= (iostate &lhs, const iostate rhs) noexcept

constexpr iostate	jau::io::operator~ (const iostate rhs) noexcept

void	jau::io::print_stats (const std::string &prefix, const uint64_t &out_bytes_total, const jau::fraction_i64 &td) noexcept

bool	jau::io::uri_tk::protocol_supported (const std::string_view &uri) noexcept
	Returns true if the uri-scheme of given uri matches a supported by libcurl network protocols otherwise false. More...

uint64_t	jau::io::read_file (const std::string &input_file, secure_vector< uint8_t > &buffer, const StreamConsumerFunc &consumer_fn) noexcept
	Synchronous byte input stream reader from given file path using the given StreamConsumerFunc consumer_fn. More...

uint64_t	jau::io::read_stream (ByteInStream &in, secure_vector< uint8_t > &buffer, const StreamConsumerFunc &consumer_fn) noexcept
	Synchronous byte input stream reader using the given StreamConsumerFunc consumer_fn. More...

uint64_t	jau::io::read_stream (ByteInStream &in, secure_vector< uint8_t > &buffer1, secure_vector< uint8_t > &buffer2, const StreamConsumerFunc &consumer_fn) noexcept
	Synchronous double-buffered byte input stream reader using the given StreamConsumerFunc consumer_fn. More...

std::unique_ptr< std::thread >	jau::io::read_url_stream (const std::string &url, ByteRingbuffer &buffer, jau::io::url_header_sync &header_sync, jau::relaxed_atomic_bool &has_content_length, jau::relaxed_atomic_uint64 &content_length, jau::relaxed_atomic_uint64 &total_read, relaxed_atomic_async_io_result_t &result) noexcept
	Asynchronous URL read content using the given byte jau::ringbuffer, allowing parallel reading. More...

uint64_t	jau::io::read_url_stream (const std::string &url, secure_vector< uint8_t > &buffer, const StreamConsumerFunc &consumer_fn) noexcept
	Synchronous URL stream reader using the given StreamConsumerFunc consumer_fn. More...

std::vector< std::string_view >	jau::io::uri_tk::supported_protocols () noexcept
	Returns a list of supported protocol supported by libcurl network protocols, queried at runtime. More...

std::unique_ptr< ByteInStream >	jau::io::to_ByteInStream (const std::string &path_or_uri, jau::fraction_i64 timeout=20_s) noexcept
	Parses the given path_or_uri, if it matches a supported protocol, see jau::io::uri::protocol_supported(), but is not a local file, see jau::io::uri::is_local_file_protocol(), ByteInStream_URL is being attempted. More...

std::string	jau::io::to_string (const iostate mask) noexcept

Variables
const size_t	jau::io::BEST_URLSTREAM_RINGBUFFER_SIZE = 2_uz * 16384_uz

Detailed Description

Input and Output (IO) types and functionality.

Typedef Documentation

◆ secure_vector

template<typename T >

using jau::io::secure_vector = typedef std::vector<T, jau::callocator_sec<T> >

Definition at line 46 of file io_util.hpp.

◆ secure_string

typedef std::basic_string<char, std::char_traits<char>, jau::callocator_sec<char> > jau::io::secure_string

Definition at line 48 of file io_util.hpp.

◆ ByteRingbuffer

typedef jau::ringbuffer<uint8_t, size_t> jau::io::ByteRingbuffer

Definition at line 50 of file io_util.hpp.

◆ relaxed_atomic_async_io_result_t

typedef jau::ordered_atomic<async_io_result_t, std::memory_order_relaxed> jau::io::relaxed_atomic_async_io_result_t

Definition at line 78 of file io_util.hpp.

◆ StreamConsumerFunc

typedef jau::function<bool(secure_vector<uint8_t>& , bool )> jau::io::StreamConsumerFunc

Stream consumer function.

bool consumer(secure_vector<uint8_t>& data, bool is_final)

Returns true to signal continuation, false to end streaming.

Definition at line 86 of file io_util.hpp.

Enumeration Type Documentation

◆ iostate

enum class jau::io::iostate : uint32_t

strong

Mimic std::ios_base::iostate for state functionality, see iostate_func.

This enum class type fulfills C++ named requirements: BitmaskType.

Enumerator
none	No error occurred nor has EOS being reached. Value is no bit set!
goodbit	No error occurred nor has EOS being reached. Value is no bit set!
badbit	Irrecoverable stream error, including loss of integrity of the underlying stream or media.
eofbit	An input operation reached the end of its stream.
failbit	Input or output operation failed (formatting or extraction error).
timeout	Input or output operation failed due to timeout.

Definition at line 53 of file byte_stream.hpp.

◆ io_dir_t

enum class jau::io::io_dir_t : int8_t

strong

I/O direction, read or write.

Enumerator
READ	Read Operation.
WRITE	Write Operation.

Definition at line 57 of file io_util.hpp.

◆ async_io_result_t

enum class jau::io::async_io_result_t : int8_t

strong

Asynchronous I/O operation result value.

Enumerator
FAILED	Operation failed.
NONE	Operation still in progress.
SUCCESS	Operation succeeded.

Definition at line 68 of file io_util.hpp.

Function Documentation

◆ number()

constexpr uint32_t jau::io::number ( const iostate rhs )

constexprnoexcept

Examples: dbt_peripheral00.cpp, and dbt_scanner10.cpp.

Definition at line 72 of file byte_stream.hpp.

◆ operator~()

constexpr iostate jau::io::operator~ ( const iostate rhs )

constexprnoexcept

Definition at line 75 of file byte_stream.hpp.

◆ operator^()

constexpr iostate jau::io::operator^	(	const iostate	lhs,
		const iostate	rhs
	)

constexprnoexcept

Definition at line 78 of file byte_stream.hpp.

◆ operator|()

constexpr iostate jau::io::operator\|	(	const iostate	lhs,
		const iostate	rhs
	)

constexprnoexcept

Definition at line 81 of file byte_stream.hpp.

◆ operator&()

constexpr iostate jau::io::operator&	(	const iostate	lhs,
		const iostate	rhs
	)

constexprnoexcept

Definition at line 84 of file byte_stream.hpp.

◆ operator|=()

constexpr iostate & jau::io::operator\|=	(	iostate &	lhs,
		const iostate	rhs
	)

constexprnoexcept

Definition at line 87 of file byte_stream.hpp.

◆ operator&=()

constexpr iostate & jau::io::operator&=	(	iostate &	lhs,
		const iostate	rhs
	)

constexprnoexcept

Definition at line 91 of file byte_stream.hpp.

◆ operator^=()

constexpr iostate & jau::io::operator^=	(	iostate &	lhs,
		const iostate	rhs
	)

constexprnoexcept

Definition at line 95 of file byte_stream.hpp.

◆ operator==()

constexpr bool jau::io::operator==	(	const iostate	lhs,
		const iostate	rhs
	)

constexprnoexcept

Definition at line 99 of file byte_stream.hpp.

◆ operator!=()

constexpr bool jau::io::operator!=	(	const iostate	lhs,
		const iostate	rhs
	)

constexprnoexcept

Definition at line 102 of file byte_stream.hpp.

◆ to_string()

std::string jau::io::to_string ( const iostate mask )

noexcept

Definition at line 170 of file byte_stream.cpp.

Here is the caller graph for this function:

◆ to_ByteInStream()

std::unique_ptr< ByteInStream > jau::io::to_ByteInStream	(	const std::string &	path_or_uri,
		jau::fraction_i64	timeout = `20_s`
	)

noexcept

Parses the given path_or_uri, if it matches a supported protocol, see jau::io::uri::protocol_supported(), but is not a local file, see jau::io::uri::is_local_file_protocol(), ByteInStream_URL is being attempted.

If the above fails, ByteInStream_File is attempted.

If non of the above leads to a ByteInStream without ByteInStream::fail(), nullptr is returned.

Parameters

path_or_uri	given path or uri for with a ByteInStream instance shall be established.
timeout	in case `path_or_uri` resolves to ByteInStream_URL, timeout is being used as maximum duration to wait for next bytes at ByteInStream_URL::available(), defaults to 20_s

Returns: a working ByteInStream w/o ByteInStream::fail() or nullptr

Definition at line 447 of file byte_stream.cpp.

Here is the caller graph for this function:

◆ read_file()

uint64_t jau::io::read_file	(	const std::string &	input_file,
		secure_vector< uint8_t > &	buffer,
		const StreamConsumerFunc &	consumer_fn
	)

noexcept

Synchronous byte input stream reader from given file path using the given StreamConsumerFunc consumer_fn.

To abort streaming, user may return false from the given consumer_func.

It is guaranteed that consumer_fn() is called with is_final=true once at the end, even if input_file stream has zero size.

Parameters

input_file	input file name path, `-` denotes std::stdin.
buffer	secure std::vector buffer, passed down to consumer_fn
consumer_fn	StreamConsumerFunc consumer for each received heap of bytes, returning true to continue stream of false to abort.

Returns: total bytes read or 0 if error

Definition at line 46 of file io_util.cpp.

◆ read_stream() [1/2]

uint64_t jau::io::read_stream	(	ByteInStream &	in,
		secure_vector< uint8_t > &	buffer,
		const StreamConsumerFunc &	consumer_fn
	)

noexcept

Synchronous byte input stream reader using the given StreamConsumerFunc consumer_fn.

To abort streaming, user may return false from the given consumer_func.

It is guaranteed that consumer_fn() is called with is_final=true once at the end, even input stream has zero size.

Parameters

in	the input byte stream to read from
buffer	secure std::vector buffer, passed down to consumer_fn
consumer_fn	StreamConsumerFunc consumer for each received heap of bytes, returning true to continue stream of false to abort.

Returns: total bytes read or 0 if error

Definition at line 59 of file io_util.cpp.

Here is the caller graph for this function:

◆ read_stream() [2/2]

uint64_t jau::io::read_stream	(	ByteInStream &	in,
		secure_vector< uint8_t > &	buffer1,
		secure_vector< uint8_t > &	buffer2,
		const StreamConsumerFunc &	consumer_fn
	)

noexcept

Synchronous double-buffered byte input stream reader using the given StreamConsumerFunc consumer_fn.

To abort streaming, user may return false from the given consumer_func.

It is guaranteed that consumer_fn() is called with is_final=true once at the end, even if input stream has zero size.

Implementation reads one buffer ahead in respect to consumer_fn().
If reading zero bytes on the next buffer, it propagates the end-of-file (EOF) to the previous buffer which will be send via consumer_fn() next.

This way, the consumer_fn() will always receive its is_final flag on the last sent bytes (size > 0) even if the content-size is unknown (pipe).
Hence it allows e.g. decryption to work where the final data chunck must be processed as such.

Parameters

in	the input byte stream to read from
buffer1	secure std::vector buffer, passed down to consumer_fn
buffer2	secure std::vector buffer, passed down to consumer_fn
consumer_fn	StreamConsumerFunc consumer for each received heap of bytes, returning true to continue stream of false to abort.

Returns: total bytes read or 0 if error

Definition at line 100 of file io_util.cpp.

◆ read_url_stream() [1/2]

uint64_t jau::io::read_url_stream	(	const std::string &	url,
		secure_vector< uint8_t > &	buffer,
		const StreamConsumerFunc &	consumer_fn
	)

noexcept

Synchronous URL stream reader using the given StreamConsumerFunc consumer_fn.

To abort streaming, user may return false from the given consumer_func.

Standard implementation uses curl, hence all libcurl network protocols are supported, see jau::io::uri::supported_protocols().

If the uri-sheme doesn't match a supported protocol, see jau::io::uri::protocol_supported(), function returns immediately with zero bytes.

Parameters

url	the URL to open a connection to and stream bytes from
buffer	secure std::vector buffer, passed down to consumer_fn
consumer_fn	StreamConsumerFunc consumer for each received heap of bytes, returning true to continue stream of false to abort.

Returns: total bytes read or 0 if transmission error or protocol of given url is not supported

Definition at line 309 of file io_util.cpp.

Here is the caller graph for this function:

◆ read_url_stream() [2/2]

std::unique_ptr< std::thread > jau::io::read_url_stream	(	const std::string &	url,
		ByteRingbuffer &	buffer,
		jau::io::url_header_sync &	header_sync,
		jau::relaxed_atomic_bool &	has_content_length,
		jau::relaxed_atomic_uint64 &	content_length,
		jau::relaxed_atomic_uint64 &	total_read,
		relaxed_atomic_async_io_result_t &	result
	)

noexcept

Asynchronous URL read content using the given byte jau::ringbuffer, allowing parallel reading.

To abort streaming, user may set given reference results to a value other than async_io_result_t::NONE.

Standard implementation uses curl, hence all libcurl network protocols are supported, see jau::io::uri::supported_protocols().

If the uri-sheme doesn't match a supported protocol, see jau::io::uri::protocol_supported(), function returns with nullptr.

Parameters

url	the URL to open a connection to and stream bytes from
buffer	the ringbuffer destination to write into
header_sync	synchronization object for URL header completion
has_content_length	indicating whether content_length is known from server
content_length	tracking the content_length
total_read	tracking the total_read
result	reference to tracking async_io_result_t. If set to other than async_io_result_t::NONE while streaming, streaming is aborted.

Returns: the url background reading thread unique-pointer or nullptr if protocol of given url is not supported

Definition at line 729 of file io_util.cpp.

◆ print_stats()

void jau::io::print_stats	(	const std::string &	prefix,
		const uint64_t &	out_bytes_total,
		const jau::fraction_i64 &	td
	)

noexcept

Definition at line 761 of file io_util.cpp.

Here is the caller graph for this function:

◆ supported_protocols()

std::vector< std::string_view > jau::io::uri_tk::supported_protocols ( )

noexcept

Returns a list of supported protocol supported by libcurl network protocols, queried at runtime.

See also: protocol_supported()

Definition at line 159 of file io_util.cpp.

Here is the caller graph for this function:

◆ get_scheme()

std::string_view jau::io::uri_tk::get_scheme ( const std::string_view & uri )

noexcept

Returns the valid uri-scheme from given uri, which is empty if no valid scheme is included.

The given uri must include at least a colon after the uri-scheme part.

Parameters

uri an uri

Returns: valid uri-scheme, empty if non found

Definition at line 182 of file io_util.cpp.

Here is the caller graph for this function:

◆ protocol_supported()

bool jau::io::uri_tk::protocol_supported ( const std::string_view & uri )

noexcept

Returns true if the uri-scheme of given uri matches a supported by libcurl network protocols otherwise false.

The uri-scheme is retrieved via get_scheme() passing given uri, hence must include at least a colon after the uri-scheme part.

The libcurl supported protocols is queried at runtime, see supported_protocols().

Parameters

uri	an uri to test

Returns: true if the uri-scheme of given uri is supported, otherwise false.

See also: supported_protocols(); get_scheme()

Definition at line 194 of file io_util.cpp.

Here is the caller graph for this function:

◆ is_local_file_protocol()

bool jau::io::uri_tk::is_local_file_protocol ( const std::string_view & uri )

noexcept

Returns true if the uri-scheme of given uri matches the local file protocol, i.e.

starts with file://.

Parameters

uri	an uri to test

Definition at line 204 of file io_util.cpp.

Here is the caller graph for this function:

◆ is_httpx_protocol()

bool jau::io::uri_tk::is_httpx_protocol ( const std::string_view & uri )

noexcept

Returns true if the uri-scheme of given uri matches the http or https protocol, i.e.

starts with http: or https:.

Parameters

uri	an uri to test

Definition at line 208 of file io_util.cpp.

Variable Documentation

◆ BEST_URLSTREAM_RINGBUFFER_SIZE

const size_t jau::io::BEST_URLSTREAM_RINGBUFFER_SIZE = 2_uz * 16384_uz

extern

Definition at line 73 of file byte_stream.cpp.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ secure_vector

◆ secure_string

◆ ByteRingbuffer

◆ relaxed_atomic_async_io_result_t

◆ StreamConsumerFunc

Enumeration Type Documentation

◆ iostate

◆ io_dir_t

◆ async_io_result_t

Function Documentation

◆ number()

◆ operator~()

◆ operator^()

◆ operator|()

◆ operator&()

◆ operator|=()

◆ operator&=()

◆ operator^=()

◆ operator==()

◆ operator!=()

◆ to_string()

◆ to_ByteInStream()

◆ read_file()

◆ read_stream() [1/2]

◆ read_stream() [2/2]

◆ read_url_stream() [1/2]

◆ read_url_stream() [2/2]

◆ print_stats()

◆ supported_protocols()

◆ get_scheme()

◆ protocol_supported()

◆ is_local_file_protocol()

◆ is_httpx_protocol()

Variable Documentation

◆ BEST_URLSTREAM_RINGBUFFER_SIZE