MMA_StreamHandle

(V51) [I.G.Q], ULONG, 0x8EDA000D

DESCRIPTION

   Memory stream handle is just the address of memory buffer to be used as
   stream data. This address must not be random. Use static tables or memory
   allocated dynamically as stream data. One of MMA_StreamHandle or
   MMA_StreamName must be specified at object creation time. If both are
   specified, the name has the precedence. The attribute has no default
   value

SEE ALSO

MMA_StreamLength

(V51) [I.G.Q], QUAD*, 0x8EDA0018

DESCRIPTION

   Unlike other streams, memory stream has no natural end (except of limit
   of CPU address space). That is why MMA_StreamLength must be specified at
   object creation time. The value passed must be lower or equal to buffer
   size, so unallocated memory area is not read

NOTES

   You can theoretically use local table as memory stream, but you must
   remember that this stream is valid only in the scope of this local table.
   It can easily become tricky and is not recommended.

   This attribute is 64-bit and as such is passed as a pointer to the actual
   value.

EXAMPLE

   Some examples of safe memory streams:

   UBYTE tab[1000];    (global variable)
   QUAD len = 1000;
   ...
   MMA_StreamHandle, (ULONG)tab, MMA_StreamLength, (ULONG)&len,

   UBYTE *buf;
   QUAD len = 2048;
   buf = AllocMem(2048, MEMF_ANY);
   ...
   MMA_StreamHandle, (ULONG)buf, MMA_StreamLength, (ULONG)&len

SEE ALSO

MMA_StreamName

(V51) [I.G.Q], STRPTR, 0x8EDA0009

DESCRIPTION

   Name of a memory stream contains hexadecimal string of address of memory
   area to be used as stream data. This string should not contain prefixes
   like '0x' or '$'. Leading whitespaces are allowed, all spaces, tabs, CR
   and LF characters are stripped. Leading zeros are optional. This string
   is case insensitive for 'a' to 'f' digits (case may be mixed in one name
   too). One of MMA_StreamName or MMA_StreamHandle must be specified at
   object creation time. If both are specified, the name has the precedence.
   The attribute has no default value

NOTES

   A local copy of the passed string is made, so the string can be local
   variable or dynamic.

SEE ALSO

MMA_StreamPosBytes

(V51) [..G.Q], QUAD*, 0x8EDA0012

DESCRIPTION

   Returns current stream read position in bytes

NOTES

   This attribute is 64-bit, storage should point to QUAD variable.

MMA_StreamSeekable

(V50) [..G.Q], BOOL, 0x8EDA0011

DESCRIPTION

   Returns TRUE if the stream is seekable, FALSE otherwise. All memory
   streams are seekable

MMM_Pull

Reads a data block from a stream. (V50)

SYNOPSIS

   LONG DoMethod(Object *obj, MMM_Pull, ULONG port, APTR buffer, LONG
   length);

DESCRIPTION

   The method reads a block of data of given length from a port of specified
   object starting from current read pointer position. Data may be pulled
   only from port 0 (as it is the only port existing in a memory.stream
   object). Pulls beyond stream length are cut and MMERR_END_OF_DATA is set
   as MMA_ErrorCode

INPUTS

   obj - object to perform method on.
   port - memory.stream has only port 0.
   buffer - address of buffer for pulled data.
   length - number of bytes to pull

RESULT

   Number of bytes pulled actually. MMA_ErrorCode contains secondary
   error information

MMM_Seek

Moves stream read pointer. (V51)

SYNOPSIS

   ULONG DoMethod(Object *obj, MMM_Seek, ULONG port, ULONG type, QUAD
   *position);

DESCRIPTION

   The read pointer of the stream is moved to the specified position,
   following MMM_Pull will read from there

INPUTS

   obj - object to perform method on.
   port - memory.stream has only port 0, so set to 0.
   type - type of seek, memory stream understands only MMM_SEEK_BYTES.
   position - a pointer to QUAD variable containing new absolute position

RESULT

   TRUE or FALSE if seek cannot be done. MMA_ErrorCode contains secondary
   error information

background

HISTORY

   51.6  (12.07.2010)
   - Fixed: Due to stupid copy&paste bug, MMM_Seek() called MMM_PostPull()
     instead of MMM_PostSeek(). Produced weird log messages and could set
     wrong error codes when seek failed.

   51.5  (14.06.2010)
   - New style MMM_Pull() and MMM_Seek().
   - MMA_StreamMode removed.
   - Autodoc updated.

   51.4  (19.03.2007)
   - Bugfix: MMA_SeekableStream was not gettable via MMM_GetPort.

   51.3  (09.01.2006)
   - Output port format is MMF_STREAM, not MMF_ANY_FORMAT.

   51.2  (04.04.2005)
   - Added MMA_StreamSeekable.
   - Switched to new API (Pull/Push).

   50.10 (11.10.2004)
   - Removed redundant NULL initialization of global library bases.
   - Query tags accessible via the class base.

   50.9 (11.7.2004)
   - MediaLogger support.
   - Query.library support.

   50.8 (30.12.2003)
   - Added: 'debug' target in makefile.
   - Changed: Debug output is done with kprintf().

   50.7 (27.12.2003)
   - DTSA_Handle can be used instead of DTSA_Name, it contains direct
     pointer instead of string.

   50.6 (4.11.2003)
   - DTSM_IsSupported: DTSM_Peek is now handled by superclass.

   50.5 (3.11.2003)
   - If DTSA_Mode_NewStream is specified stream buffer is cleared to all
     zeros as documented.

   50.4 (2.11.2003)
   - DTSM_ReadBlock: stream position limited to 2 GB.
   - DTSM_WriteBlock: uses superclass data pointer instead of internal one.
   - DTSM_CutBlock: uses superclass data pointer instead of internal one.
   - DTSM_InsertBlock: uses superclass data pointer instead of internal one.
   - DTSM_SeekStream: added SysBase->MaxExtMem check.
   - Removed all MaxExtMem checks, as this field contains no valid
     information.
   - Extensive tests performed, release version.

   50.3 (1.11.2003)
   - DTSM_ReadBlock: request is rejected with STRERR_WRONG_ARGUMENT if end
     of operation is behind SysBase->MaxExtMem.
   - DTSM_ReadBlock: uses superclass data pointer instead of internal one.

   50.2 (31.10.2003)
   - Fixed bug in TypeOfMem() workaround, memtype was compared against
     MaxLocMem instead of address passed.
   - OM_NEW will now fail if stream has no user limit set via DTSA_Length,
     or stream limit is greater than 0x7FFFFFFF.
   - New methods implemented: DTSM_CutBlock, DTSM_InsertBlock,
     DTSM_SeekStream, DTSM_IsSupported.

DESCRIPTION

   The class allows for using a memory area as Reggae stream, so data can be
   accessed with common methods. Useful for example for media data embedded
   into executable file, or for streams generated by software. Memory.stream
   object has one port. This port has always number 0 and is output for read
   streams, input for write streams.

   Object construction failure reasons

   MMA_ErrorCode == MMERR_WRONG_ARGUMENTS
   - MMA_StreamName content is not a hexadecimal number,
   - MMA_StreamName/MMA_StreamHandle do not point to existing memory,
   - MMA_StreamLength greater than 2 GB,
   - MMA_StreamLength specified as 0,
   - MMA_StreamLength not specified at all,
   - Neither MMA_StreamName nor MMA_StreamHandle specified.

   MMA_ErrorCode == MMERR_OUT_OF_MEMORY
   - MMA_StreamName was specified and there is no memory for a local copy of
     it.

NEW ATTRIBUTES

   Attributes applicability:
     I - may be set at creation time.
     S - may be set on an existing object.
     G - may be get from an object.
     P - may be set for an object's port.
     Q - may be queried from an object's port.

   MMA_StreamName         (V50) [I.G.Q], STRPTR, required on init (1)
   MMA_StreamHandle       (V50) [I.G.Q], ULONG, required on init (2)
   MMA_StreamLength       (V50) [I.G.Q], QUAD*, required on init
   MMA_StreamPosBytes     (V50) [..G.Q], QUAD*, optional on init
   MMA_StreamSeekable     (V51) [..G.Q], BOOL

   (1) required if MMA_StreamHandle not specified
   (2) required if MMA_StreamName not specified

NEW METHODS

   MMM_Pull(port, buffer, length)            (V50)
   MMM_Seek(port, type, position)            (V51)