Microsoft DirectX 8.0 |
CPersistStream は、フィルタの永続的なプロパティ (保存されたグラフのフィルタ プロパティ) の基底クラスである。
CPersistStream を使用する簡単な方法は次のとおりである。
Unicode のデータを保存する場合は、WCHAR が 2 バイトであることに留意する。
バージョン番号
ある時点で、データのフォーマットを変更または拡張したい場合がある。この場合、以前に保存したすべてのストリームにバージョン番号を付けて、ストリームを読み取ったときに、ストリームが古いフォーマットであるか、新しいフォーマットであるかを区別できるようにする必要がある。これを行うために、このクラスはバージョン番号の読み書きを行う。書き込み時には、このクラスは GetSoftwareVersion を呼び出して、そのときに使用されているソフトウェアのバージョンを問い合わせる。実質的に、これがファイル内のデータ レイアウトのバージョン番号になる。このクラスは、データ内の最初の項目としてこれを書き込む。バージョン番号を変更する場合は、GetSoftwareVersion を実装 (オーバーライド) する。このクラスは、ReadFromStream を呼び出す前に、ファイルから mPS_dwFileVersion にバージョン番号を読み取るので、ReadFromStream で mPS_dwFileVersion をチェックして、古いバージョンのファイルを読み取っているかどうかを確認できる。通常、ファイルを読み取るソフトウェアのバージョン以前のバージョンのファイルを受け入れる必要がある。
プロテクト データ メンバ
mPS_dwFileVersion ファイルのバージョン番号。 mPS_fDirty このストリームのデータを保存しなければならない。
メンバ関数
CPersistStream CPersistStream オブジェクトを作成する。 SetDirty オブジェクトをストリームに保存しなければならないことを指定する。
オーバーライド可能なメンバ関数
GetClassID このストリームのクラス識別子を取得する。 GetSoftwareVersion このファイル フォーマットのバージョン番号を取得する。 ReadFromStream ストリームからフィルタのデータを読み取る。 SizeMax データで必要なバイト数 (バージョン番号を含まない) を取得する。 WriteToStream ストリームにフィルタのデータを書き込む。
CPersistStream は IPersistStream を実装する。実装の詳細については、Microsoft Platform SDK の「COM リファレンス」を参照すること。
GetSizeMax データで必要なバイト数 (バージョン番号を含む) を取得する。 IsDirty オブジェクトを保存しなければならないかどうかをチェックする。 Load データをストリームからメモリにロードする。 Save データをメモリからストリームに保存する。
CPersistStream オブジェクトを作成する。
構文
CPersistStream( IUnknown *pUnk, HRESULT *phr );
パラメータ
- pUnk
- 委任オブジェクトの IUnknown インターフェイスへのポインタ。
- phr
- 一般的な COM 戻り値へのポインタ。この値は、この関数が失敗した場合にのみ変更される。
戻り値
戻り値なし。
このフィルタのクラス識別子を取得する。
構文
HRESULT GetClassID( CLSID *pClsID );
パラメータ
- pClsID
- CLSID 構造体へのポインタ。クラス ID をここにコピーする。
戻り値
HRESULT 値を返す。
バージョン番号を含む、現在のストリームに必要な最大バイト サイズを取得する。
構文
HRESULT GetSizeMax( ULARGE_INTEGER *pcbSize );
パラメータ
- pcbSize
- バージョン番号を含めて、このストリームを保存するために必要なバイト単位のサイズへのポインタ。
戻り値
HRESULT 値を返す。
注意
このメンバ関数は、IPersistStream::GetSizeMax メソッドを実装する。
このストリームのソフトウェア バージョンを取得する。
構文
virtual DWORD GetSoftwareVersion(void);
戻り値
バージョン番号を格納する DWORD 型の値を返す。ストリームのフォーマットが変更されるたびに、この関数を変更して以前よりも大きい数値を返すようにする必要がある。
注意
ファイル フォーマットのバージョン番号を使用する理由については、「バージョン番号」を参照すること。
オブジェクトが現在のストリームに最後に保存された後、変更されたかどうかを示す。
構文
HRESULT IsDirty(void);
戻り値
フィルタを保存する必要がある場合は S_OK を返す。保存の必要がない場合は S_FALSE を返す。
注意
このメンバ関数は、IPersistStream::IsDirty メソッドを実装する。
指定されたストリームからフィルタのデータをロードする。
構文
HRESULT Load( LPSTREAM pStm );
パラメータ
- pStm
- ロード元のストリームへのポインタ。
戻り値
HRESULT 値を返す。
注意
このメンバ関数は、IPersistStream::Load メソッドを実装する。
指定されたストリームからフィルタのデータを読み取る。
構文
virtual HRESULT ReadFromStream( IStream *pStream );
パラメータ
- pStream
- データが読み取られる IStream インターフェイスへのポインタ。
戻り値
デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。
注意
デフォルトのバージョンは何も読み取らない。これをオーバーライドして、クラスに固有のデータを読み取ることができる。
指定されたストリームにフィルタのデータを保存する。
構文
HRESULT Save( LPSTREAM pStm, BOOL fClearDirty );
パラメータ
- pStm
- データが保存されるストリームへのポインタ。
- fClearDirty
- 現在のストリームのダーティー フラグをリセットするかどうかを指定するフラグ。TRUE はダーティー フラグをリセットすることを意味する。Save 処理の中でこのメソッドを呼び出す場合、通常、この値は TRUE である。Save As 処理の中で呼び出す場合、通常、この値は FALSE である。
戻り値
HRESULT 値を返す。
注意
このメンバ関数は、IPersistStream::Save メソッドを実装する。このメンバ関数は、ソフトウェア バージョンを指定して WriteInt を呼び出し、pStm でストリームを指定して CPersistStream::WriteToStream を呼び出して、mPS_fDirty をリセットする。
現在のストリームのダーティー フラグを変更する。
構文
HRESULT SetDirty( BOOL fDirty );
パラメータ
- fDirty
- このストリームの新しいダーティー フラグ。TRUE はデータが保存されていないことを意味する。
戻り値
HRESULT 値を返す。
バージョン番号を含まない、現在のストリームに必要な最大バイト サイズを取得する。
構文
virtual int SizeMax(void);
戻り値
バージョン番号を含まない、データで必要なバイト数を返す。
注意
デフォルトのバージョンは 0 を返す。ほかの適切な値を返すには、これをオーバーライドする必要がある。
指定されたストリームにフィルタのデータを書き込む。
構文
virtual HRESULT WriteToStream( IStream *pStream );
パラメータ
- pStream
- フィルタ データの転送先ストリームを指定する IStream インターフェイスへのポインタ。
戻り値
デフォルトでは NOERROR を返す。オーバーライドするメンバ関数は、有効な HRESULT 値を返す。
注意
デフォルトのバージョンは何も書き込まない。これをオーバーライドして、クラスに固有のデータを書き込むことができる。