class ugcs::vsm::Io_stream

Overview

Abstract I/O stream interface. More…

#include <io_stream.h>

class Io_stream: public std::enable_shared_from_this< Io_stream >
{
public:
    // typedefs

    typedef std::shared_ptr<Io_stream> Ptr;
    typedef std::weak_ptr<Io_stream> Weak_ptr;
    typedef Reference_guard<Io_stream::Ptr> Ref;
    typedef int64_t Offset;
    typedef Callback_proxy<void, Io_result> Write_handler;
    typedef Callback_proxy<void, Io_buffer::Ptr, Io_result> Read_handler;
    typedef Callback_proxy<void> Close_handler;

    // enums

    enum State;
    enum Type;

    // fields

    static const Offset OFFSET_NONE;
    static const Offset OFFSET_END;

    // construction

    Io_stream(const Io_stream&);
    Io_stream(Type type);

    // methods

    template <typename... Args>
    static Ptr Create(Args&&... args);

    static const char* Io_result_as_char(const Io_result res);
    void Add_ref();
    void Release_ref();
    Operation_waiter Write(Io_buffer::Ptr buffer, Offset offset, Write_handler completion_handler = Make_dummy_callback<void, Io_result>(), Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create());
    Operation_waiter Write(Io_buffer::Ptr buffer, Write_handler completion_handler = Make_dummy_callback<void, Io_result>(), Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create());

    Operation_waiter Read(
        size_t max_to_read,
        size_t min_to_read,
        Offset offset,
        Read_handler completion_handler = Make_dummy_callback<void, Io_buffer::Ptr, Io_result>(),
        Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create()
        );

    Operation_waiter Read(
        size_t max_to_read,
        size_t min_to_read = 1,
        Read_handler completion_handler = Make_dummy_callback<void, Io_buffer::Ptr, Io_result>(),
        Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create()
        );

    Operation_waiter Close(Close_handler completion_handler = Make_dummy_callback<void>(), Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create());
    State Get_state() const;
    bool Is_closed() const;
    std::string Get_name() const;
    Type Get_type() const;
};

// direct descendants

class Stream;
class Stream;
class Stream;

Detailed Documentation

Abstract I/O stream interface.

All SDK objects which supports reading and/or writing raw bytes (like network connections, files, serial connections) implement this interface.

Typedefs

typedef std::shared_ptr<Io_stream> Ptr

Pointer type.

typedef std::weak_ptr<Io_stream> Weak_ptr

Pointer type.

typedef Reference_guard<Io_stream::Ptr> Ref

Guard object.

typedef int64_t Offset

Offset for read/write operations.

Used by streams which support offsets (like files).

typedef Callback_proxy<void, Io_result> Write_handler

Default prototype for write operation completion handler.

typedef Callback_proxy<void, Io_buffer::Ptr, Io_result> Read_handler

Default prototype for read operation completion handler.

typedef Callback_proxy<void> Close_handler

Default prototype for close operation completion handler.

Fields

static const Offset OFFSET_NONE

Offset special value which indicates that the offset value is not specified.

static const Offset OFFSET_END

Offset special value which indicates that the offset value corresponds to the stream end (e.g.

append operation).

Construction

Io_stream(const Io_stream&)

There is no sense in copying the stream.

Multiple users of the same stream should copy the shared pointer Ptr.

Io_stream(Type type)

Constructor.

Methods

template <typename... Args>
static Ptr Create(Args&&... args)

Create an instance.

static const char* Io_result_as_char(const Io_result res)

Convert Io_result value to character string.

void Add_ref()

Add reference to the stream.

void Release_ref()

Release reference for the stream.

The stream is closed when last reference is released.

Operation_waiter Write(Io_buffer::Ptr buffer, Offset offset, Write_handler completion_handler = Make_dummy_callback<void, Io_result>(), Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create())

Initiate write operation.

Parameters:

buffer	Buffer with data to write.
offset	Write offset in the stream if supported. Value OFFSET_NONE indicates that stream-maintained offset should be used.
completion_handler	Handler to invoke when the operation is completed.
comp_ctx	Completion context for the operation.
Invalid_param_exception	If handler is set without completion context or vice versa.

Returns:

Waiter object which can be used for synchronization and control.

Operation_waiter Write(Io_buffer::Ptr buffer, Write_handler completion_handler = Make_dummy_callback<void, Io_result>(), Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create())

Initiate write operation.

Parameters:

buffer	Buffer with data to write.
completion_handler	Handler to invoke when the operation is completed.
comp_ctx	Completion context for the operation.
Invalid_param_exception	If handler is set without completion context or vice versa.

Returns:

Waiter object which can be used for synchronization and control.

Operation_waiter Read(
    size_t max_to_read,
    size_t min_to_read,
    Offset offset,
    Read_handler completion_handler = Make_dummy_callback<void, Io_buffer::Ptr, Io_result>(),
    Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create()
    )

Initiate read operation.

Parameters:

max_to_read	Maximal number of bytes to read from the stream. Less bytes can be read in fact.
min_to_read	Minimal number of bytes to read from the stream. The operation is not completed until the specified minimal number of bytes is read.
offset	Read offset in the stream if supported. Value OFFSET_NONE indicates that stream-maintained offset should be used.
completion_handler	Handler to invoke when the operation is completed.
comp_ctx	Completion context for the operation.
Invalid_param_exception	If handler is set without completion context or vice versa.
Invalid_param_exception	If Max to read is less then Min to read.

Returns:

Waiter object which can be used for synchronization and control.

Operation_waiter Read(
    size_t max_to_read,
    size_t min_to_read = 1,
    Read_handler completion_handler = Make_dummy_callback<void, Io_buffer::Ptr, Io_result>(),
    Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create()
    )

Initiate read operation.

Parameters:

max_to_read	Maximal number of bytes to read from the stream. Less bytes can be read in fact. If max_to_read is set to 0, then it is determined automatically based on stream type: TCP: max_to_read = MAX_TCP_PAYLOAD_SIZE_TO_READ UDP: max_to_read = MIN_UDP_PAYLOAD_SIZE_TO_READ serial and other stream types: max_to_read = min_to_read
min_to_read	Minimal number of bytes to read from the stream. The operation is not completed until the specified minimal number of bytes is read.
completion_handler	Handler to invoke when the operation is completed.
comp_ctx	Completion context for the operation.
Invalid_param_exception	If handler is set without completion context or vice versa.
Invalid_param_exception	If Max to read is less then Min to read.

Returns:

Waiter object which can be used for synchronization and control.

Operation_waiter Close(Close_handler completion_handler = Make_dummy_callback<void>(), Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create())

Initiate stream close operation.

Parameters:

completion_handler	Completion handler for the operation.
comp_ctx	Completion context for the operation.
Invalid_param_exception	If handler is set without completion context or vice versa.

Returns:

Waiter object which can be used for synchronization and control.

State Get_state() const

Get current state of the stream.

bool Is_closed() const

Checks if stream is closed or not.

std::string Get_name() const

Get human readable stream name.

previous

class ugcs::vsm::Io_request

next

enum ugcs::vsm::Io_stream::State