Stream.hpp

This File On Github
Ask A Question

API: latest
module: oatpp
#include "oatpp/core/data/stream/Stream.hpp"

StreamType

Stream Type.

namespace oatpp { namespace data { namespace stream { 
  enum StreamType : v_int32;
}}}

StreamType::STREAM_FINITE

Finite stream.

STREAM_FINITE = 0

StreamType::STREAM_INFINITE

Infinite stream.

STREAM_INFINITE = 1

Context

Stream Context.

namespace oatpp { namespace data { namespace stream { 
  class Context {}
}}}

Typedefs

Type Name Summary
oatpp::data::share::LazyStringMap<oatpp::data::share::StringKeyLabel> Properties Convenience typedef for oatpp::data::share::LazyStringMap.

Methods

Return Type Name Summary
Properties& getMutableProperties protected. Get mutable additional optional context specific properties.
[none] Context Multiple implementations:
  1. Default constructor.
  2. Constructor.
[none] ~Context Virtual destructor.
void init Initialize stream context.
async::CoroutineStarter initAsync Initialize stream context in an async manner.
bool isInitialized Check if the stream context is initialized.
StreamType getStreamType Get stream type.
const Properties& getProperties Additional optional context specific properties.

Context::Properties

Convenience typedef for oatpp::data::share::LazyStringMap.

typedef oatpp::data::share::LazyStringMap<oatpp::data::share::StringKeyLabel> Properties

Context::getMutableProperties

protected. Get mutable additional optional context specific properties.

Properties& getMutableProperties()

Context::Context

  1. Default constructor.
    Context() = default
    
  2. Constructor.
    Context(Properties&& properties)
    

Context::~Context

Virtual destructor.

virtual ~Context() = default

Context::init

Initialize stream context.

virtual void init() = 0

Context::initAsync

Initialize stream context in an async manner.

virtual async::CoroutineStarter initAsync() = 0

Context::isInitialized

Check if the stream context is initialized.

  • @return - bool.

virtual bool isInitialized() const = 0

Context::getStreamType

Get stream type.

virtual StreamType getStreamType() const = 0

Context::getProperties

Additional optional context specific properties.

const Properties& getProperties() const

DefaultInitializedContext

The default implementation for context with no initialization.

namespace oatpp { namespace data { namespace stream { 
  class DefaultInitializedContext : public oatpp::data::stream::Context {}
}}}

Methods

Return Type Name Summary
[none] DefaultInitializedContext Multiple implementations:
  1. Constructor.
  2. Constructor.
void init Initialize stream context.
async::CoroutineStarter initAsync Initialize stream context in an async manner.
bool isInitialized Check if the stream context is initialized.
StreamType getStreamType Get stream type.

DefaultInitializedContext::DefaultInitializedContext

  1. Constructor.
    DefaultInitializedContext(StreamType streamType)
    
  2. Constructor.
    DefaultInitializedContext(StreamType streamType, Properties&& properties)
    

DefaultInitializedContext::init

Initialize stream context.
This particular implementation does nothing.

void init() override

DefaultInitializedContext::initAsync

Initialize stream context in an async manner. This particular implementation does nothing.

async::CoroutineStarter initAsync() override

DefaultInitializedContext::isInitialized

Check if the stream context is initialized. This particular implementation always returns true.

  • @return - bool.

bool isInitialized() const override

DefaultInitializedContext::getStreamType

Get stream type.

StreamType getStreamType() const override

IOMode

Stream I/O mode.

namespace oatpp { namespace data { namespace stream { 
  enum IOMode : v_int32;
}}}

IOMode::BLOCKING

Blocking stream I/O mode.

BLOCKING = 0

IOMode::NON_BLOCKING

Non-blocking stream I/O mode.

NON_BLOCKING = 1

OutputStream

Output Stream.

namespace oatpp { namespace data { namespace stream { 
  class OutputStream {}
}}}

Methods

Return Type Name Summary
[none] ~OutputStream Default virtual destructor.
data::v_io_size write Multiple implementations:
  1. Write data to stream up to count bytes, and return number of bytes actually written.
  2. Same as write((p_char8)data, std::strlen(data));.
  3. Same as write(str->getData(), str->getSize());
oatpp::async::Action suggestOutputStreamAction Implementation of OutputStream must suggest async actions for I/O results.
void setOutputStreamIOMode Set stream I/O mode.
IOMode getOutputStreamIOMode Get stream I/O mode.
Context& getOutputStreamContext Get stream context.
data::v_io_size writeChar Same as write(c, 1);.

OutputStream::~OutputStream

Default virtual destructor.

virtual ~OutputStream() = default

OutputStream::write

  1. Write data to stream up to count bytes, and return number of bytes actually written.
    It is a legal case if return result < count. Caller should handle this!
    • @param data - data to write.
    • @param count - number of bytes to write.
    • @return - actual number of bytes written. oatpp::data::v_io_size.
    virtual data::v_io_size write(const void *data, v_buff_size count) = 0
    
  2. Same as write((p_char8)data, std::strlen(data));.
    data::v_io_size write(const char* data)
    
  3. Same as write(str->getData(), str->getSize());
    data::v_io_size write(const oatpp::String& str)
    

OutputStream::suggestOutputStreamAction

Implementation of OutputStream must suggest async actions for I/O results.
Suggested Action is used for scheduling coroutines in async::Executor.
Stream MUST always give the same file-handle if applicable

virtual oatpp::async::Action suggestOutputStreamAction(data::v_io_size ioResult) = 0

OutputStream::setOutputStreamIOMode

Set stream I/O mode.

  • @throws

virtual void setOutputStreamIOMode(IOMode ioMode) = 0

OutputStream::getOutputStreamIOMode

Get stream I/O mode.

  • @return

virtual IOMode getOutputStreamIOMode() = 0

OutputStream::getOutputStreamContext

Get stream context.

virtual Context& getOutputStreamContext() = 0

OutputStream::writeChar

Same as write(c, 1);.

data::v_io_size writeChar(v_char8 c)

InputStream

Input Stream.

namespace oatpp { namespace data { namespace stream { 
  class InputStream {}
}}}

Methods

Return Type Name Summary
[none] ~InputStream Default virtual destructor.
data::v_io_size read Read data from stream up to count bytes, and return number of bytes actually read.
oatpp::async::Action suggestInputStreamAction Implementation of InputStream must suggest async actions for I/O results.
void setInputStreamIOMode Set stream I/O mode.
IOMode getInputStreamIOMode Get stream I/O mode.
Context& getInputStreamContext Get stream context.

InputStream::~InputStream

Default virtual destructor.

virtual ~InputStream() = default

InputStream::read

Read data from stream up to count bytes, and return number of bytes actually read.
It is a legal case if return result < count. Caller should handle this!

  • @param data - buffer to read data to.
  • @param count - size of the buffer.
  • @return - actual number of bytes read.

virtual data::v_io_size read(void *data, v_buff_size count) = 0

InputStream::suggestInputStreamAction

Implementation of InputStream must suggest async actions for I/O results.
Suggested Action is used for scheduling coroutines in async::Executor.
Stream MUST always give the same file-handle if applicable

virtual oatpp::async::Action suggestInputStreamAction(data::v_io_size ioResult) = 0

InputStream::setInputStreamIOMode

Set stream I/O mode.

  • @throws

virtual void setInputStreamIOMode(IOMode ioMode) = 0

InputStream::getInputStreamIOMode

Get stream I/O mode.

  • @return

virtual IOMode getInputStreamIOMode() = 0

InputStream::getInputStreamContext

Get stream context.

virtual Context& getInputStreamContext() = 0

IOStream

I/O Stream.

namespace oatpp { namespace data { namespace stream { 
  class IOStream : public InputStream, public OutputStream {}
}}}

Methods

Return Type Name Summary
void initContexts Init input/output stream contexts.
async::CoroutineStarter initContextsAsync Init input/output stream contexts in an async manner.

IOStream::initContexts

Init input/output stream contexts.

void initContexts()

IOStream::initContextsAsync

Init input/output stream contexts in an async manner.

async::CoroutineStarter initContextsAsync()

ConsistentOutputStream

Streams that guarantee data to be written in exact amount as specified in call to OutputStream::write() should extend this class.

namespace oatpp { namespace data { namespace stream { 
  class ConsistentOutputStream : public OutputStream {}
}}}

Methods

Return Type Name Summary
oatpp::async::Action suggestOutputStreamAction In case of a ConsistentOutputStream suggested Action is always oatpp::async::Action::TYPE_REPEAT if ioResult is greater then zero.
data::v_io_size writeAsString Multiple implementations:
  1. Convert value to string and write to stream.
  2. Convert value to string and write to stream.
  3. Convert value to string and write to stream.
  4. Convert value to string and write to stream.
  5. Convert value to string and write to stream.

ConsistentOutputStream::suggestOutputStreamAction

In case of a ConsistentOutputStream suggested Action is always oatpp::async::Action::TYPE_REPEAT if ioResult is greater then zero.

oatpp::async::Action suggestOutputStreamAction(data::v_io_size ioResult) override

ConsistentOutputStream::writeAsString

  1. Convert value to string and write to stream.
    data::v_io_size writeAsString(v_int32 value)
    
  2. Convert value to string and write to stream.
    data::v_io_size writeAsString(v_int64 value)
    
  3. Convert value to string and write to stream.
    data::v_io_size writeAsString(v_float32 value)
    
  4. Convert value to string and write to stream.
    data::v_io_size writeAsString(v_float64 value)
    
  5. Convert value to string and write to stream.
    data::v_io_size writeAsString(bool value)
    

AsyncInlineWriteData

Convenience structure for stream Async-Inline write operations.

namespace oatpp { namespace data { namespace stream { 
  struct AsyncInlineWriteData {}
}}}

Fields

Type Name Summary
const void* currBufferPtr Pointer to current position in the buffer.
v_buff_size bytesLeft Bytes left to write from the buffer.

Methods

Return Type Name Summary
[none] AsyncInlineWriteData Multiple implementations:
  1. Default constructor.
  2. Constructor.
void set Set currBufferPtr and bytesLeft values.
void inc Increase position in the write buffer by amount bytes.
void setEof Same as inc(bytesLeft).

AsyncInlineWriteData::currBufferPtr

Pointer to current position in the buffer.

const void* currBufferPtr

AsyncInlineWriteData::bytesLeft

Bytes left to write from the buffer.

v_buff_size bytesLeft

AsyncInlineWriteData::AsyncInlineWriteData

  1. Default constructor.
    AsyncInlineWriteData()
    
  2. Constructor.
    • @param data
    • @param size
    AsyncInlineWriteData(const void* data, v_buff_size size)
    

AsyncInlineWriteData::set

Set currBufferPtr and bytesLeft values.

  • @param data - pointer to buffer containing data to be written.
  • @param size - size in bytes of the buffer.

void set(const void* data, v_buff_size size)

AsyncInlineWriteData::inc

Increase position in the write buffer by amount bytes.
This will increase currBufferPtr and descrease bytesLeft values.

  • @param amount

void inc(v_buff_size amount)

AsyncInlineWriteData::setEof

Same as inc(bytesLeft).

void setEof()

AsyncInlineReadData

Convenience structure for stream Async-Inline read operations.

namespace oatpp { namespace data { namespace stream { 
  struct AsyncInlineReadData {}
}}}

Fields

Type Name Summary
void* currBufferPtr Pointer to current position in the buffer.
v_buff_size bytesLeft Bytes left to read to the buffer.

Methods

Return Type Name Summary
[none] AsyncInlineReadData Multiple implementations:
  1. Default constructor.
  2. Constructor.
void set Set currBufferPtr and bytesLeft values.
void inc Increase position in the read buffer by amount bytes.
void setEof Same as inc(bytesLeft).

AsyncInlineReadData::currBufferPtr

Pointer to current position in the buffer.

void* currBufferPtr

AsyncInlineReadData::bytesLeft

Bytes left to read to the buffer.

v_buff_size bytesLeft

AsyncInlineReadData::AsyncInlineReadData

  1. Default constructor.
    AsyncInlineReadData()
    
  2. Constructor.
    • @param data
    • @param size
    AsyncInlineReadData(void* data, v_buff_size size)
    

AsyncInlineReadData::set

Set currBufferPtr and bytesLeft values.

  • @param data - pointer to buffer to store read data.
  • @param size - size in bytes of the buffer.

void set(void* data, v_buff_size size)

AsyncInlineReadData::inc

Increase position in the read buffer by amount bytes.
This will increase currBufferPtr and descrease bytesLeft values.

  • @param amount

void inc(v_buff_size amount)

AsyncInlineReadData::setEof

Same as inc(bytesLeft).

void setEof()

WriteCallback

Callback for stream write operation.

namespace oatpp { namespace data { namespace stream { 
  class WriteCallback {}
}}}

Methods

Return Type Name Summary
[none] ~WriteCallback Default virtual destructor.
data::v_io_size write Write callback.

WriteCallback::~WriteCallback

Default virtual destructor.

virtual ~WriteCallback() = default

WriteCallback::write

Write callback.

virtual data::v_io_size write(const void *data, v_buff_size count) = 0

AsyncWriteCallback

Callback for stream asynchronous write operation.

namespace oatpp { namespace data { namespace stream { 
  class AsyncWriteCallback {}
}}}

Methods

Return Type Name Summary
[none] ~AsyncWriteCallback Default virtual destructor.
oatpp::async::Action writeAsyncInline Async-Inline write callback.

AsyncWriteCallback::~AsyncWriteCallback

Default virtual destructor.

virtual ~AsyncWriteCallback() = default

AsyncWriteCallback::writeAsyncInline

Async-Inline write callback.

virtual oatpp::async::Action writeAsyncInline(AsyncInlineWriteData& inlineData, oatpp::async::Action&& nextAction) = 0

AsyncWriteCallbackWithCoroutineStarter

Convenience callback to use coroutine starter instead of async inline method.

namespace oatpp { namespace data { namespace stream { 
  class AsyncWriteCallbackWithCoroutineStarter : public AsyncWriteCallback {}
}}}

Methods

Return Type Name Summary
oatpp::async::Action writeAsyncInline Async-Inline write callback.
async::CoroutineStarter writeAsync Implement this method!

AsyncWriteCallbackWithCoroutineStarter::writeAsyncInline

Async-Inline write callback.
Calls AsyncWriteCallbackWithCoroutineStarter::writeAsync() internally.

oatpp::async::Action writeAsyncInline(AsyncInlineWriteData& inlineData, oatpp::async::Action&& nextAction) override

AsyncWriteCallbackWithCoroutineStarter::writeAsync

Implement this method!
Write Callback. Data should be fully utilized on call to this method - no partial writes for this method.
Return Coroutine starter to start data-processing coroutine or, nullptr to do nothing.

virtual async::CoroutineStarter writeAsync(const void *data, v_buff_size count) = 0

DefaultWriteCallback

Default callback for stream write operation.
Uses writeExactSizeData() method underhood.

namespace oatpp { namespace data { namespace stream { 
  class DefaultWriteCallback : public WriteCallback {}
}}}

Methods

Return Type Name Summary
[none] DefaultWriteCallback Constructor.
data::v_io_size write Write callback.

DefaultWriteCallback::DefaultWriteCallback

Constructor.

  • @param stream - stream to write to.

DefaultWriteCallback(OutputStream* stream)

DefaultWriteCallback::write

Write callback.

data::v_io_size write(const void *data, v_buff_size count) override

DefaultAsyncWriteCallback

Default callback for stream asynchronous write operation. Uses writeExactSizeDataAsyncInline() method underhood.

namespace oatpp { namespace data { namespace stream { 
  class DefaultAsyncWriteCallback : public AsyncWriteCallback {}
}}}

Methods

Return Type Name Summary
[none] DefaultAsyncWriteCallback Constructor.
oatpp::async::Action writeAsyncInline Async-Inline write callback.

DefaultAsyncWriteCallback::DefaultAsyncWriteCallback

Constructor.

  • @param stream - stream to write to.

DefaultAsyncWriteCallback(const std::shared_ptr<OutputStream>& stream)

DefaultAsyncWriteCallback::writeAsyncInline

Async-Inline write callback.

oatpp::async::Action writeAsyncInline(AsyncInlineWriteData& inlineData, oatpp::async::Action&& nextAction) override

ReadCallback

Stream read callback.

namespace oatpp { namespace data { namespace stream { 
  class ReadCallback {}
}}}

Methods

Return Type Name Summary
[none] ~ReadCallback Default virtual destructor.
data::v_io_size read Read callback. Override this method!

ReadCallback::~ReadCallback

Default virtual destructor.

virtual ~ReadCallback() = default

ReadCallback::read

Read callback. Override this method!
Write up to count bytes to buffer and return the actual number of bytes written.
This method must return 0 in order to indicate end-of-file.

  • @param buffer - pointer to buffer.
  • @param count - size of the buffer.
  • @return - actual number of bytes written to buffer. 0 - to indicate end-of-file.

virtual data::v_io_size read(void *buffer, v_buff_size count) = 0

AsyncReadCallback

Callback for stream asynchronous read operation.

namespace oatpp { namespace data { namespace stream { 
  class AsyncReadCallback {}
}}}

Methods

Return Type Name Summary
[none] ~AsyncReadCallback Default virtual destructor.
oatpp::async::Action readAsyncInline Async-Inline read callback.

AsyncReadCallback::~AsyncReadCallback

Default virtual destructor.

virtual ~AsyncReadCallback() = default

AsyncReadCallback::readAsyncInline

Async-Inline read callback.

virtual oatpp::async::Action readAsyncInline(AsyncInlineReadData& inlineData, oatpp::async::Action&& nextAction) = 0

AsyncTransferError

Error of Asynchronous stream transfer.

namespace oatpp { namespace data { namespace stream { 
  class AsyncTransferError : public oatpp::async::Error {}
}}}

Methods

Return Type Name Summary
[none] AsyncTransferError Constructor.

AsyncTransferError::AsyncTransferError

Constructor.

  • @param what

AsyncTransferError(const char* what) : oatpp::async::Error(what)

transfer

Namespace: oatpp::data::stream

Read bytes from fromStream and write to writeCallback using buffer of size bufferSize transfer up to transferSize or until error if transferSize == 0

  • @param fromStream
  • @param transferSize
  • @param buffer
  • @param bufferSize
  • @return - amount of bytes actually transferred.

oatpp::data::v_io_size transfer(InputStream* fromStream,
                                WriteCallback* writeCallback,
                                v_buff_size transferSize,
                                void* buffer,
                                v_buff_size bufferSize)

transferAsync

Namespace: oatpp::data::stream

Same as transfer but asynchronous

oatpp::async::CoroutineStarter transferAsync(const std::shared_ptr<InputStream>& fromStream,
                                             const std::shared_ptr<AsyncWriteCallback>& writeCallback,
                                             v_buff_size transferSize,
                                             const std::shared_ptr<oatpp::data::buffer::IOBuffer>& buffer)

readExactSizeData

Namespace: oatpp::data::stream

Read exact amount of bytes to stream returns exact amount of bytes was read. return result can be < size only in case of some disaster like connection reset by peer

oatpp::data::v_io_size readExactSizeData(oatpp::data::stream::InputStream* stream, void* data, v_buff_size size)

writeExactSizeData

Namespace: oatpp::data::stream

Write exact amount of bytes to stream. returns exact amount of bytes was written. return result can be < size only in case of some disaster like broken pipe

oatpp::data::v_io_size writeExactSizeData(oatpp::data::stream::OutputStream* stream, const void* data, v_buff_size size)