php_stream_cast

php_stream_cast --  ストリームをFILE*またはソケットのような他の形式に変換する

説明

int php_stream_cast ( php_stream * stream, int castas, void ** ret, int flags )

php_stream_cast()stream で 指定されたストリームを castas で指示されたリソースに 変換しようと試みます。 もし、ret が NULL であった場合は、実際に 変換は行われず、単にストリームに対してそのような変換が可能であるかどうか だけを調べます。(しかし、この場合何らかのストリームの状態が変化することが あります。) もし、flagsREPORT_ERRORS が セットされていた場合は、変換中にエラーがあると、エラーメッセージが 表示されます。

注意: この関数は、成功時に SUCCESS を、失敗時に FAILURE を返します。 返り値の判定の際は単純に値の真偽を見るのではなく、 定数 SUCCESSFAILURE と 明示的に比較しなければならないことに注意してください。 これらの定数値は単純なブール値ではないからです。

表 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() も参照ください。