-
Notifications
You must be signed in to change notification settings - Fork 73
/
stream-filter-append.xml
195 lines (179 loc) · 7.6 KB
/
stream-filter-append.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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: e41806c30bf6975e452c0d4ce35ab0984c2fa68c Maintainer: mch Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.stream-filter-append" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>stream_filter_append</refname>
<refpurpose>Прикрепляет фильтр к потоку</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>resource</type><methodname>stream_filter_append</methodname>
<methodparam><type>resource</type><parameter>stream</parameter></methodparam>
<methodparam><type>string</type><parameter>filtername</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>read_write</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<para>
Функция добавляет фильтр <parameter>filtername</parameter> в список фильтров,
прикреплённых к потоку <parameter>stream</parameter>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>stream</parameter></term>
<listitem>
<para>
Целевой поток.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>filtername</parameter></term>
<listitem>
<para>
Название фильтра.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>read_write</parameter></term>
<listitem>
<para>
По умолчанию <function>stream_filter_append</function> будет
прикреплять фильтр к <literal>цепочке фильтров чтения</literal>,
если файл открыли для чтения (т. е. режим файла:
<literal>r</literal>, и/или <literal>+</literal>). Фильтр
также будет прикреплён к <literal>цепочке фильтров записи</literal>,
если файл открыли для записи (т. е. режим файла:
<literal>w</literal>, <literal>a</literal>, и/или <literal>+</literal>).
Константы <constant>STREAM_FILTER_READ</constant>,
<constant>STREAM_FILTER_WRITE</constant> и (или)
<constant>STREAM_FILTER_ALL</constant> также разрешается передавать в параметр
<parameter>read_write</parameter>, чтобы переопределить это поведение.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>params</parameter></term>
<listitem>
<para>
Этот фильтр будет добавлен с параметрами
<parameter>params</parameter> к <emphasis>концу</emphasis> списка
и, таким образом, будет вызван последним в списке потоковых операций.
Чтобы добавить фильтр в начало списка, вызывают функцию
<function>stream_filter_prepend</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Функция возвращает ресурс в случае успешного выполнения или &false;, если возникла ошибка.
Ресурс можно использовать для ссылки на этот экземпляр фильтра во время вызова
функции <function>stream_filter_remove</function>.
</para>
<para>
Функция вернёт &false;, если поток <parameter>stream</parameter> — не ресурс или если
функция не нашла фильтр <parameter>filtername</parameter>.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Контроль применения фильтров</title>
<programlisting role="php">
<![CDATA[
<?php
/* Открываем тестовый файл для чтения и записи */
$fp = fopen('test.txt', 'w+');
/* Прикрепляем фильтр ROT13 к
* цепочке фильтров записи, но не к
* цепочке фильтров чтения */
stream_filter_append($fp, "string.rot13", STREAM_FILTER_WRITE);
/* Записываем простую строку в файл,
* она будет преобразована через фильтр ROT13
* на выходе */
fwrite($fp, "This is a test\n");
/* Отматываем позицию указателя в начало файла */
rewind($fp);
/* Прочитаем содержимое файла.
* Если фильтр также был бы прикреплён к
* цепочке фильтров чтения, мы бы увидели
* преобразованный фильтром ROT13 текст в исходном состоянии */
fpassthru($fp);
fclose($fp);
/* Ожидаемый вывод
---------------
Guvf vf n grfg
*/
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<note>
<title>Передача пользовательских фильтров</title>
<simpara>
Сначала требуется вызвать функцию <function>stream_filter_register</function>,
чтобы зарегистрировать необходимый пользовательский фильтр для параметра <parameter>filtername</parameter>.
</simpara>
</note>
<note>
<simpara>
Потоковые данные читаются из ресурсов (как локальных, так удалённых) порциями,
при этом невостребованные данные сохраняются во внутренних буферах. Когда новый фильтр
добавляется в конец потока, данные во внутренних буферах обрабатываются
через новый фильтр. Это отличается от поведения функции
<function>stream_filter_prepend</function>.
</simpara>
</note>
<note>
<simpara>
Когда фильтр добавляется для чтения и записи, создаются два экземпляра
фильтра. Функцию <function>stream_filter_append</function> необходимо вызвать дважды
с флагами <constant>STREAM_FILTER_READ</constant>
и <constant>STREAM_FILTER_WRITE</constant>, чтобы получить оба ресурса фильтра.
</simpara>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>stream_filter_register</function></member>
<member><function>stream_filter_prepend</function></member>
<member><function>stream_get_filters</function></member>
</simplelist>
</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
-->