SFXElasticStreamWriter

Class for a stream to write data into using the elastic buffer.

#include <SFXElasticStreamWriter.h.hpp>

class SFXElasticStreamWriter : public SFXOutputStream;

SFMTYPEDEFCLASS(SFXElasticStreamWriter)

Inheritance diagram

Collaboration diagram

Description

What is SFXElasticStreamWriter?

The SFXElasticStreamWriter class is internally used to write data into the stream with the elastic buffer.

If the SFXBinaryStreamWriter / SFXAnsiStringStreamWriter / SFXWideStringStreamWriter instance is gotten (or set) with the GetStreamWriter function of the storage class without specifying the size argument(i.e., buffer size), the stream buffer will be elastic.

At this time, internally, the SFXElasticStreamWriter stream will be attached to the SFXBinaryStreamWriter / SFXAnsiStringStreamWriter / SFXWideStringStreamWriter stream with the SFXElasticStreamWriter::Attach function. By this operation, data will be written into the stream using the elastic buffer.

The buffer will automatically expanded to the same size of data to be written.

	Note
	In general, you don't have to use the `SFXElasticStreamWriter` class explicitly since the processing of writing data onto the stream with the elastic buffer has already been implemented.

Reference

SFXBinaryStreamWriter | SFXAnsiStringStreamWriter | SFXWideStringStreamWriter | SFXElasticStreamReader

Member

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

Public Functions
`Void`	Attach( `SFXOutputStreamPtr` stream ) Attach the specified stream to this stream.
`Void`	Cancel( `Void` ) Cancel to write onto this stream.
`SFXOutputStreamPtr`	Detach( `Void` ) Detach the stream from this stream.
`SFCError`	Flush( `Void` ) Flush the written data.
`SFCError`	Flush( `CallbackSPP` spp , `VoidPtr` reference ) Flush the written data.
`UInt32`	GetWritableSize( `Void` ) Get the size of data that can be written into this stream. [in bytes]
`Void`	Release( `Void` ) Release this stream.
`SFCError`	ResetTrigger( `Void` ) Reset the trigger condition that the callback function will be booted up.
`SFCError`	SetTrigger( `UInt32` size ) Set the trigger condition that the callback function will be booted up.
`SFCError`	SetTrigger( `SFXBufferConstRef` buffer ) Set the trigger condition that the callback function will be booted up.
`SFCError`	SetTrigger( `VoidConstPtr` buffer , `UInt32` size ) Set the trigger condition that the callback function will be booted up.
`Bool`	Triggers( `Void` ) Check whether or not the callback function is booted up by the trigger condition.
`SFCError`	Write( `SFXBufferConstRef` buffer ) Write data to stream.
`SFCError`	Write( `VoidConstPtr` buffer , `UInt32` size ) Write data to stream.

Types
CallbackSPP (inherits from SFXStream) Type that represents the callback function.

SFXElasticStreamWriter::SFXElasticStreamWriter

Constructor of the SFXElasticStreamWriter class.

[ public, explicit ]
SFXElasticStreamWriter(Void);

SFXElasticStreamWriter::~SFXElasticStreamWriter

Destructor of the SFXElasticStreamWriter class.

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

SFXElasticStreamWriter::Attach

Attach the specified stream to this stream.

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

Description

The stream and the elastic buffer which have been set to this stream before this function is called will be destroyed.

Reference

SFXElasticStreamWriter::Detach

SFXElasticStreamWriter::Cancel

Cancel to write onto this stream.

[ public, virtual ]
Void Cancel(Void);

Description

This function cancels to write onto this stream.

Concretely, the following operations are performed internally.

Call the Cancel function of the storage class associated with this stream.

In case of the file storage, the SFXFile::Cancel function will be called. In case of the TCP socket storage, the SFXTCPSocket::Cancel function will be called.
Unregister the callback functions registered into this stream with the SFXElasticStreamWriter::Flush function.

	Note
	This function will be called internally in the `SFXElasticStreamWriter::Release` function.

Reference

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

SFXElasticStreamWriter::Detach

Detach the stream from this stream.

[ public ]
SFXOutputStreamPtr Detach(Void);

Return value

Stream which has been attached to this stream

Description

After this function is executed, no stream will be set to this stream. And the elastic buffer will be destroyed.

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 passed to the callback function
);

Return value

If succeeds: SFERR_NO_ERROR
If the stream is not set, or the callback function has already been registered by this function: SFERR_INVALID_STATE
If failed: SFERR_FAILED or the error value that defined in AEEError.h

Description

This function writes data in the buffer of this stream onto the storage set to this stream.

There are two types of this function: one registers a callback function and another does not. Which type is available depends on the kind of the storage.

For instance, only the type to registet a callback function is availavle for the stream set to the SFXTCPSocket storage. However, both types are available for the stream to the SFXFile storage.

In case of the type not to registet a callback function, data in the stream buffer will be written into the storage immediately after this function is called.

	Tip
	By calling the `SFXElasticStreamWriter::Write` function, data will be written into the stream buffer.

Reference

SFXElasticStreamWriter::Write | SFXElasticStreamWriter::SetTrigger | Stream Buffer | Storage

SFXElasticStreamWriter::GetWritableSize

Get the size of data that can be written into this stream. [in bytes]

[ public, const ]
UInt32 GetWritableSize(Void);

Return value

If the stream is set: 0xFFFFFFFF
Otherwise: 0

Description

This function gets the size of data that can be written into the stream buffer. [in bytes]

Since the SFXElasticStreamWriter class is the variable buffer stream, data can be written into the stream buffer by calling the SFXElasticStreamWriter::Write function as long as the physical memory allows.

If the stream is set with the GetStreamWriter of the storage class, 0xFFFFFFFF will be returned. Otherwise, 0 will be returned.

	Note
	Since there is memory limitation, the value less than 0xFFFFFFFF of memory will be available actually.

Reference

SFXElasticStreamWriter::Write | SFXElasticStreamWriter::Flush | Stream Buffer | Variable Buffer Stream | Storage

SFXElasticStreamWriter::Release

Release this stream.

[ public ]
Void Release(Void);

Description

This function cancels to write onto this stream and releases this stream.

Note

	Note
This function will be called in the destructor of this stream. Also, it cancels to write onto this stream by calling the `SFXElasticStreamWriter::Cancel` function.

This function will be called in the destructor of this stream.

Also, it cancels to write onto this stream by calling the SFXElasticStreamWriter::Cancel function.

Reference

SFXElasticStreamWriter::Cancel

SFXElasticStreamWriter::ResetTrigger

Reset the trigger condition that the callback function will be booted up.

[ public, virtual ]
SFCError ResetTrigger(Void);

Return value

If succeeds: SFERR_NO_ERROR
If the stream is not set, or a callback function has already been registered with the SFXElasticStreamWriter::Flush function: SFERR_INVALID_STATE

Description

This function resets the trigger condition set with the SFXElasticStreamWriter::SetTrigger function.

Reference

SFXElasticStreamWriter::SetTrigger | SFXElasticStreamWriter::Triggers | SFXElasticStreamWriter::Flush

SFXElasticStreamWriter::SetTrigger

Set the trigger condition that the callback function will be booted up.

[ public, virtual ]
SFCError SetTrigger(
    UInt32 size   // size of the data to write onto this stream
);

[ public, virtual ]
SFCError SetTrigger(
    SFXBufferConstRef buffer   // data to write onto this stream
);

[ public, virtual ]
SFCError SetTrigger(
    VoidConstPtr buffer   // data to write onto this stream
    UInt32 size           // size of the data to write onto this stream
);

Return value

If succeeds: SFERR_NO_ERROR
If the stream is not set, or a callback function has already been registered with the SFXElasticStreamWriter::Flush function: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

The callback function registered by the SFXElasticStreamWriter::Flush function will be booted up when data of the stream buffer is written into the storage set to this stream.

This function sets the trigger condition that the callback function will be booted up other than the above timing.

If only the size argument is specified, the callback function will be booted up every time the specified size of data is written into this stream.

If the buffer argument is specified, the callback function will be booted up every time the specified data is written into this stream.

Example

The code below is to boot up the callback function every time the line-feed character is written into the stream.

SetTrigger("\r\n", 2);

Reference

SFXElasticStreamWriter::ResetTrigger | SFXElasticStreamWriter::Triggers | SFXElasticStreamWriter::Flush

SFXElasticStreamWriter::Triggers

Check whether or not the callback function is booted up by the trigger condition.

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

Return value

If the callback function is booted up by the trigger condition: true
Otherwise: false

Description

This function checks whether or not the callback function is booted up by the trigger condition set with the SFXElasticStreamWriter::SetTrigger function.

This function is used in the callback function to register with 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

If succeeds: SFERR_NO_ERROR
If the stream is not set: SFERR_INVALID_STATE
If the buffer argument is null, the size argument is less than or equals 0, or, memory is insufficient: SFERR_FAILED

Description

This fucntion writes data specified in the buffer argument onto the buffer of this stream.

	Caution
	If the buffer argument is null, the size argument is less than or equals 0, or, memory is insufficient, SFERR_FAILED will be returned.

	Tip
	By calling the `SFXElasticStreamWriter::Flush` function, data in the stream buffer will be written into the storage set to the stream and the stream buffer will become empty.

Reference

SFXElasticStreamWriter::GetWritableSize | SFXElasticStreamWriter::Flush | Stream Buffer | Variable Buffer Stream | Storage