SFXElasticStreamReader

Class for accessing the input stream of elastic buffer.

#include <SFXElasticStreamReader.h.hpp>

class SFXElasticStreamReader : public SFXInputStream;

SFMTYPEDEFCLASS(SFXElasticStreamReader)

Inheritance diagram

Collaboration diagram

Description

What is SFXElasticStreamReader?

The SFXElasticStreamReader class is used to read data from the input stream of elastic buffer such as file, TCP socket and so on.

The SFXBinaryStreamReader, SFXAnsiStringStreamReader, or SFXWideStringStreamReader class can get the elastic buffer stream by using the SFXElasticStreamReader class internally. Therefore, usually it is unnecessary to use the SFXElasticStreamReader class explicitly.

Attach function and Detach function

By using the SFXElasticStreamReader::Attach function, and delegating the control privilege of the SFXBinaryStreamReader, SFXAnsiStringStreamReader, or SFXWideStringStreamReader object that inherites from SFXInputStream to the SFXElasticStreamReader object, the input stream of elastic buffer can be available.

The SFXElasticStreamReader::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

SFXBinaryStreamReader | SFXAnsiStringStreamReader | SFXWideStringStreamReader | SFXElasticStreamWriter

Member

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

Public Functions
`Void`	Attach( `SFXInputStreamPtr` stream ) Delegate the control privilege of SFXInputStream object to the SFXElasticStreamReader object.
`Void`	Cancel( `Void` ) Call the Cancel function for Storage class. And also unregister callback functions.
`SFXInputStreamPtr`	Detach( `Void` ) Delegate the control privilege of SFXElasticStreamReader object to the SFXInputStream object.
`Bool`	Ends( `Void` ) Check whether the stream ends or not.
`SFCError`	Fetch( `Void` ) Fetch( `CallbackSPP` spp , `VoidPtr` reference ) Fetch for reading data newly.
`SInt32`	FirstIndexOf( `Byte` byte , `SInt32` index = SINT32_MINIMUM ) FirstIndexOf( `VoidConstPtr` buffer , `UInt32` size , `SInt32` index = SINT32_MINIMUM ) FirstIndexOf( `SFXBufferConstRef` buffer , `SInt32` index = SINT32_MINIMUM ) Get the first index of SFXElasticStreamReader object to match with the specified data, searching from the beginning.
`UInt32`	GetReadableSize( `Void` ) Get the size of readable data.
`SInt32`	LastIndexOf( `Byte` byte , `SInt32` index = SINT32_MAXIMUM ) LastIndexOf( `VoidConstPtr` buffer , `UInt32` size , `SInt32` index = SINT32_MAXIMUM ) LastIndexOf( `SFXBufferConstRef` buffer , `SInt32` index = SINT32_MAXIMUM ) Get the last index of SFXElasticStreamReader object to match with the specified data, searching from the end.
`SFCError`	Read( `SFXBufferPtr` buffer ) Read( `VoidPtr` buffer , `UInt32` size ) Read data from the input stream.
`Void`	Release( `Void` ) Release the stream.
`SFCError`	ResetTrigger( `Void` ) Reset the trigger when the callback function will be called.
`SFCError`	Seek( `UInt32` size ) Move the read pointer foraward.
`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.

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

SFXElasticStreamReader::SFXElasticStreamReader

Constructor of SFXElasticStreamReader class.

[ public, explicit ]
SFXElasticStreamReader(Void);

SFXElasticStreamReader::~SFXElasticStreamReader

Destructor of SFXElasticStreamReader class.

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

SFXElasticStreamReader::Attach

Delegate the control privilege of SFXInputStream object to the SFXElasticStreamReader object.

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

Description

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

Reference

SFXElasticStreamReader::Detach

SFXElasticStreamReader::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 the SFXElasticStreamReader::Fetch function are unregistered.

Reference

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

SFXElasticStreamReader::Detach

Delegate the control privilege of SFXElasticStreamReader object to the SFXInputStream object.

[ public ]
SFXInputStreamPtr Detach(Void);

Reference

SFXElasticStreamReader::Attach

SFXElasticStreamReader::Ends

Check whether the stream ends or not.

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

Return value

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

SFXElasticStreamReader::Fetch

Fetch for reading data newly.

[ public, virtual ]
SFCError Fetch(Void);

[ public, virtual ]
SFCError Fetch(
    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 SFXElasticStreamReader::Fetch 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 SFXElasticStreamReader::Fetch functions: one is with the registration of callback function, and the other is without it. Which type of SFXElasticStreamReader::Fetch 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 SFXElasticStreamReader::Fetch function without the registration of callback function, data is read into the internal buffer immediately after this function is called.

Reference

SFXElasticStreamReader::SetTrigger

SFXElasticStreamReader::FirstIndexOf

Get the first index of SFXElasticStreamReader object to match with the specified data, searching from the beginning.

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

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

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

Return value

Success : The first index where found.
If failed : -1

Description

To search from other than the beginning, specify the starting index to match with. (The origin index is 0.)

Reference

SFXElasticStreamReader::LastIndexOf

SFXElasticStreamReader::GetReadableSize

Get the size of readable data.

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

Description

It is necessary to check the size of readable data by the SFXElasticStreamReader::GetReadableSize function before calling the SFXElasticStreamReader::Read function.

Reference

SFXElasticStreamReader::Read

SFXElasticStreamReader::LastIndexOf

Get the last index of SFXElasticStreamReader object to match with the specified data, searching from the end.

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

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

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

Return value

Success : The last index where found.
If failed : -1

Description

To search from other than the end, specify the starting index to match with. (The origin index is 0.)

Reference

SFXElasticStreamReader::FirstIndexOf

SFXElasticStreamReader::Read

Read data from the input stream.

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

[ public, virtual ]
SFCError Read(
    VoidPtr buffer   // pointer to the buffer to read data
    UInt32 size      // size of the buffer to read 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

The size of readable data can be gotten by calling the SFXElasticStreamReader::GetReadableSize function.

When using the SFXBuffer class to receive data , set the size of data to be recieved by the SFXBuffer::SetSize function.

Reference

SFXElasticStreamReader::GetReadableSize

SFXElasticStreamReader::Release

Release the stream.

[ public ]
Void Release(Void);

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

Description

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

Reference

SFXElasticStreamReader::SetTrigger | SFXElasticStreamReader::Fetch

SFXElasticStreamReader::Seek

Move the read pointer foraward.

[ public, virtual ]
SFCError Seek(
    UInt32 size   // forward size
);

Return value

Success : SFERR_NO_ERROR
If stream is not set : SFERR_INVALID_STATE
If failed : SFERR_FAILED

SFXElasticStreamReader::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 SFXElasticStreamReader::SetTrigger function : true
Otherwise : false

Description

The SFXElasticStreamReader::Triggers function is used for the callback function registered by the SFXElasticStreamReader::Fetch function.

Reference

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

SFXElasticStreamReader::SetTrigger

Set the trigger when the callback function will be called.

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

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

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

Return value

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

Description

The callback function registered by the SFXElasticStreamReader::Fetch function is called when the stream buffer is full or the end of data is read.

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

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

Example

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

SetTrigger("\r\n", 2)

Reference

SFXElasticStreamReader::ResetTrigger | SFXElasticStreamReader::Fetch