/***************************************************************************
 *                          Zanoza Modeler v2.x                            *
 *      This is unpublished propietary source code of Zanoza Software.     *
 *      The copyright notice does not evidence any actual or intended      *
 *                    publication of such source code.                     *
 *                                                                         *
 *                Copyright (c) 2002-2008 Zanoza Software.                 *
 *                                                                         *
 *                        All rights reserved.                             *
 ***************************************************************************
 *--------------------------------------------------------------------------
 * @author:   Oleg Melashenko
 *--------------------------------------------------------------------------
 * @purpose:  Declaration of the class IStream
 *   Basic streaming interface
 *--------------------------------------------------------------------------
 * @created: Tuesday, September 24, 2002 00:28:33
 */

#if !defined(IStream_h_included)
#define IStream_h_included
//forward declaration of this class might require
namespace core
{ namespace io
  { class IStream; }; };
#include <zmodeler.h>
#include <core/io/zmIOTypes.h>

namespace core
{
  namespace io
  {
    
    class IStream : public ZUnknown
    {
    public:
      /* Opens a stream on opaque resource. Different implementations treat supplied
       * resource string in variouse ways. e.g. filestrem treats it as pathname.
       * bReadOnly: true to create a read-stream, false to read-write.
       * bEraseExisten: true to erase existing resource (if exist) when opening read-write; false to open existen */
      virtual ZRESULT open(ZString strResource, bool bReadOnly=true, bool bEraseExisten=true, bool bNeedSeek=false)=0;
      virtual ZRESULT getResource(ZString& szResource)=0;
      /* Opens a stream on supplied stream resouce. The most recent base stream
       * resource is a file stream. If reading from stream expected, nReadLimit must be
       * set to non-zero value. */
      virtual ZRESULT subStream(core::io::IStream* pBaseStream, long nReadLimit=0)=0;
      virtual ZRESULT close(void)=0;
      virtual long getLength(void)=0;
      /* Sets the length of the stream. if stream is used to read data, 
       * this length limits the quantity of data could be read. */
      virtual ZRESULT setLength(long nLen)=0;
      /* Seek from current position to supplied offset */
      virtual ZRESULT seekOffset(long nSignedOffset)=0;
      /* Seek from start to supplied offset */
      virtual ZRESULT seekTo(DWORD dwPosition)=0;
      virtual long getPosition(void)=0;
      virtual ZRESULT read(ZOpaque* pBuf, long nCount, long* pReadCount=NULL)=0;
      virtual ZRESULT write(const ZOpaque* pBuf, const long nCount, long* pWrittenCount=NULL)=0;
      /* Unmarks position as seek-back point. see markSeekBackPosition for more details. */
      virtual ZRESULT unmarkSeekBackPosition(const DWORD dwPosition=0)=0;
      /* Marks current position as seek-back point. this is the location in stream where
       * write-process will seek back afterward. This mark forces non-seekable streams
       * to start accurmulating data in memory until seek-back indicators are removed
       * and data can be processed by the stream. This limitation applies to CZIPStream,
       * CHTTPStream etc. */
      virtual ZRESULT markSeekBackPosition(const long nPlusOffset=0)=0;
    
    };//class IStream
  };//io
};//core

#endif
