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

# stream_filter_register

(PHP 5)

stream_filter_register -- `php_user_filter` に由来するクラスとして実装されたストリームフィルタを登録する

## 説明

bool stream_filter_register ( string filtername, string classname)

stream_filter_register() は、fopen() や fread() などのファイルシステムの関数で利用可能な 登録されているどの種類のストリームとも一緒に使うことのできる カスタムフィルタを登録します。

フィルタを実装するには、まず、`php_user_fitler` を継承したクラスの下記に示されたメンバ関数を実装しなくてはなりません。 `PHP` は、書き込みまたは読み出し操作を カスタムフィルタの付加されたストリームに対して行う際に、まず データをそのフィルタに(そして、付加されている他のすべてのフィルタにも) 渡し、指示どおりストリームのデータが変更されるようにします。 下記のメソッドは、説明の通り実装されなくてはなりません。 さもないと、定義されていない動作をします。

stream_filter_register() は、 指定された `filtername` がすでに定義されている場合、 `FALSE` を返します。

int filter ( resource in, resource out, int &consumed, boolean closing)

このメソッドは、fread() や fwrite() 等の関数で、付加されたストリームからデータを読み出す時や、 データを書き込む度に呼ばれます。 `in` は、`bucket brigade` (バケツリレー隊) を指すポインターです。 これは、フィルタの対象になるデータを含む複数の `bucket` オブジェクトから成っています。 `out` は、変更されたバケットが渡される `bucket brigade` を示しています。 `consumed` は、参照渡しされるパラメータで、 ここには、フィルタが実際に処理した元のデータ長を加算します。 ほとんどの場合、それぞれのバケットについて、そのデータ長 `$bucket->datalen` を、そこに足すだけでいいはずです。 もし、ストリームが閉じようとしている時 (すなわちフィルタ連鎖の中の 最後の呼び出しだった時)、`closing` パラメータは、 `TRUE` となります。`filter` パラメータは、さらに、 次の値のいずれかを終了時に返さなくてはなりません。 `PSFS_PASS_ON` は、処理に成功し、 `out` の `バケツ隊` に データが渡されたことを示します。`PSFS_FEED_ME` は、 その時点では返すデータがなく、ストリームからのより多くの入力データを 必要としていることを示します。 `PSFS_ERR_FATAL` は、フィルタにおいて、 復旧不可能なエラーが発生し、処理を継続できないことを示します。 もし、返値が返されなかった場合、 `PSFS_ERR_FATAL` が 想定されます。

void oncreate ( void )

このメソッドは、フィルタクラスのオブジェクトが実体化されるときに 呼び出されます。もし、フィルタがバッファなど他のリソースを 確保したり初期化しなくてはならない場合、この時点で行ってください。

void onclose ( void )

このメソッドは、フィルタが遮断される時(通常、ストリームが遮断 される時)に呼ばれます。また、同様に、`flush` メソッドが 呼ばれた後に呼び出されます。 もし、何らかのリソースが、`oncreate` メソッドの 呼び出し時に確保されていた場合は、それらをここで廃棄するのが いいでしょう。

下記の例は、読み込まれたり書き出されたりするデータに含まれるすべての英文字を 大文字化する `strtoupper` ストリームを実装し、`foo-bar.txt` ストリームに適用するものです。

例 1. foo-bar.txt ストリームの文字を大文字化するフィルタ

`<?php
/* フィルタクラスを定義する */
class strtoupper_filter extends php_user_filter {
function filter($in, $out, &$consumed, $closing) {
while ($bucket = stream_bucket_make_writeable($in)) {
$bucket->data = strtoupper($bucket->data);
$consumed += $bucket->datalen;
stream_bucket_append($out, $bucket);
}
return PSFS_PASS_ON;
}
}
/* PHP にフィルタを登録する */
stream_filter_register("strtoupper", "strtoupper_filter")
or die("Failed to register filter");
$fp = fopen("foo-bar.txt", "w");
/* フィルタを開いたストリームに付加する */
stream_filter_append($fp, "strtoupper");
fwrite($fp, "Line1\n");
fwrite($fp, "Word - 2\n");
fwrite($fp, "Easy As 123\n");
fclose($fp);
/* ファイルを読み出し出力する。
*/
readfile("foo-bar.txt");
/* Output
* ------
LINE1
WORD - 2
EASY AS 123
*/
?>`

stream_wrapper_register(), stream_filter_prepend(), stream_filter_append() も参照下さい。

前のページ | ホーム | 次のページ
stream_filter_prepend | 上に戻る | stream_get_contents