SFXMemory

Storage class for the memory stream.

#include <SFXMemory.h.hpp>

class SFXMemory : public SFXStorage;

SFMTYPEDEFCLASS(SFXMemory)

Inheritance diagram

Collaboration diagram

Description

The SFXMemory class is used to read / write data from / into the memory storage.

Data can be read from /written into the memory storage using the SFXMemory class as follows:

How to use the SFXMemory class

Create the SFXMemory instance.
Open the SFXMemory storage with the SFXMemory::Open function.
Get the input / output stream with the SFXMemory::GetStreamReader / SFXMemory::GetStreamWriter function.
Read / write data from / into the SFXMemory storage through the input / output stream.
* If the input / output stream is not used, data can be read from / written into the SFXMemory storage with the SFXMemory::Read / SFXMemory::Write function.
Close the SFXMemory storage with the SFXMemory::Close function.

Memory pointer

	Memory pointer
The `SFXMemory` class has the memory pointer. The `SFXMemory::Read` / `SFXMemory::Write` function reads / writes data from / into the memory storage through the memory pointer, which will advance by the amount of the read / written data. It is possible to move the memory pointer with the `SFXMemory::Seek` / `SFXMemory::SeekStart` / `SFXMemory::SeekEnd`. Or, when data is read or written using the stream, the memory pointer will advance by the amount of the read / written data too.

The SFXMemory class has the memory pointer. The SFXMemory::Read / SFXMemory::Write function reads / writes data from / into the memory storage through the memory pointer, which will advance by the amount of the read / written data.

It is possible to move the memory pointer with the SFXMemory::Seek / SFXMemory::SeekStart / SFXMemory::SeekEnd.

Or, when data is read or written using the stream, the memory pointer will advance by the amount of the read / written data too.

Example 826. How to use the SFXMemory class

SFXMemory memory;
SFXBinaryStreamWriter writer;   // output stream for writing data to memory
SFXBinaryStreamReader reader;   // input stream for reading data from memory
SFXAnsiString string;           // variable to read data from memory storage

// open memory storage
if (memory.Open() == SFERR_NO_ERROR) {

    // get output stream for writing data to memory(buffer size is 1024)
    if (memory.GetStreamWriter(1024, &writer)== SFERR_NO_ERROR) {

        writer << "abc";  // write "abc" to output stream
        writer.Flush();         // write "abc" from output stream to memory storage

        // display data to write to memory storage on BREW Output Window
        TRACE("size = %d", memory.GetSize());    // display buffer size: "size = 4"
        TRACE("wrire = %s", memory.GetBuffer()); // display internal buffer: "write = abc + '\0'" 
        
        writer.Release();  // release output stream
    }

    // seek at start
    memory.SeekStart(0);

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

        reader.Fetch();  // read data from memory storage to input stream
        reader >> string; // read data from input stream to string

        // display data to read from memory storage on BREW Output Window
        TRACE("size = %d", string.GetLength());   // display string length: " size = 3"
        TRACE("read = %s", string.GetCString());  // display string: "read = abc" 

        reader.Release();  // release input stream
    }
    memory.Close();  // close memory storage
}

Reference

Member

Constructor/Destructor
SFXMemory( `Void` ) Constructor of the SFXMemory class.
SFXMemory( `UInt16` threshold , `UInt16` cluster ) Constructor of the SFXMemory class.
~SFXMemory( `Void` ) Destructor of the SFXMemory class.

Public Functions
`SFCError`	AsSFBAStream( `SFBAStreamSmpPtr` result ) Convert the SFXBuffer instance internally managed by this memory storage into the SFBAStream instance.
`SFCError`	AsSFBSource( `SFBSourceSmpPtr` result ) Convert the SFXBuffer instance internally managed by this memory storage into the SFBSource instance.
`Void`	Cancel( `Void` ) [This function cannot be used now.]
`SFCError`	Close( `SFXBufferPtr` buffer ) Close this memory stotage.
`Void`	Close( `Void` ) Close this memory stotage.
`VoidConstPtr`	GetBuffer( `Void` ) Get the pointer to the internal buffer of this memory storage.
`UInt16`	GetCluster( `Void` ) Get the cluster size of the internal buffer of this memory storage. [in bytes]
`UInt32`	GetSize( `Void` ) Get the size of the internal buffer of this memory storage. [in bytes]
`SFCError`	GetStreamReader( `UInt32` size , `SFXStreamReaderPtr` result ) Get the input stream for reading data from this memory storage.
`SFCError`	GetStreamReader( `SFXStreamReaderPtr` result ) Get the input stream for reading data from this memory storage.
`SFCError`	GetStreamWriter( `UInt32` size , `SFXStreamWriterPtr` result ) Get the output stream for writing data onto this memory storage.
`SFCError`	GetStreamWriter( `SFXStreamWriterPtr` result ) Get the output stream for writing data onto this memory storage.
`UInt16`	GetThreshold( `Void` ) Get the minimum size of the internal buffer of this memory storage. [in bytes]
`SFCError`	Open( `SFXBufferConstRef` buffer ) Open this memory storage.
`SFCError`	Open( `VoidConstPtr` buffer , `UInt32` size ) Open this memory storage.
`SFCError`	Open( `Void` ) Open this memory storage.
`SFCError`	Read( `VoidPtr` buffer , `UInt32Ptr` size ) Read data from this memory storage without input stream.
`SFCError`	ScheduleRead( `CallbackSPP` spp , `VoidPtr` reference ) [This function cannot be used now.]
`SFCError`	ScheduleWrite( `CallbackSPP` spp , `VoidPtr` reference ) [This function cannot be used now.]
`SFCError`	Seek( `SInt32` distance ) Move the memory pointer by the specified amount from the current position of the internal buffer of this memory storage. [in bytes]
`SFCError`	SeekEnd( `SInt32` distance ) Move the memory pointer by the specified amount from the end position of the internal buffer of this memory storage. [in bytes]
`SFCError`	SeekStart( `SInt32` distance ) Move the memory pointer by the specified amount from the start position of the internal buffer of this memory storage. [in bytes]
`Void`	SetCluster( `UInt16` size ) Set the cluster size of the internal buffer of this memory storage to the specified value. [in bytes]
`Void`	SetThreshold( `UInt16` size ) Set the minimum size of the internal buffer of this memory storage to the specified value. [in bytes]
`UInt32`	Tell( `Void` ) Get the current position of the memory pointer of this memory storage.
`SFCError`	Truncate( `UInt32` position ) Truncate the internal buffer of this memory storage with the specified size. [in bytes]
`SFCError`	Write( `VoidConstPtr` buffer , `UInt32Ptr` size ) Write data into this memory storage without output stream.

Types
DefaultEnum Constants that represent the default values for the minimum size and the cluster size of the internal buffer memory. [in bytes]
CallbackSPP (inherits from SFXStorage) Type of the callback function for the Storage class.

SFXMemory::SFXMemory

Constructor of the SFXMemory class.

[ public, explicit ]
SFXMemory(Void);

[ public, explicit ]
SFXMemory(
    UInt16 threshold   // internal buffer's threshold
    UInt16 cluster     // internal buffer's cluster size 
);

Description

This constructor allocates an internal buffer with the threshold and cluster specified in the threshold and cluster arguments, if they are specified. Otherwise does nothing.

Reference

SFXMemory::SetThreshold | SFXMemory::SetCluster

SFXMemory::~SFXMemory

Destructor of the SFXMemory class.

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

Description

This destructor calls the SFXMemory::Close function.

Reference

SFXMemory::Close

SFXMemory::AsSFBAStream

Convert the SFXBuffer instance internally managed by this memory storage into the SFBAStream instance.

[ public, virtual, const ]
SFCError AsSFBAStream(
    SFBAStreamSmpPtr result   // pointer to the SFBAStream instance
);

Argument

result: Specify the pointer to the SFBAStream instance.

Return value

If succeeds: SFERR_NO_ERROR
If this memory storage has been closed: SFERR_INVALID_STATE
If the result argument is null: SFERR_INVALID_PARAM

Description

This function converts the SFXBuffer instance internally managed by this memory storage into the SFBAStream instance.

As a result, a pointer to the SFBAStream instance will be returned into the result argument.

	Note
	The contents of the memory storage can be handled through the `SFBAStream` instance.

Reference

SFXBuffer | SFBAStream

SFXMemory::AsSFBSource

Convert the SFXBuffer instance internally managed by this memory storage into the SFBSource instance.

[ public, virtual, const ]
SFCError AsSFBSource(
    SFBSourceSmpPtr result   // pointer to the SFBSource instance
);

引数

result: Specify the pointer to the SFBSource instance.

Return value

If succeeds: SFERR_NO_ERROR
If this memory storage has been closed: SFERR_INVALID_STATE
If the result argument is null: SFERR_INVALID_PARAM

Description

This function converts the SFXBuffer instance internally managed by this memory storage into the SFBSource instance.

As a result, a pointer to the SFBSource instance will be returned into the result argument.

	Note
	This function internally calls the `BREW API ISOURCEUTIL_SourceFromMemory` function.

	Note
	The contents of the memory storage can be handled as the `SFBSource` instance.

Reference

SFXBuffer | SFBSource | BREW API ISOURCEUTIL_SourceFromMemory

SFXMemory::Cancel

[This function cannot be used now.]

[ public, virtual ]
Void Cancel(Void);

Description

[This function cannot be used now.]

SFXMemory::Close

Close this memory stotage.

[ public ]
SFCError Close(
    SFXBufferPtr buffer   // pointer to the buffer
);

[ public ]
Void Close(Void);

Return value

If the buffer argument is not specified, nothing is returned.

Otherwise, an error value will be returned as follows:

If succeeds: SFERR_NO_ERROR
If this memory storage has already been closed: SFERR_INVALID_STATE
If the buffer argument is null: SFERR_INVALID_PARAM
If insufficient memory: SFERR_NO_MEMORY

Description

This function closes (or finishes) this memory storage.

Concretely, this function releases the internal buffer that this memory storage internally manages.

If the buffer argument is specified, the internal buffer is copied into it before released.

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

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

Reference

SFXMemory::Open | SFXMemory::~SFXMemory

SFXMemory::GetBuffer

Get the pointer to the internal buffer of this memory storage.

[ public, const ]
VoidConstPtr GetBuffer(Void);

Return value

Pointer to the internal buffer of this memory storage.

Description

This function gets the pointer to the internal buffer of this memory storage.

SFXMemory::GetCluster

Get the cluster size of the internal buffer of this memory storage. [in bytes]

[ public, const ]
UInt16 GetCluster(Void);

Return value

Cluster size of the internal buffer of this memory storage. [in bytes]

Description

This function gets the cluster size of the internal buffer of this memory storage. [in bytes]

Reference

SFXMemory::SetCluster | SFXBuffer::GetCluster

SFXMemory::GetSize

Get the size of the internal buffer of this memory storage. [in bytes]

[ public, const ]
UInt32 GetSize(Void);

Return value

If this memory storage is closed : 0 byte
If this memory storage is open: size of the internal buffer of this memory storage. [in bytes]

Description

This function gets the size of the internal buffer of this memory storage. [in bytes]

Reference

SFXMemory::Tell | SFXMemory::Truncate

SFXMemory::GetStreamReader

Get the input stream for reading data from this memory storage.

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

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

Return value

If succeeds: SFERR_NO_ERROR
If the result argument is null: SFERR_INVALID_PARAM
If the memory storage is closed: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function gets the input stream for reading data from this memory 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.

Reference

SFXMemory::GetStreamWriter | SFXBinaryStreamReader | SFXAnsiStringStreamReader | SFXWideStringStreamReader

SFXMemory::GetStreamWriter

Get the output stream for writing data onto this memory storage.

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

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

Return value

If succeeds: SFERR_NO_ERROR
If the result argument is null: SFERR_INVALID_PARAM
If the memory storage is closed: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function gets the output stream for writing data onto this memory storage.

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

	Tip
	You have to use the `SFXBinaryStreamWriter`, `SFXAnsiStringStreamWriter`, or `SFXWideStringStreamWriter` class for the output stream properly depending on the type of data to write.

Reference

SFXMemory::GetStreamReader | SFXBinaryStreamWriter | SFXAnsiStringStreamWriter | SFXWideStringStreamWriter

SFXMemory::GetThreshold

Get the minimum size of the internal buffer of this memory storage. [in bytes]

[ public, const ]
UInt16 GetThreshold(Void);

Return value

Minimum size of the internal buffer of this memory storage. [in bytes]

Description

This function gets the minimum size of the internal buffer of this memory storage. [in bytes]

Reference

SFXMemory::SetThreshold | SFXBuffer::GetThreshold

SFXMemory::Open

Open this memory storage.

[ public ]
SFCError Open(
    SFXBufferConstRef buffer   // buffer to be copied
);

[ public ]
SFCError Open(
    VoidConstPtr buffer   // buffer to be copied
    UInt32 size           // size of the buffer to be copied
);

[ public ]
SFCError Open(Void);

Return value

If succeeds: SFERR_NO_ERROR
If this memory storage has already been opened: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function opens this memory storage.

Concretely, this memory storage will be initialized so that data can be read from or written into it. If the buffer argument is specified, the specified buffer will be copied to the internal buffer of this memory storage. Otherwise, no data will be copied into the internal buffer(the internal buffer is empty and its size is 0).

Reference

SFXMemory::Close

SFXMemory::Read

Read data from this memory storage without input stream.

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

);

Argument

buffer: Specify the buffer to read data into.
size: Before calling this function, specify the size of the buffer to read data into. 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 memory storage is not opened with the SFXMemory::Open function: SFERR_INVALID_STATE
If the size argument is null: SFERR_INVALID_PARAM
If read position is beyond the end of this memory storage: EFILEEOF

Description

This function reads data from this memory storage without input stream.

	Prerequisite
	This memory storage needs to be opened with the `SFXMemory::Open` function before this function is called.

Reference

SFXMemory::Open | SFXMemory::Write | SFXMemory::GetSize | SFXMemory::Seek | SFXMemory::Tell

SFXMemory::ScheduleRead

[This function cannot be used now.]

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

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]

Reference

SFXStorage::CallbackSPP

SFXMemory::ScheduleWrite

[This function cannot be used now.]

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

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]

Reference

SFXStorage::CallbackSPP

SFXMemory::Seek

Move the memory pointer by the specified amount from the current position of the internal buffer of this memory storage. [in bytes]

[ public ]
SFCError Seek(
    SInt32 distance   // moving amount
);

Return value

If succeeds: SFERR_NO_ERROR
If this memory storage is not opened with the SFXMemory::Open function: SFERR_INVALID_STATE

Description

This function moves the memory pointer by the specified amount from the current position of the internal buffer of this memory storage. [in bytes]

If the memory pointer is moved by the specified amount to point to the position before the start or after the end of the internal buffer of this memory storage, it will be set to the start or the end respectively.

	Note
	To move the memory pointer backward, set the distance argument to a negative value as the moving amount.

	Prerequisite
	This memory storage needs to be opened with the `SFXMemory::Open` function before this function is called.

Reference

SFXMemory::SeekStart | SFXMemory::SeekEnd | SFXMemory::Open

SFXMemory::SeekEnd

Move the memory pointer by the specified amount from the end position of the internal buffer of this memory storage. [in bytes]

[ public ]
SFCError SeekEnd(
    SInt32 distance   // moving amount
);

Return value

If succeeds: SFERR_NO_ERROR
If this memory storage is not opened with the SFXMemory::Open function: SFERR_INVALID_STATE

Description

This function moves the memory pointer by the specified amount from the end position of the internal buffer of this memory storage. [in bytes]

	Note
	To move the memory pointer backward, set negative value as moving amount to the distance argument.

	Prerequisite
	This memory storage needs to be opened with the `SFXMemory::Open` function before this function is called.

Reference

SFXMemory::Seek | SFXMemory::SeekStart | SFXMemory::Open

SFXMemory::SeekStart

Move the memory pointer by the specified amount from the start position of the internal buffer of this memory storage. [in bytes]

[ public ]
SFCError SeekStart(
    SInt32 distance   // moving amount
);

Return value

If succeeds: SFERR_NO_ERROR
If this memory storage is not opened with the SFXMemory::Open function: SFERR_INVALID_STATE

Description

This function moves the memory pointer by the specified amount from the start position of the internal buffer of this memory storage. [in bytes]

	Note
	To move the memory pointer backward, set negative value as moving amount to the distance argument.

	Prerequisite
	This memory storage needs to be opened with the `SFXMemory::Open` function before this function is called.

Reference

SFXMemory::Seek | SFXMemory::SeekEnd | SFXMemory::Open

SFXMemory::SetCluster

Set the cluster size of the internal buffer of this memory storage to the specified value. [in bytes]

[ public ]
Void SetCluster(
    UInt16 size   // cluster size
);

Description

This function sets the minimum unit, i.e., cluster size, to allocate to the internal buffer(SFXBuffer) of this memory storage to the specified value. [in bytes]

Default: SFXMemory::DEFAULT_CLUSTER bytes

For the value of SFXMemory::DEFAULT_CLUSTER, see SFXMemory::DefaultEnum.

Reference

SFXMemory::GetCluster | SFXMemory::DefaultEnum | SFXBuffer::SetCluster | SFXBuffer

SFXMemory::SetThreshold

Set the minimum size of the internal buffer of this memory storage to the specified value. [in bytes]

[ public ]
Void SetThreshold(
    UInt16 size   // minimum value to be set
);

Description

This function sets the minimum memory of the internal buffer(SFXBuffer) of this memory storage to the specified value. [in bytes]

Default: SFXMemory::DEFAULT_THRESHOLD bytes

For the value of SFXMemory::DEFAULT_THRESHOLD, see SFXMemory::DefaultEnum.

Reference

SFXMemory::GetThreshold | SFXMemory::DefaultEnum | SFXBuffer::SetThreshold | SFXBuffer

SFXMemory::Tell

Get the current position of the memory pointer of this memory storage.

[ public, const ]
UInt32 Tell(Void);

Return value

If this memory storage is opened: current position of the memory pointer of this memory storage
If this memory storage is closed: 0

Description

This function gets the current position of the memory pointer of this memory storage.

Reference

SFXMemory::Seek | SFXMemory::Truncate

SFXMemory::Truncate

Truncate the internal buffer of this memory storage with the specified size. [in bytes]

[ public ]
SFCError Truncate(
    UInt32 position   // size
);

Return value

If succeeds: SFERR_NO_ERROR
If this memory storage is not opened with the SFXMemory::Open function: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function truncates the internal buffer of this memory storage with the specified size. [in bytes]

The memory pointer will be moved to the end position of the truncated internal buffer of this memory storage when the current pointer is beyond the end position.

	Prerequisite
	This memory storage needs to be opened with the `SFXMemory::Open` function before this function is called.

Reference

SFXMemory::Seek | SFXMemory::Tell | SFXMemory::Open

SFXMemory::Write

Write data into this memory storage without output stream.

[ public, virtual ]
SFCError Write(
    VoidConstPtr buffer   // buffer to write data into
    UInt32Ptr size        
// before this function is called: size of the buffer to write data into; 
just after this function is returned: size of the data to be written actually

);

Argument

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

Return value

If succeeds: SFERR_NO_ERROR
If this memory storage is not opened with the SFXMemory::Open function: SFERR_INVALID_STATE
If the size argument is null: SFERR_INVALID_PARAM

Description

This function writes data into this memory storage without output stream.

	Prerequisite
	This memory storage needs to be opened with the `SFXMemory::Open` function before this function is called.

Reference

SFXMemory::Open | SFXMemory::Read | SFXMemory::GetSize | SFXMemory::Seek | SFXMemory::Tell

SFXMemory::DefaultEnum

Constants that represent the default values for the minimum size and the cluster size of the internal buffer memory. [in bytes]

enum DefaultEnum {
    DEFAULT_THRESHOLD  = SFXBuffer::DEFAULT_THRESHOLD,    // default minimum size of the internal buffer of this memory storage [in bytes]
    DEFAULT_CLUSTER    = SFXBuffer::DEFAULT_CLUSTER       // default cluster size to allocate to the internal buffer of this memory storage [in bytes]
};

Description

DEFAULT_THRESHOLD and DEFAULT_CLUSTER are the constants that represent the default values for the minimum size and the cluster size of the internal buffer(SFXBuffer) of this memory storage. [in bytes]

Reference

SFXMemory::SetCluster | SFXMemory::SetThreshold | SFXBuffer | SFXBuffer::DefaultEnum