SFXStreamReader

Class for accessing a stream for reading.

#include <SFXStreamReader.h.hpp>

class SFXStreamReader : public SFXInputStream;

SFMTYPEDEFCLASS(SFXStreamReader)

Inheritance diagram

Collaboration diagram

Description

The SFXStreamReader class is used to read data from the stream of the storage.

According to the type of data to be read, select one of the SFXBinaryStreamReader / SFXAnsiStringStreamReader / SFXWideStringStreamReader class, which inherits from SFXStreamReader.

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

Reference

Member

Constructor/Destructor
SFXStreamReader( `Void` ) Constructor of the SFXStreamReader 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` ) Read data from the storage into this stream.
`SFCError`	Fetch( `CallbackSPP` spp , `VoidPtr` reference ) Read data from the storage into this stream.
`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 stream.
`SFCError`	Read( `VoidPtr` buffer , `UInt32` size ) Read data from the 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.

SFXStreamReader::SFXStreamReader

Constructor of the SFXStreamReader class.

[ public, explicit ]
SFXStreamReader(Void);

SFXStreamReader::Attach

Attach the specified stream to this stream.

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

Description

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

Reference

SFXStreamReader::Detach

SFXStreamReader::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 SFXStreamReader::Fetch function.

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

Reference

SFXStreamReader::Release | SFXStreamReader::Fetch | SFXFile::Cancel | SFXTCPSocket::Cancel

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

Reference

SFXStreamReader::Attach

SFXStreamReader::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

SFXStreamReader::Fetch | Stream Buffer | Storage

SFXStreamReader::Fetch

Read data from the storage into this stream.

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

If a callback function is registed with this function, it will be called immediately when data has been read(fetched) from the storage into the stream buffer. Any fetch 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 read(fetched) from the storage immediately after this function is called.

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

Reference

SFXStreamReader::Read | SFXStreamReader::SetTrigger | Stream Buffer | Storage

SFXStreamReader::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

SFXStreamReader::LastIndexOf | Stream Buffer

SFXStreamReader::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]

If the size of data to be read is unknown, it is necessary to call this function to check the size of the readable data before calling the SFXStreamReader::Read function.

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

Reference

SFXStreamReader::Read | SFXStreamReader::Fetch | Stream Buffer | Storage

SFXStreamReader::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

SFXStreamReader::FirstIndexOf | Stream Buffer

SFXStreamReader::Read

Read data from the stream.

[ public, virtual ]
SFCError Read(
    SFXBufferPtr buffer   // buffer contains the reading data
);

[ public, virtual ]
SFCError Read(
    VoidPtr buffer   // pointer to the buffer contains the reading data
    UInt32 size      // size of the buffer contains the reading 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, the size of data specified on the buffer (or size) argument is bigger than the return value of the SFXStreamReader::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.

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

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

Reference

SFXStreamReader::GetReadableSize | SFXStreamReader::Fetch | Stream Buffer | Storage

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

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

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

Reference

SFXStreamReader::Cancel

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

Description

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

Reference

SFXStreamReader::SetTrigger | SFXStreamReader::Triggers | SFXStreamReader::Fetch

SFXStreamReader::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

SFXStreamReader::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 the 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 SFXStreamReader::Fetch function: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

The callback function registered by the SFXStreamReader::Fetch function will be booted up when the stream buffer is full of data read from the storage set to this stream or no more data is left to read.

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

SFXStreamReader::ResetTrigger | SFXStreamReader::Triggers | SFXStreamReader::Fetch

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

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

Reference

SFXStreamReader::SetTrigger | SFXStreamReader::ResetTrigger | SFXStreamReader::Fetch