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()
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.
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.
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.
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.
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.
Syntax
-
- Open(PIMoaStreamThis,
MoaLongaccessMode,
MoaLongsetPositionType)
Parameters
-
This
- Pointer to the
IMoaStream
interface
accessMode
MoaLong
Constant specifying the access mode
setPositionType
MoaLong
Constant 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.
Syntax
-
- Read(PIMoaStreamThis,
PMoaVoidpBuf,
MoaStreamCountnumToRead,
MoaStreamCount FAR *pNumActuallyRead)
Parameters
-
This
- Pointer to the
IMoaStream
interface
pBuf
PMoaVoid
Buffer to read data into
numToRead
MoaStreamCount
Data 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.
Syntax
-
- ReadAhead(PIMoaStreamThis,
PMoaVoidpBuf,
MoaStreamCountnumToRead,
MoaStreamCount FAR *pNumActuallyRead)
Parameters
-
This
- Pointer to the
IMoaStream
interface
pBuf
PMoaVoid
Buffer to read data into
numToRead
MoaStreamCount
Data 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.
Syntax
-
- SetPosition(PIMoaStreamThis,
MoaStreamPositionpos)
Parameters
-
This
- Pointer to the
IMoaStream
interface
pos
MoaStreamPosition
New 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.
Syntax
-
- Write(PIMoaStreamThis,
PMoaVoidpBuf,
MoaStreamCountnumToWrite,
MoaStreamCount FAR *pNumActuallyWritten)
Parameters
-
This
- Pointer to the
IMoaStream
interface
pBuf
PMoaVoid
Buffer to write data from
numToWrite
MoaStreamCount
Data 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.