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(PIMoaStream2 This)

Parameters

This

Pointer to the IMoaStream2 interface

Returns

kMoaErr_NoErr	Success
kMoaStreamErr_StreamAlreadyOpen	Stream is already open

Description

Closes the stream.

CloseWithError()

Syntax

CloseWithError(PIMoaStream2 This,

MoaError err)

Parameters

This

Pointer to the IMoaStream2 interface

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(PIMoaStream2 This)

Parameters

This

Pointer to the IMoaStream2 interface

Returns

kMoaErr_NoErr	Success
kMoaStreamErr_StreamNotOpen	Stream no open

Description

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

GetCurrentLength()

Syntax

GetCurrentLength(PIMoaStream2 This,

MoaStreamPosition FAR *pPos) PURE; )

Parameters

This

Pointer to the IMoaStream2 interface

PURE;

MoaStreamPosition FAR *pPos)

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(PIMoaStream2 This,

MoaStreamPosition FAR * pPos)

Parameters

This

Pointer to the IMoaStream2 interface

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(PIMoaStream2 This,

PIMoaIOAttributeDict FAR *ppIDict)

Parameters

This

Pointer to the IMoaStream2 interface

*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(PIMoaStream2 This,

MoaLong FAR * pAccessMode,
MoaLong FAR * pSetPositionType)

Parameters

This

Pointer to the IMoaStream2 interface

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(PIMoaStream2 This,

MoaStreamPosition FAR * pPos)

Parameters

This

Pointer to the IMoaStream2 interface

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(PIMoaStream2 This,

MoaLong accessMode,
MoaLong setPositionType)

Parameters

This

Pointer to the IMoaStream2 interface

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 access mode paramater indicates the type of access required for the stream. Valid access modes are: Read - Stream will only be read from Write - Stream will only be written to ReadWrite - Stream will be read from and written to The set position parameter determines what set position mode to use with the stream. Valid set position modes are: None - SetPosition will never be called. Cheap - Set position will be called often Expensive - Set position will be called occasionally

Read()

Syntax

Read(PIMoaStream2 This,

PMoaVoid pBuf,
MoaStreamCount numToRead,
MoaStreamCount FAR * pNumActuallyRead)

Parameters

This

Pointer to the IMoaStream2 interface

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 numActuallyRead. The position will be incremented to reflect the number of bytes read from the stream.

ReadAhead()

Syntax

ReadAhead(PIMoaStream2 This,

PMoaVoid pBuf,
MoaStreamCount numToRead,
MoaStreamCount FAR * pNumActuallyRead)

Parameters

This

Pointer to the IMoaStream2 interface

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_ReadAheadTooFar	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 numActuallyRead. The position is not incremented when performing a ReadAhead().

ReadOperation()

Syntax

ReadOperation(PIMoaStream2 This,

PMoaStreamIOOperation pOperation)

Parameters

This

Pointer to the IMoaStream2 interface

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: IOOperations that are synchronous (blocking) and un-bufferred IOOperations that are asynchronous (non-blocking) IOOperations that are bufferred IOOperations that are provide direct access to a stream's buffer The asynchronous, bufferred and direct-access modes are optional per implementation. Their availability can be queried using the MoaDict 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: - ioFlags: the I/O mode (as described above) - ioRequestCount: the number of bytes to be transferred or for direct-access mode, bytes to be accessed in the stream buffer - pClientBuffer: the destination for the data that will be read, ignored for direct-access mode - pCompletionProc: a function to be called when an asynchronous read has completed only called if the read was actually asynchronous. - pClientData: any piece of data to be passed to the pCompletionProc. Upon return, the output fields of the MoaStreamIOOperation structure are set as follows: - ioResult: the result of the I/O operation (should match return value on synchronous reads) - actualIOCount: the actual number of bytes transferred or for direct-access mode, bytes made available in the stream buffer - pStreamBuffer: a pointer to a region of the stream's buffer, the size of the region is returned in the actualIOCount field.

ReleaseStreamBuffer()

Syntax

ReleaseStreamBuffer(PIMoaStream2 This,

PMoaStreamIOOperation pOperation)

Parameters

This

Pointer to the IMoaStream2 interface

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 MoaStream2 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(PIMoaStream2 This,

MoaStreamPosition pos)

Parameters

This

Pointer to the IMoaStream2 interface

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(PIMoaStream2 This,

MoaStreamPosition pos)

Parameters

This

Pointer to the IMoaStream2 interface

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(PIMoaStream2 This,

MoaStreamPosition pos,
MoaStreamPositionMode mode)

Parameters

This

Pointer to the IMoaStream2 interface

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: kMoaStreamPositionMode_FromStart kMoaStreamPositionMode_FromCurrent kMoaStreamPositionMode_FromEnd

Write()

Syntax

Write(PIMoaStream2 This,

PMoaVoid pBuf,
MoaStreamCount numToWrite,
MoaStreamCount FAR * pNumActuallyWritten)

Parameters

This

Pointer to the IMoaStream2 interface

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 numActuallyWritten. The stream position is updated to reflect the number of bytes written to the stream.

WriteOperation()

Syntax

WriteOperation(PIMoaStream2 This,

PMoaStreamIOOperation pOperation)

Parameters

This

Pointer to the IMoaStream2 interface

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: IOOperations that are synchronous (blocking) and un-bufferred IOOperations that are asynchronous (non-blocking) IOOperations that are bufferred IOOperations that are provide direct access to a stream's buffer The asynchronous, bufferred and direct-access modes are optional per implementation. Their availability can be queried using the MoaDict 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: - ioFlags: the I/O mode (as described above) - ioRequestCount: the number of bytes to be transferred or for direct-access mode, bytes to be accessed in the stream buffer - pClientBuffer: the source for the data that will be written, ignored for direct-access mode. - pCompletionProc: a function to be called when an asynchronous write has completed only called if the write was actually asynchronous. - pClientData: any piece of data to be passed to the pCompletionProc. Upon return, the output fields of the MoaStreamIOOperation structure are set as follows: - ioResult: the result of the I/O operation (should match return value on synchronous writes) - actualIOCount: the actual number of bytes transferred or for direct-access mode, bytes made be available in the stream buffer - pStreamBuffer: a pointer to a region of the stream's buffer, the size of the region is returned in the actualIOCount field.