SFXElasticStreamReader

Class for a stream to read data from using the elastic buffer.

#include <SFXElasticStreamReader.h.hpp>

class SFXElasticStreamReader : public SFXInputStream;

SFMTYPEDEFCLASS(SFXElasticStreamReader)

Inheritance diagram

Collaboration diagram

Description

What is SFXElasticStreamReader?

The SFXElasticStreamReader class is internally used to read data from the stream with the elastic buffer.

If the SFXBinaryStreamReader / SFXAnsiStringStreamReader / SFXWideStringStreamReader instance is gotten (or set) with the GetStreamReader 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 SFXElasticStreamReader stream will be attached to the SFXBinaryStreamReader / SFXAnsiStringStreamReader / SFXWideStringStreamReader stream with the SFXElasticStreamReader::Attach function. By this operation, data will be read from the stream using the elastic buffer.

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

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

Reference

SFXBinaryStreamReader | SFXAnsiStringStreamReader | SFXWideStringStreamReader | SFXElasticStreamWriter

Member

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

Public Functions
`Void`	Attach( `SFXInputStreamPtr` stream ) Attach the specified stream to this stream.
`Void`	Cancel( `Void` ) Cancel to read from this stream.
`SFXInputStreamPtr`	Detach( `Void` ) Detach the stream from this stream.
`Bool`	Ends( `Void` ) Check whether or not the read pointer reaches the end of this stream.
`SFCError`	Fetch( `Void` ) Fetch for reading data newly.
`SFCError`	Fetch( `CallbackSPP` spp , `VoidPtr` reference ) Fetch for reading data newly.
`SInt32`	FirstIndexOf( `Byte` byte , `SInt32` index = SINT32_MINIMUM ) Get the first index to match the specified data, searching from the head of the stream buffer.
`SInt32`	FirstIndexOf( `SFXBufferConstRef` buffer , `SInt32` index = SINT32_MINIMUM ) Get the first index to match the specified data, searching from the head of the stream buffer.
`SInt32`	FirstIndexOf( `VoidConstPtr` buffer , `UInt32` size , `SInt32` index = SINT32_MINIMUM ) Get the first index to match the specified data, searching from the head of the stream buffer.
`UInt32`	GetReadableSize( `Void` ) Get the size of data that can be read from this stream. [in bytes]
`SInt32`	LastIndexOf( `Byte` byte , `SInt32` index = SINT32_MAXIMUM ) Get the last index to match the specified data, searching from the tail of the stream buffer.
`SInt32`	LastIndexOf( `SFXBufferConstRef` buffer , `SInt32` index = SINT32_MAXIMUM ) Get the last index to match the specified data, searching from the tail of the stream buffer.
`SInt32`	LastIndexOf( `VoidConstPtr` buffer , `UInt32` size , `SInt32` index = SINT32_MAXIMUM ) Get the last index to match the specified data, searching from the tail of the stream buffer.
`SFCError`	Read( `SFXBufferPtr` buffer ) Read data from the input stream.
`SFCError`	Read( `VoidPtr` buffer , `UInt32` size ) Read data from the input stream.
`Void`	Release( `Void` ) Release this stream.
`SFCError`	ResetTrigger( `Void` ) Reset the trigger condition that the callback function will be booted up.
`SFCError`	Seek( `UInt32` size ) Move the read pointer forward.
`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.

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

SFXElasticStreamReader::SFXElasticStreamReader

Constructor of the SFXElasticStreamReader class.

[ public, explicit ]
SFXElasticStreamReader(Void);

SFXElasticStreamReader::~SFXElasticStreamReader

Destructor of the SFXElasticStreamReader class.

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

SFXElasticStreamReader::Attach

Attach the specified stream to this stream.

[ public ]
Void Attach(
    SFXInputStreamPtr 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

SFXElasticStreamReader::Detach

SFXElasticStreamReader::Cancel

Cancel to read from this stream.

[ public, virtual ]
Void Cancel(Void);

Description

This function cancels to read from 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 SFXElasticStreamReader::Fetch function.

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

Reference

SFXElasticStreamReader::Fetch | SFXFile::Cancel | SFXTCPSocket::Cancel

SFXElasticStreamReader::Detach

Detach the stream from this stream.

[ public ]
SFXInputStreamPtr 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

SFXElasticStreamReader::Attach

SFXElasticStreamReader::Ends

Check whether or not the read pointer reaches the end of this stream.

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

Return value

If the read pointer reaches the end of this stream, and there is no data to read: true
Otherwise: false

Description

This function checks whether or not the read pointer reaches the end of this stream.

If the read pointer reaches the end of this stream buffer and no more data can be read from the storage set to this stream, "true" will be returned. Otherwise "false" will be returned.

Reference

SFXElasticStreamReader::Fetch | Stream Buffer | Storage

SFXElasticStreamReader::Fetch

Fetch for reading data newly.

[ public, virtual ]
SFCError Fetch(Void);

[ public, virtual ]
SFCError Fetch(
    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 reads data from the storage set to this stream into the buffer of 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 read from the storage immediately after this function is called.

	Tip
	By calling the `SFXElasticStreamReader::Read` function, data will be read from the stream buffer.

Reference

SFXElasticStreamReader::Read | SFXElasticStreamReader::SetTrigger | Stream Buffer | Storage

SFXElasticStreamReader::FirstIndexOf

Get the first index to match the specified data, searching from the head of the stream buffer.

[ public, virtual, const ]
SInt32 FirstIndexOf(
    Byte byte                       // data to match
    SInt32 index = SINT32_MINIMUM   // beginning index to search from
);

[ public, virtual, const ]
SInt32 FirstIndexOf(
    SFXBufferConstRef buffer        // data to match
    SInt32 index = SINT32_MINIMUM   // beginning index to search from
);

[ public, virtual, const ]
SInt32 FirstIndexOf(
    VoidConstPtr buffer             // data to match
    UInt32 size                     // size of the data to match
    SInt32 index = SINT32_MINIMUM   // beginning index to search from
);

Return value

If succeeds: The first index of the stream buffer where the specified data is found.
If failed: -1

Description

This fucntion gets the first index to match the specified data, searching from the head of the stream buffer.

By specifying the beginning index, you can search from the position other than the head.

	Note
	The index of the head of the stream buffer is 0.

Reference

SFXElasticStreamReader::LastIndexOf | Stream Buffer

SFXElasticStreamReader::GetReadableSize

Get the size of data that can be read from this stream. [in bytes]

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

Return value

Size of data that can be read from the stream buffer [in bytes]

Description

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

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

Reference

SFXElasticStreamReader::Read | SFXElasticStreamReader::Fetch | Stream Buffer | Variable Buffer Stream | Storage

SFXElasticStreamReader::LastIndexOf

Get the last index to match the specified data, searching from the tail of the stream buffer.

[ public, virtual, const ]
SInt32 LastIndexOf(
    Byte byte                       // data to match
    SInt32 index = SINT32_MAXIMUM   // beginning index to search from
);

[ public, virtual, const ]
SInt32 LastIndexOf(
    SFXBufferConstRef buffer        // data to match
    SInt32 index = SINT32_MAXIMUM   // beginning index to search from
);

[ public, virtual, const ]
SInt32 LastIndexOf(
    VoidConstPtr buffer             // data to match
    UInt32 size                     // size of the data to match
    SInt32 index = SINT32_MAXIMUM   // beginning index to search from
);

Return value

If succeeds: The last index of the stream buffer where the specified data is found.
If failed: -1

Description

This fucntion gets the last index to match the specified data, searching from the tail of the stream buffer.

By specifying the beginning index, you can search from the position other than the tail.

	Note
	The index of the head of the stream buffer is 0.

Reference

SFXElasticStreamReader::FirstIndexOf | Stream Buffer

SFXElasticStreamReader::Read

Read data from the input stream.

[ public, virtual ]
SFCError Read(
    SFXBufferPtr buffer   // buffer to read data into
);

[ public, virtual ]
SFCError Read(
    VoidPtr buffer   // pointer to the buffer to read data into
    UInt32 size      // size of the buffer to read data into
);

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 SFXElasticStreamReader::GetReadableSize function: SFERR_FAILED

Description

This fucntion reads data from the buffer of this stream into the variable specified in the argument.

The size of data that can be read is gotten with the SFXElasticStreamReader::GetReadableSize function.

Caution

	Caution
When using the buffer argument of the `SFXBuffer` type, it is necessary to set the size of data that will be read from this stream with the `SFXBuffer::SetSize` function. 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 `SFXElasticStreamReader::GetReadableSize` 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.

When using the buffer argument of the SFXBuffer type, it is necessary to set the size of data that will be read from this stream with the SFXBuffer::SetSize function.

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 SFXElasticStreamReader::GetReadableSize 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 `SFXElasticStreamReader::Fetch` function, data will be read from the storage set to the stream into the stream buffer.

Reference

SFXElasticStreamReader::GetReadableSize | SFXElasticStreamReader::Fetch | Stream Buffer | Variable Buffer Stream | Storage

SFXElasticStreamReader::Release

Release this stream.

[ public ]
Void Release(Void);

Description

This function cancels to read from this stream and releases this stream.

Note

	Note
This function will be called in the destructor of this stream. Also, it cancels to read from this stream by calling the `SFXElasticStreamReader::Cancel` function.

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

Also, it cancels to read from this stream by calling the SFXElasticStreamReader::Cancel function.

Reference

SFXElasticStreamReader::Cancel

SFXElasticStreamReader::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 SFXElasticStreamReader::Fetch function: SFERR_INVALID_STATE

Description

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

Reference

SFXElasticStreamReader::SetTrigger | SFXElasticStreamReader::Triggers | SFXElasticStreamReader::Fetch

SFXElasticStreamReader::Seek

Move the read pointer forward.

[ public, virtual ]
SFCError Seek(
    UInt32 size   // size to move the read pointer forward
);

Return value

If succeeds: SFERR_NO_ERROR
If the stream is not set: SFERR_INVALID_STATE
If the read pointer goes beyond the tail of stream buffer: SFERR_FAILED

Description

This function moves forward the read pointer which is for reading data from the stream buffer.

Reference

Stream Buffer

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

This function is used in the callback function to register with the SFXElasticStreamReader::Fetch function.

Reference

SFXElasticStreamReader::SetTrigger | SFXElasticStreamReader::ResetTrigger | SFXElasticStreamReader::Fetch

SFXElasticStreamReader::SetTrigger

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

[ public, virtual ]
SFCError SetTrigger(
    UInt32 size   // size of the data to be read from this stream
);

[ public, virtual ]
SFCError SetTrigger(
    SFXBufferConstRef buffer   // data to be read from this stream
);

[ public, virtual ]
SFCError SetTrigger(
    VoidConstPtr buffer   // data to be read from this stream
    UInt32 size           // size of data to be read from 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 SFXElasticStreamReader::Fetch function: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

The callback function registered by the SFXElasticStreamReader::Fetch function will be booted up when no more data is left to read from 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 size of data specified in the argument is read from this stream.

If the buffer argument is specified, the callback function will be booted up every time the data specified in the arguments is read from this stream.

Example

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

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

Reference

SFXElasticStreamReader::ResetTrigger | SFXElasticStreamReader::Triggers | SFXElasticStreamReader::Fetch