PSTREAM.H

//==========================================================================; 
// 
//  THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY 
//  KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
//  IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR 
//  PURPOSE. 
// 
//  Copyright (c) 1992 - 1997  Microsoft Corporation.  All Rights Reserved. 
// 
//--------------------------------------------------------------------------; 
 
#ifndef __PSTREAM__ 
#define __PSTREAM__ 
 
// Base class for persistent properties of filters 
// (i.e. filter properties in saved graphs) 
 
// The simplest way to use this is: 
// 1. Arrange for your filter to inherit this class 
// 2. Implement in your class WriteToStream and ReadFromStream 
//    These will override the "do nothing" functions here. 
// 3. Change your NonDelegatingQueryInterface to handle IPersistStream 
// 4. Implement SizeMax to return the number of bytes of data you save. 
//    If you save UNICODE data, don't forget a char is 2 bytes. 
// 5. Whenever your data changes, call SetDirty() 
// 
// At some point you may decide to alter, or extend the format of your data. 
// At that point you will wish that you had a version number in all the old 
// saved graphs, so that you can tell, when you read them, whether they 
// represent the old or new form.  To assist you in this, this class 
// writes and reads a version number. 
// When it writes, it calls GetSoftwareVersion()  to enquire what version 
// of the software we have at the moment.  (In effect this is a version number 
// of the data layout in the file).  It writes this as the first thing in the data. 
// If you want to change the version, implement (override) GetSoftwareVersion(). 
// It reads this from the file into mPS_dwFileVersion before calling ReadFromStream, 
// so in ReadFromStream you can check mPS_dwFileVersion to see if you are reading 
// an old version file. 
// Normally you should accept files whose version is no newer than the software 
// version that's reading them. 
 
 
// CPersistStream 
// 
// Implements IPersistStream. 
// See 'OLE Programmers Reference (Vol 1):Structured Storage Overview' for 
// more implementation information. 
class CPersistStream : public IPersistStream { 
    private: 
 
        // Internal state: 
 
    protected: 
        DWORD     mPS_dwFileVersion;         // version number of file (being read) 
        BOOL      mPS_fDirty; 
 
    public: 
 
        // IPersistStream methods 
 
        STDMETHODIMP IsDirty() 
            {return (mPS_fDirty ? S_OK : S_FALSE);}  // note FALSE means clean 
        STDMETHODIMP Load(LPSTREAM pStm); 
        STDMETHODIMP Save(LPSTREAM pStm, BOOL fClearDirty); 
        STDMETHODIMP GetSizeMax(ULARGE_INTEGER * pcbSize) 
                         // Allow 24 bytes for version. 
                         { pcbSize->QuadPart = 12*sizeof(WCHAR)+SizeMax(); return NOERROR; } 
 
        // implementation 
 
        CPersistStream(IUnknown *punk, HRESULT *phr); 
        ~CPersistStream(); 
 
        HRESULT SetDirty(BOOL fDirty) 
            { mPS_fDirty = fDirty; return NOERROR;} 
 
 
        // override to reveal IPersist & IPersistStream 
        // STDMETHODIMP NonDelegatingQueryInterface(REFIID riid, void **ppv); 
 
        // --- IPersist --- 
 
        // You must override this to provide your own class id 
        STDMETHODIMP GetClassID(CLSID *pClsid) PURE; 
 
        // overrideable if you want 
        // file version number.  Override it if you ever change format 
        virtual DWORD GetSoftwareVersion(void) { return 0; } 
 
 
        //========================================================================= 
        // OVERRIDE THESE to read and write your data 
        // OVERRIDE THESE to read and write your data 
        // OVERRIDE THESE to read and write your data 
 
        virtual int SizeMax() {return 0;} 
        virtual HRESULT WriteToStream(IStream *pStream); 
        virtual HRESULT ReadFromStream(IStream *pStream); 
        //========================================================================= 
 
    private: 
 
}; 
 
 
// --- Useful helpers --- 
 
 
// Writes an int to an IStream as UNICODE. 
STDAPI WriteInt(IStream *pIStream, int n); 
 
// inverse of WriteInt 
STDAPI_(int) ReadInt(IStream *pIStream, HRESULT &hr); 
 
#endif // __PSTREAM__