php_stream_make_seekable() は、まず origstream が
シーク可能かどうか調べます。もしシークできない場合は、新たに一時的ストリーム
を作り、元のストリームのデータをすべてそこにコピーします。
成功の場合は、newstream には、元のストリームが
シーク可能だったとしても、常に利用可能なストリームが返されます。
flags で、どのような形のシーク可能なストリームが
返されるかを指定することができます。デフォルトのシーク可能なストリームを
利用したい場合は、PHP_STREAM_NO_PREFERENCE を
(通常では動的に増大するメモリ上のバッファを利用するが、
もしストリーム内のデータが巨大な場合は、テンポラリファイルに裏打ちされた
ストリームに切り替える)、または通常のテンポラリファイルに裏打ちされた
ストリームを利用したい場合は、PHP_STREAM_PREFER_STDIO
を指定してください。
表 44-1. php_stream_make_seekable() の返り値
| Value | Meaning |
|---|---|
| PHP_STREAM_UNCHANGED | 元のストリームがシーク可能だった。newstream には origstream がセットされます。
|
| PHP_STREAM_RELEASED | 元のストリームはシーク可能ではないので、開放された。
newstream には、新たに作成されたシーク可能なストリームがセットされます。
以後、origstream にアクセスしてはいけません。
|
| PHP_STREAM_FAILED | ストリームの変換中にエラーが発生した。
newstream には NULL がセットされます。
このとき origstream はまだ有効なストリームです。
|
| PHP_STREAM_CRITICAL | ストリームの変換中にエラーが発生し、元のストリームは origstream
不定な状態になっている。newstream には
NULL がセットされます。このときは、origstream
を閉じることを強く推奨します。
|
注意: 新しいストリームに対してシークを行い書き込みを行うような場合、 そのストリームは、必ずしも元のストリームと同じリソースに 関連付けられていると保証されているわけではないので、 この関数を呼び出す意味はあまりありません。
注意: もし、前方へのシークのみが必要なときは、この関数を利用してストリームを シーク可能にする必要はありません。ストリーム API は、 whence パラメータが SEEK_CUR の時、前方シークを エミュレートするからです。
注意: もし、
origstreamがネットワークベースのストリーム の場合は、この関数は、すべてのデータが読み込まれるまでブロックします。
注意: 絶対に、PHP スクリプト内で使用されているファイルポインタを参照する ストリームを、
origstreamに指定しないでください。 この関数は、そのストリームを閉じる場合があるので、スクリプト内で次に そのファイルポインタに対してアクセスが行われた場合に、クラッシュが 起こる可能性があります。
注意: ほとんどの場合において、この関数は、
origstreamが新たに開かれたストリームで、しかもストリーム層においてデータが バッファリングされていない時にのみ成功します。これにより、 また、この関数は正しく使うには多少複雑なので、できれば、 この関数を直接呼び出すのではなく、 php_stream_open_wrapper() を使い、 PHP_STREAM_MUST_SEEK をオプションとして渡す方法 を検討してみてください。