CPersistStream is the base class for persistent properties of filters (that is, filter properties in saved graphs).
The simplest way to use CPersistStream is to:
If you save Unicode data, remember that a WCHAR is 2 bytes.
Version Numbers
At some point you might decide to alter or extend the format of your data. You will then wish you had a version number in all the old saved streams so you can tell, when you read them, whether they represent the old or new form. To assist you, this class writes and reads a version number. When it writes, it calls GetSoftwareVersion to inquire as to the version of the software being used 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 the version number 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. Usually you should accept files whose version is no newer than the software version that is reading them.
Protected Data Members
| Name | Description |
| mPS_dwFileVersion | Version number of the file. |
| mPS_fDirty | Data for this stream must be saved. |
Member Functions
| Name | Description |
| CPersistStream | Constructs a CPersistStream object. |
| SetDirty | Indicates that the object must be saved to the stream. |
Overridable Member Functions
| Name | Description |
| SizeMax | Returns the number of bytes needed for data (not including version number). |
| GetClassID | Returns the class identifier of this stream. |
| GetSoftwareVersion | Returns the version number for this file format. |
| ReadFromStream | Reads the filter's data from the stream. |
| WriteToStream | Writes the filter's data to the stream. |
CPersistStream implements IPersistStream. For more implementation information, see "OLE Programmers Reference (Vol. 1): Structured Storage Overview."
Implemented IPersistStream Methods
| Name | Description |
| GetSizeMax | Returns the number of bytes needed for data (including version number). |
| IsDirty | Checks if the object must be saved. |
| Load | Loads the data from the stream into memory. |
| Save | Saves the data from memory to the stream. |
Constructs a CPersistStream object.
CPersistStream(
IUnknown *pUnk,
HRESULT *phr
);
No return value.
Retrieves the class identifier for this filter.
HRESULT GetClassID(
CLSID *pClsID
);
Returns an HRESULT value.
Returns the maximum byte size needed for the current stream, including the version number.
HRESULT GetSizeMax(
ULARGE_INTEGER * pcbSize
);
Returns an HRESULT value.
This member function implements the IPersistStream::GetSizeMax method.
Returns the software version for this stream.
virtual DWORD GetSoftwareVersion(void);
Returns a DWORD containing the version number. Each time the format of the stream is changed, this function should be altered to return a larger number than before.
See Version Numbers for an explanation as to why file format version numbers are useful.
Indicates whether the object has changed since it was last saved to its current stream.
HRESULT IsDirty( );
Returns S_OK if the filter needs saving and S_FALSE if it does not need saving.
This member function implements the IPersistStream::IsDirty method.
Loads the filter's data from a given stream.
HRESULT Load(
LPSTREAM pStm
);
Returns an HRESULT value.
This member function implements the IPersistStream::Load method.
Reads the filter's data from the given stream.
virtual HRESULT ReadFromStream(
IStream *pStream
);
Returns NOERROR by default; the overriding member function should return a valid HRESULT value.
The default version reads nothing; it can be overridden to read data specific to your class.
Saves the filter's data to the given stream.
HRESULT Save(
LPSTREAM pStm,
BOOL fClearDirty
);
Returns an HRESULT value.
This member function implements the IPersistStream::Save method. It calls WriteInt with the software version, calls CPersistStream::WriteToStream with the stream in pStm, and resets mPS_fDirty.
Changes the dirty flag for the current stream.
HRESULT SetDirty(
BOOL fDirty
);
Returns an HRESULT value.
Retrieves the maximum byte size needed for the current stream, not including the version number.
virtual int SizeMax( );
Returns the number of bytes needed for data, not including the version number.
The default version returns zero; it should be overridden to provide some other appropriate value.
Writes the filter's data to the given stream.
virtual HRESULT WriteToStream(
IStream *pStream
);
Returns NOERROR by default; the overriding member function should return a valid HRESULT value.
The default version writes nothing; it can be overridden to write data specific to your class.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.