class IReadStream;

IStreamEngine.h

This is the file "handle" that can be used to query the status of the asynchronous operation on the file. The same object may be returned for the same file to multiple clients. Notes: It will actually represent the asynchronous object in memory, and will be thread-safe reference-counted (both AddRef() and Release() will be virtual and thread-safe, just like the others)

USE: IReadStream_AutoPtr pReadStream = pStreamEngine->StartRead ("bla.xxx", this); OR: pStreamEngine->StartRead ("MusicSystem","bla.xxx", this);

The clients are not allowed to destroy this object directly; only via Release().

virtual ~IReadStream();

virtual void Abort() = 0;

Tries to stop reading the stream; this is advisory and may have no effect but the callback will not be called after this. If you just destructing object, dereference this object and it will automatically abort and release all associated resources.

Increment ref count, returns new count

virtual int AddRef() = 0;

Free temporary memory allocated for this stream, when not needed anymore. Can be called from Async callback, to free memory earlier, not waiting for synchrounus callback.

virtual void FreeTemporaryMemory() = 0;

virtual const void* GetBuffer() = 0;

Returns the buffer into which the data has been or will be read at least GetBytesRead() bytes in this buffer are guaranteed to be already read. Notes: DO NOT USE THIS BUFFER during read operation! DO NOT READ from it, it can lead to memory corruption!

virtual unsigned int GetBytesRead(bool bWait = false) = 0;

The total number of bytes read (if it completes successfully, returns the size of block being read)

Returns the number of bytes read so far (the whole buffer size if IsFinished())

Returns pointer to callback routine(can be NULL).

virtual IStreamCallback* GetCallback() const = 0;

Returns caller type.

virtual const EStreamTaskType GetCallerType() const = 0;

Returns IO error #.

virtual unsigned GetError() const = 0;

Returns IO error name

virtual const char* GetErrorName() const = 0;

Returns media type used to satisfy request - only valid once stream has begun read.

virtual EStreamSourceMediaType GetMediaType() const = 0;

Returns stream name.

virtual const char* GetName() const = 0;

Returns stream params.

virtual const StreamReadParams& GetParams() const = 0;

virtual DWORD_PTR GetUserData() = 0;

Returns the transparent DWORD that was passed in the StreamReadParams::dwUserData field of the structure passed in the call to IStreamEngine::StartRead.

StreamReadParams::dwUserData,IStreamEngine::StartRead

Returns true if the file read was not successful.

virtual bool IsError() = 0;

Checks IsError to check if the whole requested file (piece) was read.

virtual bool IsFinished() = 0;

True if the file read was completed successfully.

Decrement ref count, returns new count

virtual int Release() = 0;

Set user defined data into stream's params.

virtual void SetUserData(DWORD_PTR dwUserData) = 0;

virtual bool TryAbort() = 0;

Tries to stop reading the stream, as long as IO or the async callback is not currently in progress.

Unconditionally waits until the callback is called. if nMaxWaitMillis is not negative wait for the specified ammount of milliseconds then exit.

virtual void Wait(int nMaxWaitMillis = -1) = 0;

If the stream hasn't yet finish, it's guaranteed that the user-supplied callback is called before return from this function (unless no callback was specified).