SFXMemory

Storage class for the memory stream.

#include <SFXMemory.h.hpp>

class SFXMemory : public SFXStorage;

SFMTYPEDEFCLASS(SFXMemory)

Inheritance diagram

Collaboration diagram

Description

SFXMemory has an internal buffer that is read or written by the stream obtained by the SFXMemory::GetStreamReader or SFXMemory::GetStreamWriter function.

SFXMemory has the read/write pointer. In the SFXMemory::Read and SFXMemory::Write function, data is read and written through the pointer, which is moved by the amount of read/written data.

How to use the SFXMemory class

Create the SFXMemory instance.
Open the memory storage using the SFXMemory::Open function.
Get the input stream for reading data from memory and the output stream for writing data to memory by the SFXMemory::GetStreamReader function and SFXMemory::GetStreamWriter function respectively.
Read data from the input stream and write data to the output stream.
After using the input or output stream, release resources by calling the SFXMemory::Close function.

Example 478. Sample code for the memory stream

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 SFXMemory class.
SFXMemory( `UInt16` threshold , `UInt16` cluster ) Constructor of SFXMemory class.
~SFXMemory( `Void` ) Destructor of SFXMemory class.

Public Functions
`Void`	Cancel( `Void` ) [ This function cannot be used now. ]
`SFCError`	Close( `SFXBufferPtr` buffer ) Close the memory.
`Void`	Close( `Void` ) Close the memory.
`VoidConstPtr`	GetBuffer( `Void` ) Get the pointer to the internal buffer.
`UInt16`	GetCluster( `Void` ) Get the cluster size of the buffer memory used internally.
`UInt32`	GetSize( `Void` ) Get the size of the buffer used internally.
`SFCError`	GetStreamReader( `UInt32` size , `SFXStreamReaderPtr` result ) GetStreamReader( `SFXStreamReaderPtr` result ) Get the input stream for reading data from memory storage.
`SFCError`	GetStreamWriter( `UInt32` size , `SFXStreamWriterPtr` result ) GetStreamWriter( `SFXStreamWriterPtr` result ) Get the output stream for writing data to memory storage.
`UInt16`	GetThreshold( `Void` ) Get the minimum value of internal buffer size.
`SFCError`	Open( `SFXBufferConstRef` buffer ) Open( `Void` ) Open( `VoidConstPtr` buffer , `UInt32` size ) Open the memory storage.
`SFCError`	Read( `VoidPtr` buffer , `UInt32Ptr` size ) Read data from memory storage without using the 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.
`SFCError`	SeekEnd( `SInt32` distance ) Move the memory pointer by the specified amount from the end position of buffer.
`SFCError`	SeekStart( `SInt32` distance ) Move the memory pointer by the specified amount from the start position of buffer.
`Void`	SetCluster( `UInt16` size ) Set the cluster size of internal buffer memory.
`Void`	SetThreshold( `UInt16` size ) Set the minimum value of internal buffer size.
`UInt32`	Tell( `Void` ) Get the current position of the read/write pointer.
`SFCError`	Truncate( `UInt32` position ) Truncate the internal buffer with the specified size.
`SFCError`	Write( `VoidConstPtr` buffer , `UInt32Ptr` size ) Write data to memory storage without using the output stream.

Types
DefaultEnum Enumeration type of initial value of each parameter regarding the memory storage.
CallbackSPP (inherits from SFXStorage) The prototype of the callback function for the SFXStorage class.

SFXMemory::SFXMemory

Constructor of SFXMemory class.

[ public, explicit ]
SFXMemory(Void);

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

Description

An internal buffer is allocated.

Reference

SFXMemory::SetThreshold | SFXMemory::SetCluster

SFXMemory::~SFXMemory

Destructor of SFXMemory class.

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

SFXMemory::Cancel

[ This function cannot be used now. ]

[ public, virtual ]
Void Cancel(Void);

SFXMemory::Close

Close the memory.

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

[ public ]
Void Close(Void);

Return value

If the argument is not specified, nothing is returned.

If SFXBufferPtr is specified for the argument, error value is returned.

Succeeded : SFERR_NO_ERROR
If memory storage is closed : SFERR_INVALID_STATE
If argument is null : SFERR_INVALID_PARAM
If insufficient memory : SFERR_NO_MEMORY

Description

If the argument is not specified, internal buffer will be released.

If the buffer of SFXBufferPtr type is specified as an argument, the internal buffer is copied to the specified buffer and then released.

Reference

SFXMemory::Open

SFXMemory::GetBuffer

Get the pointer to the internal buffer.

[ public, const ]
VoidConstPtr GetBuffer(Void);

SFXMemory::GetCluster

Get the cluster size of the buffer memory used internally.

[ public, const ]
UInt16 GetCluster(Void);

Reference

SFXBuffer::GetCluster | SFXMemory::SetCluster

SFXMemory::GetSize

Get the size of the buffer used internally.

[ public, const ]
UInt32 GetSize(Void);

Return value

If memory storage is closed : 0
If memory storage is open: size of the buffer used internally

Reference

SFXMemory::Tell | SFXMemory::Truncate

SFXMemory::GetStreamReader

Get the input stream for reading data from 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

Success : SFERR_NO_ERROR
If argument is null : SFERR_INVALID_PARAM
If memory storage is closed : SFERR_INVALID_STATE
If insufficient memory : SFERR_NO_MEMORY

Description

The buffer size of the input stream can be specified. Use the SFXBinaryStreamReader, SFXAnsiStringStreamReader, or SFXWideStringStreamReader class for the input stream properly according to the type of data to read.

Reference

SFXMemory::GetStreamWriter | SFXBinaryStreamReader | SFXAnsiStringStreamReader | SFXWideStringStreamReader

SFXMemory::GetStreamWriter

Get the output stream for writing data to 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

Success : SFERR_NO_ERROR
If argument is null : SFERR_INVALID_PARAM
If memory storage is closed : SFERR_INVALID_STATE
If insufficient memory : SFERR_NO_MEMORY

Description

The buffer size of the output stream can be specified. Use the SFXBinaryStreamWriter, SFXAnsiStringStreamWriter, or SFXWideStringStreamWriter class for the output stream properly according to the written data type

Reference

SFXMemory::GetStreamReader | SFXBinaryStreamWriter | SFXAnsiStringStreamWriter | SFXWideStringStreamWriter

SFXMemory::GetThreshold

Get the minimum value of internal buffer size.

[ public, const ]
UInt16 GetThreshold(Void);

Reference

SFXBuffer::GetThreshold | SFXMemory::SetThreshold

SFXMemory::Open

Open the 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

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

Description

Initialize to use the memory storage. If the buffer is specified as an argument, the specified buffer is copied to the internal buffer. If the argument is not specified, the internal buffer is empty (size 0).

Reference

SFXMemory::Close

SFXMemory::Read

Read data from memory storage without using the input stream.

[ public, virtual ]
SFCError Read(
    VoidPtr buffer   // buffer to read data from memory storage
    UInt32Ptr size   // bufer size
);

Argument

buffer: Specify the buffer to read data from memory storage.
size: Specify the size of buffer when calling SFXMemory::Read function. When the SFXMemory::Read function ends, the size of data that is actually read is stored.

Return value

Success : SFERR_NO_ERROR
If memory storage has been closed : SFERR_INVALID_STATE
If the size argument is null : SFERR_INVALID_PARAM
If read position is at the end of file : EFILEEOF

Reference

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
);

Description

SFERR_UNSUPPORTED is returned.

SFXMemory::ScheduleWrite

[ This function cannot be used now. ]

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

Description

Return SFERR_UNSUPPORTED.

SFXMemory::Seek

Move the memory pointer by the specified amount from the current position.

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

Return value

Success : SFERR_NO_ERROR
If memory storage is closed : SFERR_INVALID_STATE

Description

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

If the poition of memory pointer after moved by this function is under the start of buffer or over the end of buffer, it will be set to the start or end of buffer respectively.

Reference

SFXMemory::SeekStart | SFXMemory::SeekEnd

SFXMemory::SeekEnd

Move the memory pointer by the specified amount from the end position of buffer.

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

Return value

Success : SFERR_NO_ERROR
If memory storage is closed : SFERR_INVALID_STATE

Description

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

If the poition of memory pointer after moved by this function is under the start of buffer or over the end of buffer, it will be set to the start or end of buffer respectively.

Reference

SFXMemory::Seek | SFXMemory::SeekStart

SFXMemory::SeekStart

Move the memory pointer by the specified amount from the start position of buffer.

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

Return value

Success : SFERR_NO_ERROR
If memory storage is closed : SFERR_INVALID_STATE

Description

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

If the poition of memory pointer after moved by this function is under the start of buffer or over the end of buffer, it will be set to the start or end of buffer respectively.

Reference

SFXMemory::Seek | SFXMemory::SeekEnd

SFXMemory::SetCluster

Set the cluster size of internal buffer memory.

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

Description

Set the minimum unit size when allocating the internal buffer.

Reference

SFXBuffer::SetThreshold | SFXMemory::GetThreshold

SFXMemory::SetThreshold

Set the minimum value of internal buffer size.

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

Reference

SFXBuffer::SetThreshold | SFXMemory::GetThreshold

SFXMemory::Tell

Get the current position of the read/write pointer.

[ public, const ]
UInt32 Tell(Void);

Return value

If memory storage is opened: the current position of the read/write pointer
If memory storage is closed : 0

Reference

SFXMemory::Seek | SFXMemory::Truncate

SFXMemory::Truncate

Truncate the internal buffer with the specified size.

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

Return value

Success : SFERR_NO_ERROR
If memory storage is closed : SFERR_INVALID_STATE
If insufficient memory : SFERR_NO_MEMORY

Description

The read/write pointer will be moved to the end position of buffer truncated using the SFXMemory::Truncate function when the current pointer is over the end of buffer.

Reference

SFXMemory::Seek | SFXMemory::Tell

SFXMemory::Write

Write data to memory storage without using the output stream.

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

Argument

buffer: Specify the buffer to write data to memory storage.
size: Specify the size of data to write to memory storage when calling the SFXMemory::Write function. When the SFXMemory::Write function ends, the size of data that is actually written is stored.

Return value

Success : SFERR_NO_ERROR
If memory storage is closed : SFERR_INVALID_STATE
If the size argument is null : SFERR_INVALID_PARAM

Reference

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

SFXMemory::DefaultEnum

Enumeration type of initial value of each parameter regarding the memory storage.

enum DefaultEnum {
    DEFAULT_THRESHOLD               = SFXBuffer::DEFAULT_THRESHOLD,
    DEFAULT_CLUSTER                 = SFXBuffer::DEFAULT_CLUSTER
};

Description

DEFAULT_THRESHOLD: the default value of the minimum value of internal buffer size.
DEFAULT_CLUSTER: the default value of the cluster size of internal buffer memory.

Reference

SFXBuffer::DefaultEnum