SFXStreamWriter

Class for accessing a stream for writing.

#include <SFXStreamWriter.h.hpp>

class SFXStreamWriter : public SFXOutputStream;

SFMTYPEDEFCLASS(SFXStreamWriter)

Inheritance diagram

Collaboration diagram

Description

The SFXStreamWriter class is used to write data into the stream of the storage.

According to the type of data to write, select one of the SFXBinaryStreamWriter / SFXAnsiStringStreamWriter / SFXWideStringStreamWriter class, which inherits from SFXStreamWriter.

In case of the variable buffer stream, the SFXElasticStreamWriter class is internally used. But you don't have to be aware of this class.

Reference

Member

Constructor/Destructor
SFXStreamWriter( `Void` ) Constructor of the SFXStreamWriter 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` ) Write data in the stream buffer into the storage.
`SFCError`	Flush( `CallbackSPP` spp , `VoidPtr` reference ) Write data in the stream buffer into the storage.
`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 onto the stream.
`SFCError`	Write( `VoidConstPtr` buffer , `UInt32` size ) Write data onto the stream.

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

SFXStreamWriter::SFXStreamWriter

Constructor of the SFXStreamWriter class.

[ public, explicit ]
SFXStreamWriter(Void);

SFXStreamWriter::Attach

Attach the specified stream to this stream.

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

Description

The stream which has been set to this stream before this function is called will be destroyed.

Reference

SFXStreamWriter::Detach

SFXStreamWriter::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 SFXStreamWriter::Flush function.

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

Reference

SFXStreamWriter::Release | SFXStreamWriter::Flush | SFXFile::Cancel | SFXTCPSocket::Cancel

SFXStreamWriter::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.

Reference

SFXStreamWriter::Attach

SFXStreamWriter::Flush

Write data in the stream buffer into the storage.

[ 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 into 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.

If a callback function is registed with this function, it will be called immediately when data has been written(flushed) from the stream buffer into the storage. Any flush error will be passed to the 1st argument of the specified callback function. If this function returns the value other than SFERR_NO_ERROR, the specified callback function will not be called.

If no callback function is registed, data in the stream buffer will be written(flushed) into the storage immediately after this function is called.

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

Reference

SFXStreamWriter::Write | SFXStreamWriter::SetTrigger | Stream Buffer | Storage

SFXStreamWriter::GetWritableSize

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

[ public, virtual, const ]
UInt32 GetWritableSize(Void);

Return value

Size of data that can be written into the stream buffer. [in bytes]

Description

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

If the size of data to be written is larger than the return value of this function, it is necessary to divide data into chunks that can be written into the stream buffer and call the SFXStreamWriter::Write and SFXStreamWriter::Flush functions for each chunk in multiple times.

	Note
	The physical size of the stream buffer is specified in the size argument of the GetStreamWriter function of the storage class.

Reference

SFXStreamWriter::Write | SFXStreamWriter::Flush | Stream Buffer | Storage

SFXStreamWriter::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 `SFXStreamWriter::Cancel` function.

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

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

Reference

SFXStreamWriter::Cancel

SFXStreamWriter::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 SFXStreamWriter::Flush function: SFERR_INVALID_STATE

Description

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

Reference

SFXStreamWriter::SetTrigger | SFXStreamWriter::Triggers | SFXStreamWriter::Flush

SFXStreamWriter::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 SFXStreamWriter::Flush function: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

The callback function registered by the SFXStreamWriter::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

SFXStreamWriter::ResetTrigger | SFXStreamWriter::Triggers | SFXStreamWriter::Flush

SFXStreamWriter::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 SFXStreamWriter::SetTrigger function.

This function is used in the callback function to register with the SFXStreamWriter::Flush function.

Reference

SFXStreamWriter::SetTrigger | SFXStreamWriter::ResetTrigger | SFXStreamWriter::Flush

SFXStreamWriter::Write

Write data onto the 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 stream buffer contains some of the memory region specified in the buffer argument: SFERR_INVALID_PARAM
If the buffer argument is null, the size argument is less than or equals 0, or, the size of data specified on the buffer (or size) argument is bigger than the return value of the SFXStreamWriter::GetWritableSize function: SFERR_FAILED

Description

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

	Note
	The physical size of the stream buffer is specified in the size argument of the GetStreamWriter function of the storage class.

Caution

	Caution
If the size of data specified in the buffer (or size) argument bigger than `SFXStreamWriter::GetWritableSize` the return value of the `SFXStreamWriter::GetWritableSize` function, SFERR_FAILED will be returned. If the stream buffer contains some of the memory region specified in the buffer argument, SFERR_INVALID_PARAM will be returned.

If the size of data specified in the buffer (or size) argument bigger than SFXStreamWriter::GetWritableSize the return value of the SFXStreamWriter::GetWritableSize function, SFERR_FAILED will be returned.

If the stream buffer contains some of the memory region specified in the buffer argument, SFERR_INVALID_PARAM will be returned.

	Tip
	By calling the `SFXStreamWriter::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

SFXStreamWriter::GetWritableSize | SFXStreamWriter::Flush | Stream Buffer | Storage