StreamInterfaces.h

// StreamInterfaces.h
//
// Author David Barrett-Lennard
// (C)opyright Cedanet Pty Ltd 2004

#pragma once
#ifndef Ceda_cxUtils_StreamInterfaces_H
#define Ceda_cxUtils_StreamInterfaces_H

#include "cxUtils.h"
#include "IException.h"

namespace ceda
{

///////////////////////////////////////////////////////////////////////////////////////////////////
// IInputStream

// An input byte stream.
// The stream is closed (if necessary) when the interface ptr is deleted
struct IInputStream
{
    virtual ~IInputStream() {}

	// Try to read numBytesRequested from the stream.  Returns the actual number of bytes read 
    // which may be less than numBytesRequested, indicating the end of stream.  This implies that
	// streams representing I/O (e.g. sockets) must block until numBytesRequested is available.
	//
	// This method must not throw exceptions.
	virtual ssize_t ReadStream(void* buffer, ssize_t numBytesRequested) = 0;
};


///////////////////////////////////////////////////////////////////////////////////////////////////
// ISeekableInputStream

// An input byte stream that allows the current position (relative to the start of the stream) to 
// be get/set.
struct ISeekableInputStream : public IInputStream
{
    // Get the total length of the stream
    virtual ssize_t GetStreamLength() const = 0;

    virtual ssize_t GetStreamPosition() const = 0;
    virtual void SetStreamPosition(ssize_t pos) = 0;
};


///////////////////////////////////////////////////////////////////////////////////////////////////
// IOutputStream

// An output byte stream.
// The stream is closed (if necessary) when the interface ptr is deleted
struct IOutputStream
{
    virtual ~IOutputStream() {}

    virtual void WriteStream(const void* buffer, ssize_t numBytes) = 0;
    virtual void FlushStream() = 0;
};


///////////////////////////////////////////////////////////////////////////////////////////////////
// Closeable streams

// These interfaces are used at cross-dll boundaries, and in particular where one dll gives out
// a stream to be used by a different dll.  When the stream is no longer required it must be closed
// but not deleted by the client!  This allows the dlls to employ different heap implementations.
// It is assumed that closing the stream implicitly deletes it.

struct ICloseableInputStream : public IInputStream
{
    virtual void Close() = 0;
};

struct ICloseableSeekableInputStream : public ISeekableInputStream
{
    virtual void Close() = 0;
};

struct ICloseableOutputStream : public IOutputStream
{
    virtual void Close() = 0;
};

///////////////////////////////////////////////////////////////////////////////////////////////////
// StreamClosedException

class cxUtils_API StreamClosedException : public IException
{
public:
    virtual void Write(xostream& os) const;
};

} // namespace ceda

#endif // include guard