/
filter.xml
132 lines (126 loc) · 4.11 KB
/
filter.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="php-user-filter.filter" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>php_user_filter::filter</refname>
<refpurpose>Called when applying the filter</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="php_user_filter">
<modifier>public</modifier> <type>int</type><methodname>php_user_filter::filter</methodname>
<methodparam><type>resource</type><parameter>in</parameter></methodparam>
<methodparam><type>resource</type><parameter>out</parameter></methodparam>
<methodparam><type>int</type><parameter role="reference">consumed</parameter></methodparam>
<methodparam><type>bool</type><parameter>closing</parameter></methodparam>
</methodsynopsis>
<para>
This method is called whenever data is read from or written to
the attached stream (such as with <function>fread</function> or <function>fwrite</function>).
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>in</parameter></term>
<listitem>
<para>
<parameter>in</parameter> is a resource pointing to a <literal>bucket brigade</literal>
which contains one or more <literal>bucket</literal> objects containing data to be filtered.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>out</parameter></term>
<listitem>
<para>
<parameter>out</parameter> is a resource pointing to a second <literal>bucket brigade</literal>
into which your modified buckets should be placed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>consumed</parameter></term>
<listitem>
<para>
<parameter>consumed</parameter>, which must <emphasis>always</emphasis>
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 <parameter>consumed</parameter> by <literal>$bucket->datalen</literal>
for each <literal>$bucket</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>closing</parameter></term>
<listitem>
<para>
If the stream is in the process of closing
(and therefore this is the last pass through the filterchain),
the <parameter>closing</parameter> parameter will be set to &true;.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The <methodname>filter</methodname> method must return one of
three values upon completion.
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Return Value</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>PSFS_PASS_ON</constant></entry>
<entry>
Filter processed successfully with data available in the
<parameter>out</parameter> <literal>bucket brigade</literal>.
</entry>
</row>
<row>
<entry><constant>PSFS_FEED_ME</constant></entry>
<entry>
Filter processed successfully, however no data was available to
return. More data is required from the stream or prior filter.
</entry>
</row>
<row>
<entry><constant>PSFS_ERR_FATAL</constant> (default)</entry>
<entry>
The filter experienced an unrecoverable error and cannot continue.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->