Direct-BT v3.3.0-1-gc2d430c
Direct-BT - Direct Bluetooth Programming.
Classes | Typedefs | Enumerations | Functions | Variables
IO Utilities

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 iostatejau::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 iostatejau::io::operator^= (iostate &lhs, const iostate rhs) noexcept
 
constexpr iostate jau::io::operator| (const iostate lhs, const iostate rhs) noexcept
 
constexpr iostatejau::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< ByteInStreamjau::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

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_urigiven path or uri for with a ByteInStream instance shall be established.
timeoutin 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_fileinput file name path, - denotes std::stdin.
buffersecure std::vector buffer, passed down to consumer_fn
consumer_fnStreamConsumerFunc 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
inthe input byte stream to read from
buffersecure std::vector buffer, passed down to consumer_fn
consumer_fnStreamConsumerFunc 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
inthe input byte stream to read from
buffer1secure std::vector buffer, passed down to consumer_fn
buffer2secure std::vector buffer, passed down to consumer_fn
consumer_fnStreamConsumerFunc 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
urlthe URL to open a connection to and stream bytes from
buffersecure std::vector buffer, passed down to consumer_fn
consumer_fnStreamConsumerFunc 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
urlthe URL to open a connection to and stream bytes from
bufferthe ringbuffer destination to write into
header_syncsynchronization object for URL header completion
has_content_lengthindicating whether content_length is known from server
content_lengthtracking the content_length
total_readtracking the total_read
resultreference 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
urian 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
urian 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
urian 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
urian 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.