php_stream_cast() は stream で 指定されたストリームを castas で指示されたリソースに 変換しようと試みます。 もし、ret が NULL であった場合は、実際に 変換は行われず、単にストリームに対してそのような変換が可能であるかどうか だけを調べます。(しかし、この場合何らかのストリームの状態が変化することが あります。) もし、flags に REPORT_ERRORS が セットされていた場合は、変換中にエラーがあると、エラーメッセージが 表示されます。
注意: この関数は、成功時に SUCCESS を、失敗時に FAILURE を返します。 返り値の判定の際は単純に値の真偽を見るのではなく、 定数 SUCCESS や FAILURE と 明示的に比較しなければならないことに注意してください。 これらの定数値は単純なブール値ではないからです。
表 44-1. castas に指定できるリソースの種類
| 値 | 意味 |
|---|---|
| PHP_STREAM_AS_STDIO | ストリームを表す ANSI FILE* ファイルポインタを要求する |
| PHP_STREAM_AS_FD | ストリームを表す POSIX ファイルデスクリプタを要求する |
| PHP_STREAM_AS_SOCKETD | ストリームを表すソケットのデスクリプタを要求する |
上に示したような基本的なリソースの種類を指定するのに加え、 変換動作を、リソースの種類を表す値と次に示した値とを OR 演算子で 組み合わせることでしていすることができます:
表 44-2. Resource types for castas
| 値 | 意味 |
|---|---|
| PHP_STREAM_CAST_TRY_HARD | 別のリソースをあえて利用するなど、できるだけ変換が成功するような試行を行う |
| PHP_STREAM_CAST_RELEASE | ストリームAPI に、この関数を呼び出した ストリームAPI 以外のコード (おそらくはサードパーティのライブラリ) の内部で、ストリームがラップしているリソースやハンドルを閉じることを 通知します。これにより、stream が、 ストリームの背後にあるハンドルそのものを閉じずに ret に返したところで閉じられます。 このとき、この関数が成功したら、 stream はその時点で閉じられたと判断されるべきで、 以降そのストリームを使ってはいけません。 |
注意: もし使っているシステム(glibc 2 または以降を使っているシステム)が fopencookie() をサポートしている場合、 ストリーム API は常にどのストリームからも ANSI FILE * ポインタを 合成できます。この特長はあらゆる PHP ストリームをサードパーティの ライブラリに渡せるので非常に便利ですが、一方で、移植可能性は高く ありません。この場合は、あなたの作成した拡張モジュールを配布する際に、 移植可能性についての表示を行っておいたほうがよいでしょう。 もし fopencookie による合成が望ましくない場合は、問題とするストリームが ネイティブに FILE* をサポートしているかどうか php_stream_is() で調べましょう。
注意: ソケットベースのストリームを FILE* に変換する際、ストリーム API は fdopen() を使ってそれを生成します。 そうすることは、ストリーム API のコールと ANSI 標準入出力 API のコールを 交互に行った際に、ストリーム層においてバッファされたデータが失われる 危険性を生じることに注意してください。
php_stream_is() と php_stream_can_cast() も参照ください。