<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Called when applying the filter</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="class.php-user-filter.html">php_user_filter</a></div>
<div class="next" style="text-align: right; float: right;"><a href="php-user-filter.onclose.html">php_user_filter::onClose</a></div>
<div class="up"><a href="class.php-user-filter.html">php_user_filter</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="php-user-filter.filter" class="refentry">
<div class="refnamediv">
<h1 class="refname">php_user_filter::filter</h1>
<p class="verinfo">(PHP 5)</p><p class="refpurpose"><span class="refname">php_user_filter::filter</span> — <span class="dc-title">Called when applying the filter</span></p>
</div>
<div class="refsect1 description" id="refsect1-php-user-filter.filter-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">int</span> <span class="methodname"><strong>php_user_filter::filter</strong></span>
( <span class="methodparam"><span class="type">resource</span> <code class="parameter">$in</code></span>
, <span class="methodparam"><span class="type">resource</span> <code class="parameter">$out</code></span>
, <span class="methodparam"><span class="type">int</span> <code class="parameter reference">&$consumed</code></span>
, <span class="methodparam"><span class="type">bool</span> <code class="parameter">$closing</code></span>
)</div>
<p class="para rdfs-comment">
This method is called whenever data is read from or written to
the attached stream (such as with <span class="function"><a href="function.fread.html" class="function">fread()</a></span> or <span class="function"><a href="function.fwrite.html" class="function">fwrite()</a></span>).
</p>
</div>
<div class="refsect1 parameters" id="refsect1-php-user-filter.filter-parameters">
<h3 class="title">Parameters</h3>
<dl>
<dt>
<span class="term"><em><code class="parameter">in</code></em></span>
<dd>
<p class="para">
<em><code class="parameter">in</code></em> is a resource pointing to a <em>bucket brigade</em>
which contains one or more <em>bucket</em> objects containing data to be filtered.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">out</code></em></span>
<dd>
<p class="para">
<em><code class="parameter">out</code></em> is a resource pointing to a second <em>bucket brigade</em>
into which your modified buckets should be placed.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">consumed</code></em></span>
<dd>
<p class="para">
<em><code class="parameter">consumed</code></em>, which must <em class="emphasis">always</em>
be declared by reference, should be incremented by the length of the data
which your filter reads in and alters. In most cases this means you will
increment <em><code class="parameter">consumed</code></em> by <em>$bucket->datalen</em>
for each <em>$bucket</em>.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">closing</code></em></span>
<dd>
<p class="para">
If the stream is in the process of closing
(and therefore this is the last pass through the filterchain),
the <em><code class="parameter">closing</code></em> parameter will be set to <strong><code>TRUE</code></strong>.
</p>
</dd>
</dt>
</dl>
</div>
<div class="refsect1 returnvalues" id="refsect1-php-user-filter.filter-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
The <span class="methodname"><strong>filter()</strong></span> method must return one of
three values upon completion.
<table class="doctable informaltable">
<thead>
<tr>
<th>Return Value</th>
<th>Meaning</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td><strong><code>PSFS_PASS_ON</code></strong></td>
<td>
Filter processed successfully with data available in the
<em><code class="parameter">out</code></em> <em>bucket brigade</em>.
</td>
</tr>
<tr>
<td><strong><code>PSFS_FEED_ME</code></strong></td>
<td>
Filter processed successfully, however no data was available to
return. More data is required from the stream or prior filter.
</td>
</tr>
<tr>
<td><strong><code>PSFS_ERR_FATAL</code></strong> (default)</td>
<td>
The filter experienced an unrecoverable error and cannot continue.
</td>
</tr>
</tbody>
</table>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="class.php-user-filter.html">php_user_filter</a></div>
<div class="next" style="text-align: right; float: right;"><a href="php-user-filter.onclose.html">php_user_filter::onClose</a></div>
<div class="up"><a href="class.php-user-filter.html">php_user_filter</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
