Share via


CPersistStream Class

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

Aa920909.566bfdba-0cf6-4175-b2d1-36fb34c18a32(en-us,MSDN.10).gif

This class 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 CPersistStream::WriteToStream and CPersistStream::ReadFromStream in your class. These will override the functions here, which do nothing but act as placeholders.
  3. Change your NonDelegatingQueryInterface to handle IPersistStream:IPersist.
  4. Implement CPersistStream::SizeMax to return an upper bound on the number of bytes of data you save.
  5. If you save Unicode data, remember that a WCHAR is 2 bytes.
  6. When your data changes, call CPersistStream::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 CPersistStream::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) CPersistStream::GetSoftwareVersion. It reads the version number from the file into CPersistStream::mPS_dwFileVersion before calling CPersistStream::ReadFromStream, so in CPersistStream::ReadFromStream you can check CPersistStream::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

Data Member Description

mPS_dwFileVersion

Version number of the file.

mPS_fDirty

Data for this stream must be saved.

Member Functions

Member Function Description

CPersistStream

Constructs a CPersistStream object.

SetDirty

Indicates that the object must be saved to the stream.

Overridable Member Functions

Member Function 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.

Implemented IPersistStream Methods

Method 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.

Requirements

Windows Embedded CE Windows CE 2.12 and later
Windows Mobile Windows Mobile Version 5.0 and later
Note Microsoft DirectShow applications and DirectShow filters have different include file and Library requirements
For more information, see Setting Up the Build Environment

See Also

Reference

DirectShow Classes

Other Resources

IPersistStream