CPersistStream Class

CPersistStream class hierarchy

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.

Protected Data Members

mPS_dwFileVersion Version number of the file.
mPS_fDirty Data for this stream must be saved.

Member Functions

CPersistStream Constructs a CPersistStream object.
SetDirty Indicates that the object must be saved to the stream.

Overridable Member Functions

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.

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

Implemented IPersistStream Methods

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.

CPersistStream::CPersistStream

CPersistStream Class

Constructs a CPersistStream object.

Syntax

CPersistStream(
    IUnknown *pUnk,
    HRESULT *phr
);

Parameters

pUnk
Pointer to the IUnknown interface of the delegating object.
phr
Pointer to the general COM return value. This value is changed only if this function fails.

Return Value

No return value.

CPersistStream::GetClassID

CPersistStream Class

Retrieves the class identifier for this filter.

Syntax

HRESULT GetClassID(
    CLSID *pClsID
);

Parameters

pClsID
Pointer to a CLSID structure. Copy your class ID to here.

Return Value

Returns an HRESULT value.

CPersistStream::GetSizeMax

CPersistStream Class

Retrieves the maximum byte size needed for the current stream, including the version number.

Syntax

HRESULT GetSizeMax(
    ULARGE_INTEGER *pcbSize
);

Parameters

pcbSize
Pointer to the size in bytes needed to save this stream, including the version number.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IPersistStream::GetSizeMax method.

CPersistStream::GetSoftwareVersion

CPersistStream Class

Retrieves the software version for this stream.

Syntax

virtual DWORD GetSoftwareVersion(void);

Return Value

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.

Remarks

For an explanation as to why file format version numbers are useful, see Version Numbers.

CPersistStream::IsDirty

CPersistStream Class

Indicates whether the object has changed since it was last saved to its current stream.

Syntax

HRESULT IsDirty(void);

Return Value

Returns S_OK if the filter needs saving and S_FALSE if it does not need saving.

Remarks

This member function implements the IPersistStream::IsDirty method.

CPersistStream::Load

CPersistStream Class

Loads the filter's data from a given stream.

Syntax

HRESULT Load(
    LPSTREAM pStm
);

Parameters

pStm
Pointer to the stream from which to be loaded.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IPersistStream::Load method.

CPersistStream::ReadFromStream

CPersistStream Class

Reads the filter's data from the given stream.

Syntax

virtual HRESULT ReadFromStream(
    IStream *pStream
);

Parameters

pStream
Pointer to an IStream interface from which data is to be read.

Return Value

Returns NOERROR by default; the overriding member function should return a valid HRESULT value.

Remarks

The default version reads nothing; it can be overridden to read data specific to your class.

CPersistStream::Save

CPersistStream Class

Saves the filter's data to the given stream.

Syntax

HRESULT Save(
    LPSTREAM pStm,
    BOOL fClearDirty
);

Parameters

pStm
Pointer to the stream to which data is to be saved.
fClearDirty
Flag that indicates whether to reset the current stream's dirty flag; TRUE means to reset it. When called as part of a Save command, the flag is ordinarily reset; when called as part of a Save As command, the flag is ordinarily not reset.

Return Value

Returns an HRESULT value.

Remarks

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.

CPersistStream::SetDirty

CPersistStream Class

Changes the dirty flag for the current stream.

Syntax

HRESULT SetDirty(
    BOOL fDirty
);

Parameters

fDirty
New dirty flag for this stream. TRUE means that the data has not been saved.

Return Value

Returns an HRESULT value.

CPersistStream::SizeMax

CPersistStream Class

Retrieves the maximum byte size needed for the current stream, not including the version number.

Syntax

virtual int SizeMax(void);

Return Value

Returns the number of bytes needed for data, not including the version number.

Remarks

The default version returns zero; it should be overridden to provide some other appropriate value.

CPersistStream::WriteToStream

CPersistStream Class

Writes the filter's data to the given stream.

Syntax

virtual HRESULT WriteToStream(
    IStream *pStream
);

Parameters

pStream
Pointer to an IStream interface that specifies the filter data's destination stream.

Return Value

Returns NOERROR by default; the overriding member function should return a valid HRESULT value.

Remarks

The default version writes nothing; it can be overridden to write data specific to your class.


Top of Page Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.