Debian Codegraph @

sys/directshow/strmbase/baseclasses/pstream.h

raw
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-2001 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(__out 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, __inout 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(__out 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, __out HRESULT &hr);
113
114 #endif // __PSTREAM__