# 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::ASYNCHRONOUS

Non-blocking stream I/O mode.

ASYNCHRONOUS = 1

# WriteCallback

Callback for stream write operation.

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

# Methods

Return Type Name Summary
[none] ~WriteCallback Default virtual destructor.
v_io_size write Write operation callback.
v_io_size writeSimple Multiple implementations:
  1. Same as write((p_char8)data, std::strlen(data));.
  2. Same as write(str->getData(), str->getSize());
v_io_size writeCharSimple Same as write(c, 1);.

# WriteCallback::~WriteCallback

Default virtual destructor.

virtual ~WriteCallback() = default

# WriteCallback::write

Write operation callback.

  • @param data - pointer to data.
  • @param count - size of the data in bytes.
  • @param action - async specific action. If action is NOT oatpp::async::Action::TYPE_NONE, then caller MUST return this action on coroutine iteration.
  • @return - actual number of bytes written. 0 - to indicate end-of-file.

virtual v_io_size write(const void *data, v_buff_size count, async::Action& action) = 0

# WriteCallback::writeSimple

  1. Same as write((p_char8)data, std::strlen(data));.
    • @param data - data to write.
    • @return - actual number of bytes written. oatpp::v_io_size.
    v_io_size writeSimple(const char* data)
    
  2. Same as write(str->getData(), str->getSize());
    • @param str - data to write.
    • @return - actual number of bytes written. oatpp::v_io_size.
    v_io_size writeSimple(const oatpp::String& str)
    

# WriteCallback::writeCharSimple

Same as write(c, 1);.

  • @param c - one char to write.
  • @return - actual number of bytes written. oatpp::v_io_size.

v_io_size writeCharSimple(v_char8 c)

# OutputStream

Output Stream.

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

# Methods

Return Type Name Summary
[none] ~OutputStream Default virtual destructor.
void setOutputStreamIOMode Set stream I/O mode.
IOMode getOutputStreamIOMode Get stream I/O mode.
Context& getOutputStreamContext Get stream context.

# OutputStream::~OutputStream

Default virtual destructor.

virtual ~OutputStream() = default

# 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

# ReadCallback

Stream read callback.

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

# Methods

Return Type Name Summary
[none] ~ReadCallback Default virtual destructor.
v_io_size read Read operation callback.

# ReadCallback::~ReadCallback

Default virtual destructor.

virtual ~ReadCallback() = default

# ReadCallback::read

Read operation callback.

  • @param buffer - pointer to buffer.
  • @param count - size of the buffer in bytes.
  • @param action - async specific action. If action is NOT oatpp::async::Action::TYPE_NONE, then caller MUST return this action on coroutine iteration.
  • @return - actual number of bytes written to buffer. 0 - to indicate end-of-file.

virtual v_io_size read(void *buffer, v_buff_size count, async::Action& action) = 0

# InputStream

Input Stream.

namespace oatpp { namespace data { namespace stream { 
  class InputStream : public ReadCallback {}
}}}

# Methods

Return Type Name Summary
[none] ~InputStream Default virtual destructor.
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::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
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.
  6. Convert value to string and write to stream.
  7. Convert value to string and write to stream.
  8. Convert value to string and write to stream.
  9. Convert value to string and write to stream.
  10. Convert value to string and write to stream.
  11. Convert value to string and write to stream.

# ConsistentOutputStream::writeAsString

  1. Convert value to string and write to stream.
    v_io_size writeAsString(v_int8 value)
    
  2. Convert value to string and write to stream.
    v_io_size writeAsString(v_uint8 value)
    
  3. Convert value to string and write to stream.
    v_io_size writeAsString(v_int16 value)
    
  4. Convert value to string and write to stream.
    v_io_size writeAsString(v_uint16 value)
    
  5. Convert value to string and write to stream.
    v_io_size writeAsString(v_int32 value)
    
  6. Convert value to string and write to stream.
    v_io_size writeAsString(v_uint32 value)
    
  7. Convert value to string and write to stream.
    v_io_size writeAsString(v_int64 value)
    
  8. Convert value to string and write to stream.
    v_io_size writeAsString(v_uint64 value)
    
  9. Convert value to string and write to stream.
    v_io_size writeAsString(v_float32 value)
    
  10. Convert value to string and write to stream.
v_io_size writeAsString(v_float64 value)
  1. Convert value to string and write to stream.
v_io_size writeAsString(bool value)

# 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)

# StatelessDataTransferProcessor

Plain data transfer processor. Transfers data as is.

namespace oatpp { namespace data { namespace stream { 
  class StatelessDataTransferProcessor : public data::buffer::Processor {}
}}}

# transfer

Namespace: oatpp::data::stream

Transfer data from readCallback to writeCallback.

  • @param readCallback - ReadCallback.
  • @param writeCallback - WriteCallback.
  • @param transferSize - how much data should be read from the readCallback. 0 - to read until error.
  • @param buffer - pointer to buffer used to do the transfer by chunks.
  • @param bufferSize - size of the buffer.
  • @param processor - data processing to be applied during the transfer.
  • @return - the actual amout of bytes read from the readCallback.

v_io_size transfer(const base::ObjectHandle<ReadCallback>& readCallback,
                         const base::ObjectHandle<WriteCallback>& writeCallback,
                         v_io_size transferSize,
                         void* buffer,
                         v_buff_size bufferSize,
                         const base::ObjectHandle<data::buffer::Processor>& processor = &StatelessDataTransferProcessor::INSTANCE)

# transferAsync

Namespace: oatpp::data::stream

Transfer data from readCallback to writeCallback in Async manner.

async::CoroutineStarter transferAsync(const base::ObjectHandle<ReadCallback>& readCallback,
                                      const base::ObjectHandle<WriteCallback>& writeCallback,
                                      v_buff_size transferSize,
                                      const base::ObjectHandle<data::buffer::IOBuffer>& buffer,
                                      const base::ObjectHandle<data::buffer::Processor>& processor = &StatelessDataTransferProcessor::INSTANCE)