MOA Developer's Guide
MOA Interfaces | MOA Methods | MOA Types and Misc API

IMoaStream


Interface ID: IID_IMoaStream
Pointer type: PIMoaStream
Inheritance: IMoaUnknown
Header file: moastdif.h

Description


The IMoaStream interface is designed as a universal interface for streaming data to all MOA-enabled documents. This interface may be implemented for accessing data in a disk file, memory structure, internet site, etc. The IMoaStream interface is designed to totally encapsulate the nature of the data being read or written. It provides techniques for random access of the data, though specific implementations may not enable these random access techniques.

Note: Specific providers of this interface may include certain implementation details worth noting. These distinctions are documented with the XDK for a specific implementation.

See also

IMoaStream types, IMoaStream constants, IMoaStream errors

Methods

Opening and closing

Open()
Close()

Accessing data

Read()
ReadAhead()

Writing data

Write()
Flush()

Positioning

GetPosition()
SetPosition()
GetEnd()

Determining capabilities

GetModes()

Close()

Syntax

Close(PIMoaStreamThis)

Parameters

This
Pointer to the IMoaStream interface

Returns

MoaError

Description

Call this method when through using the stream. It does not necessarily flush the stream; you should explicitly call Flush()to force a write of all data.

Flush()

Syntax

Flush(PIMoaStreamThis)

Parameters

This
Pointer to the IMoaStream interface

Returns

MoaError

Description

Flushes any buffered data stored in the stream. Call this to ensure that data written to the stream is passed all the way through.

GetEnd()

Syntax

GetEnd(PIMoaStreamThis,

MoaStreamPosition FAR *pPos)

Parameters

This
Pointer to the IMoaStream interface

pPos
MoaStreamPosition FAR *Offset of the end of the data

Returns

MoaError

Description

The GetEnd() method gets the position of the current end-of-stream. Attempting to read past this position will fail. Attempting to write past this position may or may not succeed, depending on the nature of the media. Streams opened with kMoaStreamSetPositionType_None may return kMoaStreamErr_NoSetPosition.

GetModes()

Syntax

GetModes(PIMoaStreamThis,

MoaLong FAR *pAccessMode,
MoaLong FAR *pSetPositionType)

Parameters

This
Pointer to the IMoaStream interface

pAccessMode
MoaLong FAR *Returns the access mode

pSetPositionType
MoaLong FAR *Returns the seek type

Returns

MoaError

Description

Call this method to get the access mode (in pAccessMode) and seek mode (in pSetPositionType) that were specified when Open() was called on the IMoaStream This.

GetPosition()

Syntax

GetPosition(PIMoaStreamThis,

MoaStreamPosition FAR *pPos)

Parameters

This
Pointer to the IMoaStream interface

pPos
MoaStreamPosition FAR *Returns current position

Returns

MoaError

Description

Call this method to acquire, in pPos, the current position in the stream from which reads or writes will take place. Note that this is a 32-bit unsigned integer that is always an absolute offset from the start of the stream.

Open()

Syntax

Open(PIMoaStreamThis,

MoaLongaccessMode,
MoaLongsetPositionType)

Parameters

This
Pointer to the IMoaStream interface

accessMode
MoaLongConstant specifying the access mode

setPositionType
MoaLongConstant specifying the seek type

Returns

MoaError

Description


The Open() method opens the stream for reading or writing. You must open the stream before calling other methods on it. The parameter pAccessMode specifies the access mode (read, write, or read/write). Use one of the access mode constants described below for this parameter.

The pSetPositionType parameter specifies the seekability provided by SetPosition(). Use one of the set position constants described below for this parameter. Providing the appropriate constant enables the stream to optimize for particular seeking needs. However, not all streams support all seekability modes. More specifically, a stream may not support seeking at all, or may support only "expensive" seeking. If you specify an unavailable seek mode, Open() returns an error.


Read()

Syntax

Read(PIMoaStreamThis,

PMoaVoidpBuf,
MoaStreamCountnumToRead,
MoaStreamCount FAR *pNumActuallyRead)

Parameters

This
Pointer to the IMoaStream interface

pBuf
PMoaVoidBuffer to read data into

numToRead
MoaStreamCountData size requested

pNumActuallyRead
MoaStreamCount FAR *Data size delivered

Returns

MoaError

Description


Call this method to read data from the stream. This method has slightly different semantics depending on the pNumActuallyRead parameter:

If you pass NULL for pNumActuallyRead, then Read() attempts to read exactly numToRead bytes from the current position in the stream and copy them into the buffer. If there aren't enough bytes remaining (i.e., you read past the end), kMoaStreamErr_ReadPastEnd is returned (whether or not data is copied into the buffer is undefined).

If you pass a value for pNumActuallyRead, then Read() will read as much as can be read "quickly", perhaps returning pNumActuallyRead < numToRead without an error indication. Reading past the end of the stream will return kMoaStreamErr_ReadPastEnd with pNumActuallyRead set correctly. Note that "quickly" is implementation-defined.

In all cases, if the return value is kMoaErr_NoErr or kMoaStreamErr_ReadPastEnd, the stream position is set to the first byte past the data read; otherwise, the stream position is unchanged.


ReadAhead()

Syntax

ReadAhead(PIMoaStreamThis,

PMoaVoidpBuf,
MoaStreamCountnumToRead,
MoaStreamCount FAR *pNumActuallyRead)

Parameters

This
Pointer to the IMoaStream interface

pBuf
PMoaVoidBuffer to read data into

numToRead
MoaStreamCountData size requested

pNumActuallyRead
MoaStreamCount FAR *Data size delivered

Returns

MoaError

Description

This method is similar to Read(), except that the stream position is never advanced, even if the read is successful. This call is particularly useful with non-seek (or expensive-seek) streams. Note that you are only guaranteed to be able to read amounts of kMoaStreamReadAheadLimit or less (defined as 32); some streams may allow more, but it is not guaranteed. If you ask for more than the stream supports, it will return kMoaStreamErr_ReadAheadTooFar.

SetPosition()

Syntax

SetPosition(PIMoaStreamThis,

MoaStreamPositionpos)

Parameters

This
Pointer to the IMoaStream interface

pos
MoaStreamPositionNew position requested

Returns

MoaError

Description

Call this method to set the position in the stream from which subsequent reads or writes will begin. The pos specified is a 32-bit unsigned integer that is always an absolute offset from the start of the stream. Note: it is legal to set the position outside the end of the stream; however, an attempt to read from such a position will return an error. Note: streams opened with kMoaStreamSetPositionType_None will always return kMoaStreamErr_NoSetPosition.

Write()

Syntax

Write(PIMoaStreamThis,

PMoaVoidpBuf,
MoaStreamCountnumToWrite,
MoaStreamCount FAR *pNumActuallyWritten)

Parameters

This
Pointer to the IMoaStream interface

pBuf
PMoaVoidBuffer to write data from

numToWrite
MoaStreamCountData size to be delivered

pNumActuallyWritten
MoaStreamCount FAR *Data size delivered

Returns

MoaError

Description

Call this method to write data to the stream This. This method attempts to write numToWrite bytes to the current position in the stream and advances the stream position by that number of bytes. An attempt to write past the end of the stream extends the stream length before writing (if possible). If the write is successful, the stream position is set to the first byte past the data written. If the write is unsuccessful, the stream position is unchanged. If pNumActuallyWritten is not NULL, it will be set to the number of bytes actually written.


Copyright © 1995-2007 Adobe Macromedia Software LLC, Inc.