SFXSource

Storage class for reading data from the ISource interface(SFBSource storage).

#include <SFXSource.h.hpp>

class SFXSource : public SFXStorage;

SFMTYPEDEFCLASS(SFXSource)

Inherince diagram

Collaboration diagram

Description

The SFXSource class is used to read data through the BREW API ISource interface.

	Limitation
	Data can be read from the `SFXSource` storage, but it cannot be written into this storage. The function to move the read pointer is not supported.

How to use the SFXSource class

Create the SFBSource instance to read data through the BREW API ISource interface.
Set it to the SFXSource instance, i.e., the SFXSource storage, with the SFXSource::Open function.
Get the input stream with the SFXSource::GetStreamReader function.
Read data from the SFXSource storage using the input stream.
* If the input stream is not used, data can be read with the SFXSource::Read function.
Close the SFXSource storage with the SFXSource::Close function.

Example 844. How to use the SFXSource class

Void MyClass::UseSFXSource(Void)
{
    SFXSource source; 
    static ACharConst data[] = "test data"; // read data
    SFXAnsiString string;                 // variable to read data from the SFXSource storage
    SFXBinaryStreamReader reader;         // input stream for reading data from the SFXSource storage
    SFBSourceUtilSmp util;
    SFBSourceSmp bs;

    // create from SFBSource storage from memory block
    util = SFBSourceUtil::NewInstance();
    util->SourceFromMemory(data, sizeof(data), null, null, &bs);

    // set the SFXSource storage
    if (source.Open(bs) == SFERR_NO_ERROR) {

        // get input stream for reading data from the SFXSource storage
        if (source.GetStreamReader(1024, &reader) == SFERR_NO_ERROR) {

            reader.Fetch();  // read data from the SFXSource storage into input stream buffer actually
            reader >> string; // read data from input stream buffer to the string variable

            // display the string variable on BREW Output Window
            TRACE("size = %d", string.GetLength());   // display string length: "size = 9"
            TRACE("read = %s", string.GetCString());  // display string: "read = test data"  

            // release input stream for reading data from the SFXSource storage
            reader.Release();  
        }

        // close the SFXSource storage
        source.Close(); 
    }
    return;
}

Reference

Member

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

Public Functions
`Void`	Cancel( `Void` ) Cancel the callback.
`Void`	Close( `Void` ) Close this source.
`SFBSourceSmpConstRef`	GetSFBSource( `Void` ) Get the SFBSource instance managed internally by this SFXSource storage.
`SFCError`	GetStreamReader( `UInt32` size , `SFXStreamReaderPtr` result ) Get the input stream for reading data from the ISource interface(the SFBSource storage).
`SFCError`	GetStreamReader( `SFXStreamReaderPtr` result ) Get the input stream for reading data from the ISource interface(the SFBSource storage).
`SFCError`	GetStreamWriter( `UInt32` size , `SFXStreamWriterPtr` result ) [This function cannot be used now.]
`SFCError`	GetStreamWriter( `SFXStreamWriterPtr` result ) [This function cannot be used now.]
`SFCError`	Open( `SFXStorageConstRef` storage ) Set the specified stream, storage or source to this SFXSource storage.
`SFCError`	Open( `SFBSourceSmpConstRef` source ) Set the specified stream, storage or source to this SFXSource storage.
`SFCError`	Open( `SFBAStreamSmpConstRef` stream ) Set the specified stream, storage or source to this SFXSource storage.
`SFCError`	Read( `VoidPtr` buffer , `UInt32Ptr` size ) Read data from this source without input stream.
`SFCError`	ScheduleRead( `CallbackSPP` spp , `VoidPtr` reference ) Schedule to read data from this source without input stream.
`SFCError`	ScheduleWrite( `CallbackSPP` spp , `VoidPtr` reference ) [This function cannot be used now.]
`SFCError`	Write( `VoidConstPtr` buffer , `UInt32Ptr` size ) [This function cannot be used now.]
`SFCError`	AsSFBAStream( `SFBAStreamSmpPtr` result ) (inherits from SFXStorage) Convert the storage instance internally managed by this storage into the SFBAStream instance.
`SFCError`	AsSFBSource( `SFBSourceSmpPtr` result ) (inherits from SFXStorage) Convert the storage instance internally managed by this storage into the SFBSource instance.

Types
CallbackSPP (inherits from SFXStorage) Type of the callback function for the Storage class.

SFXSource::SFXSource

Constructor of the SFXSource class.

[ public, explicit ]
SFXSource(Void);

Description

This constructor does nothing.

SFXSource::~SFXSource

Destructor of the SFXSource class.

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

Description

This destructor calls the SFXSource::Close function.

	Note
	Registered callback functions will be canceled.

Reference

SFXSource::Close

SFXSource::Cancel

Cancel the callback.

[ public, virtual ]
Void Cancel(Void);

Description

This function cancels scheduling with the SFXSource::ScheduleRead function.

The registered callback functions will be canceled.

	Note
	This function is called in the `SFXSource::Close` function.

Reference

SFXSource::ScheduleRead | SFXSource::Close

SFXSource::Close

Close this source.

[ public ]
Void Close(Void);

Description

This function closes (or finishes) this source.

Concretely, this function calls the SFXSource::Cancel function and releases the SFBSource instance that this source internally manages.

	Note
	The registered callback functions will be canceled.

	Note
	This function is called in the `SFXSource::~SFXSource` destructor.

	Tip
	When suspending, resources should be released by calling this function.

Reference

SFXSource::Cancel | SFXSource::~SFXSource | SFXSource::Open | SFBSource

SFXSource::GetSFBSource

Get the SFBSource instance managed internally by this SFXSource storage.

[ public, const ]
SFBSourceSmpConstRef GetSFBSource(Void);

Return value

SFBSource instance managed internally by this SFXSource storage.

Description

This function gets the SFBSource instance managed internally by this SFXSource storage.

Reference

SFBSource | BREW API ISource

SFXSource::GetStreamReader

Get the input stream for reading data from the ISource interface(the SFBSource storage).

[ public, virtual ]
SFCError GetStreamReader(
    UInt32 size                 // buffer size
    SFXStreamReaderPtr result   // pointer to the input stream for reading data from the ISource interface(the SFBSource storage)
);

[ public, virtual ]
SFCError GetStreamReader(
    SFXStreamReaderPtr result   // pointer to the input stream for reading data from the ISource interface(the SFBSource storage)
);

Return value

If succeeds: SFERR_NO_ERROR
If the result argument is null: SFERR_INVALID_PARAM
If no source is registered in this SFXSource storage with the SFXSource::Open function: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function gets the input stream for reading data from this SFXSource storage.

If the size argument is specified, the buffer size of the input stream will be fixed with the specified value. Otherwise, the buffer size will be variable and the SFXElasticStreamReader class will be used internally.

	Tip
	You have to use the `SFXBinaryStreamReader`, `SFXAnsiStringStreamReader`, or `SFXWideStringStreamReader` class for the input stream properly depending on the type of data to be read.

	Caution
	Before calling this function, you have to register the source into this SFXSource storage with the `SFXSource::Open` function.

Reference

SFXSource::GetStreamWriter | SFXBinaryStreamReader | SFXAnsiStringStreamReader | SFXWideStringStreamReader

SFXSource::GetStreamWriter

[This function cannot be used now.]

[ public, virtual ]
SFCError GetStreamWriter(
    UInt32 size                 // size
    SFXStreamWriterPtr result   // pointer to the output stream for writing data to the ISource interface(SFBSource storage)
);

[ public, virtual ]
SFCError GetStreamWriter(
    SFXStreamWriterPtr result   // pointer to the output stream for writing data to the ISource interface(SFBSource storage)
);

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]

Reference

SFXSource::GetStreamReader

SFXSource::Open

Set the specified stream, storage or source to this SFXSource storage.

[ public ]
SFCError Open(
    SFXStorageConstRef storage   // storage
);

[ public ]
SFCError Open(
    SFBSourceSmpConstRef source   // source
);

[ public ]
SFCError Open(
    SFBAStreamSmpConstRef stream   // stream
);

Return value

If succeeds: SFERR_NO_ERROR
If stream, storage or source has already been set: SFERR_INVALID_STATE
If argument is null: SFERR_INVALID_PARAM

Description

This function sets the specified stream, storage or source as the source of this SFXSource storage.

The SFXStorage, SFBAStream or SFBSource instance can be specified in the argument.

After this function is executed, the data will be read by using the input stream obtained with the SFXSource::GetStreamReader function or by calling the SFXSource::Read function.

	Note
	Internally, the storage and the stream will be converted into the source with the AsSFBSource function and the `SFBSourceUtil::SourceFromAStream` function respectively.

Reference

SFXSource::Close | SFXSource::GetStreamReader | SFXSource::Read | SFBSourceUtil::SourceFromAStream BREW API ISOURCEUTIL_SourceFromAStream

SFXSource::Read

Read data from this source without input stream.

[ public, virtual ]
SFCError Read(
    VoidPtr buffer   // buffer to read data
    UInt32Ptr size   // before this function is called: size of the data to read; just after this function is returned: size of the data to be read actually
);

Argument

buffer: Specify the buffer to read data.
size: Before calling this function, specify the buffer size to read data. Just after this function is returned, the size of data to be read actually will be stored into this argument.

Return value

If succeeds: SFERR_NO_ERROR
If this source is not opend (or set) with the SFXSource::Open function: SFERR_INVALID_STATE
If the size argument is null: SFERR_INVALID_PARAM
If an error occurs: ISOURCE_END(-1)
If retry is necessary: ISOURCE_WAIT(-2)

Description

This function reads data from this source without using any stream.

When all data has been read from this ZIPDecoder, this function will return SFERR_NO_ERROR and 0 will be returned into the area that the size argument points to.

* If this function returns ISOURCE_WAIT, it will be necessary to register a callback function with the SFXSource::ScheduleRead function where data will be read with this function.

	Note
	This function internally calls the `SFBSource::Read` function.

	Prerequisite
	This source needs to be opened (or set) with the `SFXSource::Open` function before this function is called.

Reference

SFXSource::Open | SFXSource::ScheduleRead | SFBSource::Read | BREW API ISOURCE_Read

SFXSource::ScheduleRead

Schedule to read data from this source without input stream.

[ public, virtual ]
SFCError ScheduleRead(
    CallbackSPP spp     // callback function
    VoidPtr reference   // data passed to callback function
);

Return value

If succeeds: SFERR_NO_ERROR
If this source is not opened (or set) with the SFXSource::Open function, or reading data has already been scheduled: SFERR_INVALID_STATE

Description

This function schedules to read data from this source without using any stream.

Concretely, this function registers the callback function that will read data with the SFXSource::Read function. The registered callback function will be called by BREW AEE when it is possible to read data.

The status of this source is "under scheduling to read data" until the callback function is called. And after the callback function is called, it will become the status before calling this function, i.e., "this source is opened".

If you call the SFXSource::Cancel function before the callback function is called, reading data will be canceled and the status will be returned to the status before calling this function, i.e., "this source is opened".

*1. If the SFXSource::Read function returns ISOURCE_WAIT, it will be necessary to register a callback function with this function where data will be read with the SFXSource::Read function.

*2. If this function returns the value other than SFERR_NO_ERROR, the specified callback function will not be called.

	Note
	This function internally calls the `SFBSource::Readable` function.

Prerequisite

	Prerequisite
This source needs to be opened (or set) with the `SFXSource::Open` function before this function is called. And if this source has been already scheduled to read data, the SFERR_INVALID_STATE error will be returned.

This source needs to be opened (or set) with the SFXSource::Open function before this function is called.

And if this source has been already scheduled to read data, the SFERR_INVALID_STATE error will be returned.

Reference

SFXSource::ScheduleWrite

[This function cannot be used now.]

[ public, virtual ]
SFCError ScheduleWrite(
    CallbackSPP spp     // callback function
    VoidPtr reference   // data passed to the callback function
);

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]

Reference

SFXStorage::CallbackSPP

SFXSource::Write

[This function cannot be used now.]

[ public, virtual ]
SFCError Write(
    VoidConstPtr buffer   // data to write
    UInt32Ptr size        // size of data to write
);

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]