Microsoft DirectX 8.0

CPersistStream クラス

CPersistStream クラスの階層

CPersistStream は、フィルタの永続的なプロパティ (保存されたグラフのフィルタ プロパティ) の基底クラスである。

CPersistStream を使用する簡単な方法は次のとおりである。

  1. フィルタがこのクラスを継承するようにする。
  2. クラスに WriteToStream および ReadFromStream を実装する。これらの方法はここで示されている、プレースホルダとしてのみ機能する関数をオーバーライドする。
  3. NonDelegatingQueryInterface を、IPersistStream を処理するように変更する。
  4. 保存するデータのバイト数の上限を返す SizeMax を実装する。

    Unicode™ のデータを保存する場合は、WCHAR が 2 バイトであることに留意する。

  5. データが変更されたときに、SetDirty を呼び出す。

バージョン番号

ある時点で、データのフォーマットを変更または拡張したい場合がある。この場合、以前に保存したすべてのストリームにバージョン番号を付けて、ストリームを読み取ったときに、ストリームが古いフォーマットであるか、新しいフォーマットであるかを区別できるようにする必要がある。これを行うために、このクラスはバージョン番号の読み書きを行う。書き込み時には、このクラスは GetSoftwareVersion を呼び出して、そのときに使用されているソフトウェアのバージョンを問い合わせる。実質的に、これがファイル内のデータ レイアウトのバージョン番号になる。このクラスは、データ内の最初の項目としてこれを書き込む。バージョン番号を変更する場合は、GetSoftwareVersion を実装 (オーバーライド) する。このクラスは、ReadFromStream を呼び出す前に、ファイルから mPS_dwFileVersion にバージョン番号を読み取るので、ReadFromStreammPS_dwFileVersion をチェックして、古いバージョンのファイルを読み取っているかどうかを確認できる。通常、ファイルを読み取るソフトウェアのバージョン以前のバージョンのファイルを受け入れる必要がある。

プロテクト データ メンバ

mPS_dwFileVersion ファイルのバージョン番号。
mPS_fDirty このストリームのデータを保存しなければならない。

メンバ関数

CPersistStream CPersistStream オブジェクトを作成する。
SetDirty オブジェクトをストリームに保存しなければならないことを指定する。

オーバーライド可能なメンバ関数

GetClassID このストリームのクラス識別子を取得する。
GetSoftwareVersion このファイル フォーマットのバージョン番号を取得する。
ReadFromStream ストリームからフィルタのデータを読み取る。
SizeMax データで必要なバイト数 (バージョン番号を含まない) を取得する。
WriteToStream ストリームにフィルタのデータを書き込む。

CPersistStreamIPersistStream を実装する。実装の詳細については、Microsoft Platform SDK の「COM リファレンス」を参照すること。

実装される IPersistStream メソッド

GetSizeMax データで必要なバイト数 (バージョン番号を含む) を取得する。
IsDirty オブジェクトを保存しなければならないかどうかをチェックする。
Load データをストリームからメモリにロードする。
Save データをメモリからストリームに保存する。

CPersistStream::CPersistStream

CPersistStream クラス

CPersistStream オブジェクトを作成する。

構文

CPersistStream(
IUnknown *pUnk,
HRESULT *phr
);

パラメータ

pUnk
委任オブジェクトの IUnknown インターフェイスへのポインタ。
phr
一般的な COM 戻り値へのポインタ。この値は、この関数が失敗した場合にのみ変更される。

戻り値

戻り値なし。

CPersistStream::GetClassID

CPersistStream クラス

このフィルタのクラス識別子を取得する。

構文

HRESULT GetClassID(
CLSID *pClsID
);

パラメータ

pClsID
CLSID 構造体へのポインタ。クラス ID をここにコピーする。

戻り値

HRESULT 値を返す。

CPersistStream::GetSizeMax

CPersistStream クラス

バージョン番号を含む、現在のストリームに必要な最大バイト サイズを取得する。

構文

HRESULT GetSizeMax(
ULARGE_INTEGER *pcbSize
);

パラメータ

pcbSize
バージョン番号を含めて、このストリームを保存するために必要なバイト単位のサイズへのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IPersistStream::GetSizeMax メソッドを実装する。

CPersistStream::GetSoftwareVersion

CPersistStream クラス

このストリームのソフトウェア バージョンを取得する。

構文

virtual DWORD GetSoftwareVersion(void);

戻り値

バージョン番号を格納する DWORD 型の値を返す。ストリームのフォーマットが変更されるたびに、この関数を変更して以前よりも大きい数値を返すようにする必要がある。

注意

ファイル フォーマットのバージョン番号を使用する理由については、「バージョン番号」を参照すること。

CPersistStream::IsDirty

CPersistStream クラス

オブジェクトが現在のストリームに最後に保存された後、変更されたかどうかを示す。

構文

HRESULT IsDirty(void);

戻り値

フィルタを保存する必要がある場合は S_OK を返す。保存の必要がない場合は S_FALSE を返す。

注意

このメンバ関数は、IPersistStream::IsDirty メソッドを実装する。

CPersistStream::Load

CPersistStream クラス

指定されたストリームからフィルタのデータをロードする。

構文

HRESULT Load(
LPSTREAM pStm
);

パラメータ

pStm
ロード元のストリームへのポインタ。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IPersistStream::Load メソッドを実装する。

CPersistStream::ReadFromStream

CPersistStream クラス

指定されたストリームからフィルタのデータを読み取る。

構文

virtual HRESULT ReadFromStream(
IStream *pStream
);

パラメータ

pStream
データが読み取られる IStream インターフェイスへのポインタ。

戻り値

デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。

注意

デフォルトのバージョンは何も読み取らない。これをオーバーライドして、クラスに固有のデータを読み取ることができる。

CPersistStream::Save

CPersistStream クラス

指定されたストリームにフィルタのデータを保存する。

構文

HRESULT Save(
LPSTREAM pStm,
BOOL fClearDirty
);

パラメータ

pStm
データが保存されるストリームへのポインタ。
fClearDirty
現在のストリームのダーティー フラグをリセットするかどうかを指定するフラグ。TRUE はダーティー フラグをリセットすることを意味する。Save 処理の中でこのメソッドを呼び出す場合、通常、この値は TRUE である。Save As 処理の中で呼び出す場合、通常、この値は FALSE である。

戻り値

HRESULT 値を返す。

注意

このメンバ関数は、IPersistStream::Save メソッドを実装する。このメンバ関数は、ソフトウェア バージョンを指定して WriteInt を呼び出し、pStm でストリームを指定して CPersistStream::WriteToStream を呼び出して、mPS_fDirty をリセットする。

CPersistStream::SetDirty

CPersistStream クラス

現在のストリームのダーティー フラグを変更する。

構文

HRESULT SetDirty(
BOOL fDirty
);

パラメータ

fDirty
このストリームの新しいダーティー フラグ。TRUE はデータが保存されていないことを意味する。

戻り値

HRESULT 値を返す。

CPersistStream::SizeMax

CPersistStream クラス

バージョン番号を含まない、現在のストリームに必要な最大バイト サイズを取得する。

構文

virtual int SizeMax(void);

戻り値

バージョン番号を含まない、データで必要なバイト数を返す。

注意

デフォルトのバージョンは 0 を返す。ほかの適切な値を返すには、これをオーバーライドする必要がある。

CPersistStream::WriteToStream

CPersistStream クラス

指定されたストリームにフィルタのデータを書き込む。

構文

virtual HRESULT WriteToStream(
IStream *pStream
);

パラメータ

pStream
フィルタ データの転送先ストリームを指定する IStream インターフェイスへのポインタ。

戻り値

デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。

注意

デフォルトのバージョンは何も書き込まない。これをオーバーライドして、クラスに固有のデータを書き込むことができる。