Home > Language Reference > Classes

StreamMemory Class

  + Object
    + Stream
      + StreamMemory

Description

The StreamMemory class allows manipulation of memory blocks as streams (see also Data Streams). This object is typically used to store raw data, like records in a native database, or a parameter block transmitted to another application (see CustomLaunch) or to an external C function (see Declare). This class is instantiable but not derivable nor cloneable.

The memory block the StreamMemory object manages is automatically allocated and resized as needed, and destroyed by the garbage collector when it is no longer used. This memory block can be located either in the dynamic heap or in the storage heap, depending on circumstances.The following summarizes this:

• When a StreamMemory object is first created, it does not hold any memory block. Its Kind property always returns hbStreamUnallocated, and invoking tyhe Read function on such a stream raises an error.
• When a StreamMemory object is retrieved from a native database using one of the Record or Resource properties, the memory block it manages is actually that database record itself (no copy is performed), and thus is located in the storage heap. The Kind property then returns hbStreamStorage.
• If you calls the Write method (or any other operation that alters the memory block content) and the previous status of the StreamMemory object was hbStreamUnallocated, a new memory block is allocated in the dynamic heap. If it was hbStreamStorage, the database record is copied into the dynamic heap so that it can be modified. The Kind property then returns hbStreamHeap.

Due to Palm OS^® limitations, a StreamMemory object cannot manage memory blocks greater than approximately 64 kb.

A StreamMemory object can also be mapped to any memory address, using the Map method. A memory mapped stream does not allocate nor manage any memory block. It simply encapsulates a portion of the device memory into a stream so that you can easily read or alter its content. This is close to the functionnality pointers offer in C/C++. Of course, it may also be as hazardous as pointers can be, and it is strongly advised you do not use this feature unless you know exactly what you are doing. The Kind property of such a stream always returns hbStreamMapped.

A StreamMemory object can also be placed into a destructive read mode. This mode deletes blocks as data are read, freeing storage automatically. This feature can be used to implement a pseudo-pipe, for example. Please refer to the Destructive property for more information.

This class supports all the functionality inherited from the Stream class. Refer to the documentation of this class for more information. Furthermore, this class also offers the Clear and Truncate methods to delete all or part of a memory block, the FindByte function to find a specified byte in the memory block and the Crc16 function to perform checksum computations.

When a StreamMemory object is duplicated, for example using the Clone function, what happens to the data contained in the memory block depends on the status of the StreamMemory object. If the memory block resides in the dynamic heap (ie the Kind property returns hbStreamHeap), it is copied. Once the operation completes, both the original and the copied objects have their own set of data. On the other hand, if the memory block resides in the storage heap or is mapped to an arbitrary memory address (ie the Kind property returns hbStreamStorage or hbStreamMapped), it is not copied. Once the operation completes, both objects points to the same data.

Members

System requirements