SFXElasticStreamWriter

Class for accessing the output stream of elastic buffer.

#include <SFXElasticStreamWriter.h.hpp>

class SFXElasticStreamWriter : public SFXOutputStream;

SFMTYPEDEFCLASS(SFXElasticStreamWriter)

Inheritance diagram

Collaboration diagram

Description

What is SFXElasticStreamWriter?

The SFXElasticStreamWriter class is used to write data onto the output stream of elastic buffer such as file, TCP socket and so on.

The SFXBinaryStreamWriter, SFXAnsiStringStreamWriter, or SFXWideStringStreamWriter class can get the elastic buffer stream by using the SFXElasticStreamWriter class internally. Therefore, usually it is unnecessary to use the SFXElasticStreamWriter class explicitly.

Attach function and Detach function

By using the SFXElasticStreamWriter::Attach function, and delegating the control privilege of the SFXBinaryStreamWriter, SFXAnsiStringStreamWriter, or SFXWideStringStreamWriter object that inherites from SFXOutputStream to the SFXElasticStreamWriter object, the output stream of elastic buffer can be available.

The SFXElasticStreamWriter::Detach function has reverse functionality.

What is delegation?: In object oriented programming, delegation means that an object have another deputy object behave like itself.

Reference

SFXBinaryStreamWriter | SFXAnsiStringStreamWriter | SFXWideStringStreamWriter | SFXElasticStreamReader

Member

Constructor/Destructor
SFXElasticStreamWriter( `Void` ) Constructor of SFXElasticStreamWriter class.
~SFXElasticStreamWriter( `Void` ) Destructor of SFXElasticStreamWriter class.

Public Functions
`Void`	Attach( `SFXOutputStreamPtr` stream ) Delegate the control privilege of SFXOutputStream object to the SFXStreamWriter object.
`Void`	Cancel( `Void` ) Call the Cancel function for Storage class. And also unregister callback functions.
`SFXOutputStreamPtr`	Detach( `Void` ) Delegate the control privilege of SFXElasticStreamWriter object to the SFXOutputStream object.
`SFCError`	Flush( `Void` ) Flush( `CallbackSPP` spp , `VoidPtr` reference ) Flush the written data.
`UInt32`	GetWritableSize( `Void` ) Get the size of writable data.
`Void`	Release( `Void` ) Release the stream.
`SFCError`	ResetTrigger( `Void` ) Reset the trigger when the callback function will be called.
`SFCError`	SetTrigger( `UInt32` size ) SetTrigger( `VoidConstPtr` buffer , `UInt32` size ) SetTrigger( `SFXBufferConstRef` buffer ) Set the trigger when the callback function will be called.
`Bool`	Triggers( `Void` ) Check whether the callback function is called by trigger or not.
`SFCError`	Write( `SFXBufferConstRef` buffer ) Write( `VoidConstPtr` buffer , `UInt32` size ) Write data to stream.

Types
CallbackSPP (inherits from SFXStream) Constant that represents Callback function.

SFXElasticStreamWriter::SFXElasticStreamWriter

Constructor of SFXElasticStreamWriter class.

[ public, explicit ]
SFXElasticStreamWriter(Void);

SFXElasticStreamWriter::~SFXElasticStreamWriter

Destructor of SFXElasticStreamWriter class.

[ public, virtual ]
virtual ~SFXElasticStreamWriter(Void);

SFXElasticStreamWriter::Attach

Delegate the control privilege of SFXOutputStream object to the SFXStreamWriter object.

[ public ]
Void Attach(
    SFXOutputStreamPtr stream   // stream to set
);

Description

The contents of the SFXElasticStreamWriter object before calling the SFXElasticStreamWriter::Attach function will be destroyed.

Reference

SFXElasticStreamWriter::Detach

SFXElasticStreamWriter::Cancel

Call the Cancel function for Storage class. And also unregister callback functions.

[ public, virtual ]
Void Cancel(Void);

Description

Call the SFXFile::Cancel function for file, the SFXTCPSocket::Cancel function for TCP socket, etc.

And also the callback functions registered by SFXElasticStreamWriter::Flush function are unregistered.

Reference

SFXElasticStreamWriter::Flush | SFXFile::Cancel | SFXTCPSocket::Cancel

SFXElasticStreamWriter::Detach

Delegate the control privilege of SFXElasticStreamWriter object to the SFXOutputStream object.

[ public ]
SFXOutputStreamPtr Detach(Void);

Reference

SFXElasticStreamWriter::Attach

SFXElasticStreamWriter::Flush

Flush the written data.

[ public, virtual ]
SFCError Flush(Void);

[ public, virtual ]
SFCError Flush(
    CallbackSPP spp     // callback function
    VoidPtr reference   // data sent to callback function
);

Return value

Success : SFERR_NO_ERROR
If argument is invalid : SFERR_INVALID_PARAM
If stream is not set, or the SFXElasticStreamWriter::Flush function is under processing : SFERR_INVALID_STATE
If failed : SFERR_FAILED
Otherwise : The Error value that defined in AEEError.h

Description

There are two types of SFXElasticStreamWriter::Flush functions: one is with the registration of callback function, and the other is without it. Which type of SFXElasticStreamWriter::Flush function is available depends upon the storage of stream.

　　　 For example, only the type with the registration of callback function is availavle for TCP stream. However file stream can use both types.

In case of the SFXElasticStreamWriter::Flush function without the registration of callback function, data is flushed immediately after this function is called.

SFXElasticStreamWriter::GetWritableSize

Get the size of writable data.

[ public, const ]
UInt32 GetWritableSize(Void);

Reference

SFXElasticStreamWriter::Flush

SFXElasticStreamWriter::Release

Release the stream.

[ public ]
Void Release(Void);

SFXElasticStreamWriter::ResetTrigger

Reset the trigger when the callback function will be called.

[ public, virtual ]
SFCError ResetTrigger(Void);

Return value

Success : SFERR_NO_ERROR
If the stream is not set, or the SFXElasticStreamWriter::Flush function is under processing : SFERR_INVALID_STATE

Description

Reset the trigger set with the SFXElasticStreamWriter::SetTrigger function.

Reference

SFXElasticStreamWriter::SetTrigger | SFXElasticStreamWriter::Flush

SFXElasticStreamWriter::SetTrigger

Set the trigger when the callback function will be called.

[ public, virtual ]
SFCError SetTrigger(
    UInt32 size   // data size to be written through output stream
);

[ public, virtual ]
SFCError SetTrigger(
    SFXBufferConstRef buffer   // SFXBuffer object to be written through output stream
);

[ public, virtual ]
SFCError SetTrigger(
    VoidConstPtr buffer   // data to be written through output stream
    UInt32 size           // size of data to be written through output stream
);

Return value

Success : SFERR_NO_ERROR
If the stream is not set, or the SFXElasticStreamWriter::Flush function is under processing : SFERR_INVALID_STATE
If insufficient memory : SFERR_NO_MEMORY

Description

The callback function registered by the SFXElasticStreamWriter::Flush function is called when the stream buffer is full or the end of data is written.

When the "size" parameter of SFXElasticStreamWriter::SetTrigger function is specified, callback function is called every time the "size" data is written.

When the "buffer" parameter of SFXElasticStreamWriter::SetTrigger function is specified, callback function is called every time the data same with "buffer" is written.

Example

Call the callback on every time the line-feed character is read.

SetTrigger("\r\n", 2)

Reference

SFXElasticStreamWriter::ResetTrigger | SFXElasticStreamWriter::Flush

SFXElasticStreamWriter::Triggers

Check whether the callback function is called by trigger or not.

[ public, virtual, const ]
Bool Triggers(Void);

Return value

If called by trigger set with the SFXElasticStreamWriter::SetTrigger : true
Otherwise : false

Description

The SFXElasticStreamWriter::Triggers function is used for the callback function registered by the SFXElasticStreamWriter::Flush function.

Reference

SFXElasticStreamWriter::SetTrigger | SFXElasticStreamWriter::ResetTrigger | SFXElasticStreamWriter::Flush

SFXElasticStreamWriter::Write

Write data to stream.

[ public, virtual ]
SFCError Write(
    SFXBufferConstRef buffer   // writing data
);

[ public, virtual ]
SFCError Write(
    VoidConstPtr buffer   // writing data
    UInt32 size           // size of writing data
);

Return value

Success : SFERR_NO_ERROR
If stream is not set : SFERR_INVALID_STATE
If argument is invalid : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Description

When the size of data to be written is larger than the return value of SFXElasticStreamWriter::GetWritableSize function, it is necessary to call the SFXElasticStreamWriter::Flush function.

Reference

SFXElasticStreamWriter::GetWritableSize | SFXElasticStreamWriter::Flush