Stream.hpp

This File On Github
Ask A Question

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

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.
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, data::v_io_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::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.

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, data::v_io_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

IOStream

I/O Stream.

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

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.
data::v_io_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.

data::v_io_size bytesLeft

AsyncInlineWriteData::AsyncInlineWriteData

  1. Default constructor.
    AsyncInlineWriteData()
    
  2. Constructor.
    • @param data
    • @param size
    AsyncInlineWriteData(const void* data, data::v_io_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, data::v_io_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(data::v_io_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.
data::v_io_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.

data::v_io_size bytesLeft

AsyncInlineReadData::AsyncInlineReadData

  1. Default constructor.
    AsyncInlineReadData()
    
  2. Constructor.
    • @param data
    • @param size
    AsyncInlineReadData(void* data, data::v_io_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, data::v_io_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(data::v_io_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, data::v_io_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, data::v_io_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, data::v_io_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, data::v_io_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,
                                oatpp::data::v_io_size transferSize,
                                void* buffer,
                                oatpp::data::v_io_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,
                                             oatpp::data::v_io_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, data::v_io_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, data::v_io_size size)