src/filters/BaseClasses/pstream.h

   1 //------------------------------------------------------------------------------
   2 // File: PStream.h
   3 //
   4 // Desc: DirectShow base classes - defines a class for persistent properties
   5 //       of filters.
   6 //
   7 // Copyright (c) 1992-2002 Microsoft Corporation.  All rights reserved.
   8 //------------------------------------------------------------------------------
   9
  10
  11 #ifndef __PSTREAM__
  12 #define __PSTREAM__
  13
  14 // Base class for persistent properties of filters
  15 // (i.e. filter properties in saved graphs)
  16
  17 // The simplest way to use this is:
  18 // 1. Arrange for your filter to inherit this class
  19 // 2. Implement in your class WriteToStream and ReadFromStream
  20 //    These will override the "do nothing" functions here.
  21 // 3. Change your NonDelegatingQueryInterface to handle IPersistStream
  22 // 4. Implement SizeMax to return the number of bytes of data you save.
  23 //    If you save UNICODE data, don't forget a char is 2 bytes.
  24 // 5. Whenever your data changes, call SetDirty()
  25 //
  26 // At some point you may decide to alter, or extend the format of your data.
  27 // At that point you will wish that you had a version number in all the old
  28 // saved graphs, so that you can tell, when you read them, whether they
  29 // represent the old or new form.  To assist you in this, this class
  30 // writes and reads a version number.
  31 // When it writes, it calls GetSoftwareVersion()  to enquire what version
  32 // of the software we have at the moment.  (In effect this is a version number
  33 // of the data layout in the file).  It writes this as the first thing in the data.
  34 // If you want to change the version, implement (override) GetSoftwareVersion().
  35 // It reads this from the file into mPS_dwFileVersion before calling ReadFromStream,
  36 // so in ReadFromStream you can check mPS_dwFileVersion to see if you are reading
  37 // an old version file.
  38 // Normally you should accept files whose version is no newer than the software
  39 // version that's reading them.
  40
  41
  42 // CPersistStream
  43 //
  44 // Implements IPersistStream.
  45 // See 'OLE Programmers Reference (Vol 1):Structured Storage Overview' for
  46 // more implementation information.
  47 class CPersistStream : public IPersistStream {
  48     private:
  49
  50         // Internal state:
  51
  52     protected:
  53         DWORD     mPS_dwFileVersion;         // version number of file (being read)
  54         BOOL      mPS_fDirty;
  55
  56     public:
  57
  58         // IPersistStream methods
  59
  60         STDMETHODIMP IsDirty()
  61             {return (mPS_fDirty ? S_OK : S_FALSE);}  // note FALSE means clean
  62         STDMETHODIMP Load(LPSTREAM pStm);
  63         STDMETHODIMP Save(LPSTREAM pStm, BOOL fClearDirty);
  64         STDMETHODIMP GetSizeMax(ULARGE_INTEGER * pcbSize)
  65                          // Allow 24 bytes for version.
  66                          { pcbSize->QuadPart = 12*sizeof(WCHAR)+SizeMax(); return NOERROR; }
  67
  68         // implementation
  69
  70         CPersistStream(IUnknown *punk, HRESULT *phr);
  71         ~CPersistStream();
  72
  73         HRESULT SetDirty(BOOL fDirty)
  74             { mPS_fDirty = fDirty; return NOERROR;}
  75
  76
  77         // override to reveal IPersist & IPersistStream
  78         // STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void **ppv);
  79
  80         // --- IPersist ---
  81
  82         // You must override this to provide your own class id
  83         STDMETHODIMP GetClassID(CLSID *pClsid) PURE;
  84
  85         // overrideable if you want
  86         // file version number.  Override it if you ever change format
  87         virtual DWORD GetSoftwareVersion(void) { return 0; }
  88
  89
  90         //=========================================================================
  91         // OVERRIDE THESE to read and write your data
  92         // OVERRIDE THESE to read and write your data
  93         // OVERRIDE THESE to read and write your data
  94
  95         virtual int SizeMax() {return 0;}
  96         virtual HRESULT WriteToStream(IStream *pStream);
  97         virtual HRESULT ReadFromStream(IStream *pStream);
  98         //=========================================================================
  99
 100     private:
 101
 102 };
 103
 104
 105 // --- Useful helpers ---
 106
 107
 108 // Writes an int to an IStream as UNICODE.
 109 STDAPI WriteInt(IStream *pIStream, int n);
 110
 111 // inverse of WriteInt
 112 STDAPI_(int) ReadInt(IStream *pIStream, HRESULT &hr);
 113
 114 #endif // __PSTREAM__