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

IMoaStream2

Interface ID: IID_IMoaStream2
Pointer type: PIMoaStream2
Inheritance: IMoaStream
Header file: moastr2.h

Methods

Open()
Close()
Read()
ReadAhead()
Write()
GetPosition()
SetPosition()
GetEnd()
Flush()
GetModes()
SetPositionRelative()
SetEnd()
GetCurrentLength()
CloseWithError()
GetMoaIOAttributeDict()
ReadOperation()
WriteOperation()
ReleaseStreamBuffer()

Close()

Syntax

Close()

Parameters

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamAlreadyOpen Stream is already open

Description

Closes the stream.

CloseWithError()

Syntax

CloseWithError(MoaError err)

Parameters

err
error code

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen Stream no open

Description

Closes the stream with an error condition of err. Used for closing streams used as pipes or as transformers between pull-mode and push-mode streams. The producer should call CloseWithError with a termination error, which in turn will be passed to the consumer on the next stream operation.

Flush()

Syntax

Flush()

Parameters

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen Stream no open

Description

Forces any data not written to the stream to be written.

GetCurrentLength()

Syntax

GetCurrentLength(MoaStreamPosition *pPos)

Parameters

pPos
on return gets the availble length of the stream

Returns

kMoaErr_NoErr Success
kMoaStreamErr_IoError catch-all r/w/pos error

Description

Gets the available length of the stream, which might be different from its total length, esp. for streams on remote objects.

GetEnd()

Syntax

GetEnd(MoaStreamPosition * pPos)

Parameters

pPos
on return contains stream position

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen Stream no open
kMoaStreamErr_IoError catch-all r/w/pos error

Description

Returns the position of the end of the stream.

GetMoaIOAttributeDict()

Syntax

GetMoaIOAttributeDict(PIMoaIOAttributeDict *ppIDict)

Parameters

ppIDict
on return contains IMoaIOAttributeDict pointer

Returns

kMoaErr_NoErr Success or standard MOA QueryInterface errors

Description

Returns an IMoaIOAttributeDict interface which is used to enumerate through various stream and file attributes. This interface is identical to IMoaDict. The client is responsible for releasing this interface when done. For a list of IO attributes, see Types and Miscellaneous API.

GetModes()

Syntax

GetModes(MoaLong * pAccessMode, MoaLong * pSetPositionType)

Parameters

pAccessMode
on return contains access mode

pSetPositionType
on return contains set position type

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen Stream no open

Description

Returns the access mode and set position type for the current stream.

GetPosition()

Syntax

GetPosition(MoaStreamPosition * pPos)

Parameters

pPos
on return contains stream position

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen Stream no open
kMoaStreamErr_IoError catch-all r/w/pos error

Description

Returns the current position in the stream.

Open()

Syntax

Open(MoaLong accessMode, MoaLong setPositionType)

Parameters

accessMode
access mode for the stream

setPositionType
set position type for the stream

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamAlreadyOpen Stream is already open
kMoaStreamErr_BadAccessMode not an allowable r/w perm
kMoaStreamErr_BadSetPositionMode not an allowable seek perm

Description

Opens the stream. The accessMode parameter indicates the type of access required for the stream. Valid access modes are:
The setPositionType parameter determines what set position mode to use with the stream. Valid set position modes are:

Read()

Syntax

Read(PMoaVoid pBuf, MoaStreamCount numToRead, MoaStreamCount * pNumActuallyRead)

Parameters

pBuf
pointer to buffer for data

numToRead
number of bytes to read from stream

pNumActuallyRead
number of bytes actually read

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen returned by everything but Open
kMoaStreamErr_BadParameter you passed me bad parm
kMoaStreamErr_IoError catch-all r/w/pos error
kMoaStreamErr_ReadPastEnd attempted to read past end
kMoaStreamErr_DataNotAvail attempted to read past current length (partially downloaded streams)

Description

Attempts to read numToRead bytes from the stream and write them into the buffer passed in. The number of bytes actually read from the stream is return in pNumActuallyRead. The position will be incremented to reflect the number of bytes read from the stream.

ReadAhead()

Syntax

ReadAhead(PMoaVoid pBuf, MoaStreamCount numToRead, MoaStreamCount * pNumActuallyRead)

Parameters

pBuf
pointer to buffer for data

numToRead
number of bytes to read from stream

pNumActuallyRead
number of bytes actually read

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen returned by everything but Open
kMoaStreamErr_BadParameter you passed me bad parm
kMoaStreamErr_IoError catch-all r/w/pos error
kMoaStreamErr_ReadPastEnd attempted to read past end
kMoaStreamErr_ReadAheadToo you asked for too much ReadAhead
kMoaStreamErr_DataNotAvail attempted to read past current length (partially downloaded streams)

Description

Attempts to read numToRead bytes from the stream and write them into the buffer passed in. The number of bytes actually read from the stream is return in pNumActuallyRead. The position is not incremented when performing a ReadAhead().

ReadOperation()

Syntax

ReadOperation(PMoaStreamIOOperation pOperation)

Parameters

pOperation
pointer to an MoaStreamIOOperation structure

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen returned by everything but Open
kMoaStreamErr_BadParameter - you passed me bad parm
kMoaStreamErr_IoError catch-all r/w/pos error
kMoaStreamErr_ReadPastEnd attempted to read past end
kMoaStreamErr_DataNotAvail attempted to read past current length (partially downloaded streams) Sets output fields of MoaStreamIOOperation structure.

Description

Performs a READ operation using parameters specified by the MoaStreamIOOperation structure. There are 4 basic modes of I/O specified using the ioFlags parameter: The asynchronous, bufferred and direct-access modes are optional per implementation. Their availability can be queried using the IMoaDict returned by GetMoaIOAttributeDict(). The asynchronous and buffered modes can be combined to request async, buffered I/O. The direct-access mode can be used to bypass memory copies that would normally result in bufferred operation between a stream's buffer and a client's buffer. Direct-Access mode cannot be combined with any other modes.

The client must also specify other inputs in MoaStreamIOOperation structure:
Upon return, the output fields of the MoaStreamIOOperation structure are set as follows:

ReleaseStreamBuffer()

Syntax

ReleaseStreamBuffer(PMoaStreamIOOperation pOperation)

Parameters

pOperation
pointer to an MoaStreamIOOperation structure

Returns

kMoaErr_NoErr Success

Description

This method will only be supported by stream implementations that support direct-access mode MoaIOStreamOperations. After a IMoaStream2 client has acquired a region of a stream's buffer for read or write, the client will read from (or write to) the buffer, then the client must return that region of the stream's buffer back to the stream implementation. This method returns the stream buffer region specified by the pOperation parameter back to the stream implementation. The pOperation structure must have been used by the client for a direct-access read or write to the stream's buffer.

SetEnd()

Syntax

SetEnd(MoaStreamPosition pos)

Parameters

pos
new stream extent

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen Stream no open
kMoaStreamErr_IoError catch-all r/w/pos error

Description

Sets the end of the stream.

SetPosition()

Syntax

SetPosition(MoaStreamPosition pos)

Parameters

pos
new stream position

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen Stream no open
kMoaStreamErr_IoError catch-all r/w/pos error

Description

Sets the current stream position to pos.

SetPositionRelative()

Syntax

SetPositionRelative(MoaStreamPosition pos, MoaStreamPositionMode mode)

Parameters

pos
new stream position offset
mode
new stream position mode

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen Stream no open
kMoaStreamErr_IoError catch-all r/w/pos error

Description

Sets the stream position relative to the stream position mode. Valid stream position modes are:

Write()

Syntax

Write(PMoaVoid pBuf, MoaStreamCount numToWrite, MoaStreamCount * pNumActuallyWritten)

Parameters

pBuf
buffer to be written in to stream

numToWrite
number of bytes to write

pNumActuallyWritten
number of bytes written

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen returned by everything but Open
kMoaStreamErr_BadParameter you passed me bad parm
kMoaStreamErr_IoError catch-all r/w/pos error
kMoaStreamErr_WrotePastEnd attempted to write past end

Description

Attempts to write numToWrite bytes into the stream. The number of bytes actually written to the stream is returned in *pNumActuallyWritten. The stream position is updated to reflect the number of bytes written to the stream.

WriteOperation()

Syntax

WriteOperation(PMoaStreamIOOperation pOperation)

Parameters

pOperation
pointer to an MoaStreamIOOperation structure

Returns

kMoaErr_NoErr Success
kMoaStreamErr_StreamNotOpen returned by everything but Open
kMoaStreamErr_BadParameter you passed me bad parm
kMoaStreamErr_IoError catch-all r/w/pos error
kMoaStreamErr_WrotePastEnd attempted to write past end

Description

Performs a WRITE operation using parameters specified by the MoaStreamIOOperation structure. There are 4 basic modes of I/O specified using the ioFlags parameter: The asynchronous, bufferred and direct-access modes are optional per implementation. Their availability can be queried using the IMoaDict returned by GetMoaIOAttributeDict(). The asynchronous and buffered modes can be combined to request async, buffered I/O. The direct-access mode can be used to bypass memory copies that would normally result in bufferred operation between a stream's buffer and a client's buffer. Direct-Access mode cannot be combined with any other modes.

The client must also specify other inputs in MoaStreamIOOperation structure:
Upon return, the output fields of the MoaStreamIOOperation structure are set as follows:

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