CPersistStream class

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

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:

1. Arrange for your filter to inherit this class.

2. Implement WriteToStream and ReadFromStream in your class. These will override the functions here, which do nothing but act as placeholders.

3. Change your NonDelegatingQueryInterface to handle IPersistStream.

4. Implement SizeMax to return an upper bound on the number of bytes of data you save.

   If you save Unicode™ data, remember that a WCHAR is 2 bytes.

5. When your data changes, call SetDirty.

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.

CPersistStream implements IPersistStream. For more implementation information, see the COM Reference in the Microsoft Platform SDK.

Protected Data Members	Description
mPS_dwFileVersion	Version number of the file.
mPS_fDirty	Data for this stream must be saved.
Member Functions	Description
CPersistStream	Constructs a CPersistStream object.
SetDirty	Indicates that the object must be saved to the stream.
Overridable Member Functions	Description
GetClassID	Retrieves the class identifier of this stream.
GetSoftwareVersion	Retrieves the version number for this file format.
ReadFromStream	Reads the filter's data from the stream.
SizeMax	Retrieves the number of bytes needed for data (not including version number).
WriteToStream	Writes the filter's data to the stream.
IPersistStream Methods	Description
GetSizeMax	Retrieves 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.