PHP マニュアル
前のページ |  | 次のページ

# php_stream_cast

(no version information, might be only in CVS)

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

## 説明

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

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

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

表 43-1. `castas` に指定できるリソースの種類

値 | 意味
--- | ---
PHP_STREAM_AS_STDIO | ストリームを表す ANSI FILE* ファイルポインタを要求する
PHP_STREAM_AS_FD | ストリームを表す POSIX ファイルデスクリプタを要求する
PHP_STREAM_AS_SOCKETD | ストリームを表すソケットのデスクリプタを要求する

上に示したような基本的なリソースの種類を指定するのに加え、 変換動作を、リソースの種類を表す値と次に示した値とを OR 演算子で 組み合わせることでしていすることができます:

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

前のページ | ホーム | 次のページ
php_stream_make_seekable | 上に戻る | php_stream_can_cast