pollita Sat Jan 4 23:25:07 2003 EDT
Added files:
/phpdoc/en/reference/stream/functions stream-get-filters.xml
Modified files:
/phpdoc/en/reference/stream reference.xml
/phpdoc/en/reference/stream/functions stream-register-filter.xml
Log:
Changes per Wez and addition of stream_get_filters
Index: phpdoc/en/reference/stream/reference.xml
diff -u phpdoc/en/reference/stream/reference.xml:1.4
phpdoc/en/reference/stream/reference.xml:1.5
--- phpdoc/en/reference/stream/reference.xml:1.4 Sat Jan 4 18:14:54 2003
+++ phpdoc/en/reference/stream/reference.xml Sat Jan 4 23:25:06 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
<reference id="ref.stream">
<title>Stream functions</title>
<titleabbrev>Streams</titleabbrev>
@@ -11,21 +11,33 @@
<simpara>
Streams were introduced with <literal>PHP</literal> 4.3.0 as
a way of generalizing file, network, data compression, and other
- opperations which share a common set of functions and uses. In
- its simplest definition, a stream is any I/O conduit for exchanging
- information. Some streams work on the local filesystem, some
- use network connections (sockets), while others might potentially focus
- on communication devices such as printers or modems. Because any variety
- of stream may be added to <literal>PHP</literal> via the
- <function>stream_register_wrapper</function> function, there is no
- set limit on what can be done with them. See <xref linkend="wrappers"/>
- for a listing of stream wrappers built into <literal>PHP</literal>.
+ opperations which share a common set of functions and uses. In
+ its simplest definition, a <literal>stream</literal> is a
+ <literal>resource</literal> object which exhibits streamable
+ behavior. That is, it can be read from or written to in a linear
+ fashion, and may be able to <function>fseek</function> to an
+ arbitrary locations within the stream.
</simpara>
<simpara>
- In addition to streams, support for custom user filters is also available.
- While a stream (such as 'http') is designed to communicate with an endpoint,
- one or more filters can be placed between the stream and the application to
- further process the data as it is read/written.
+ A <literal>wrapper</literal> is additional code which tells the stream how to
+handle
+ specific protocols/encodings. For example, the <literal>http</literal>
+ wrapper knows how to translate a URL into an <literal>HTTP/1.1</literal>
+ request for a file on a remote server. There are many wrappers
+ built into <literal>PHP</literal> by default (See <xref linkend="wrappers"/>),
+ and additional, custom wrappers may be added either within a
+ PHP script using <function>stream_register_wrapper</function>,
+ or directly from an extension using the <xref linkend="streams"/>.
+ Because any variety of wrapper may be added to <literal>PHP</literal>,
+ there is no set limit on what can be done with them. To access the list
+ of currently registered wrappers, use <function>stream_get_wrappers</function>.
+ </simpara>
+ <simpara>
+ A <literal>filter</literal> is a final piece of code which may perform
+ opperations on data as it is being read from or written to a stream.
+ Filters may be defined in a <literal>PHP</literal> script using
+ <function>stream_register_filter</function> or in an extension using the
+ <xref linkend="streams"/>. To access the list of currently registered filters,
+ use <function>stream_get_filters</function>.
</simpara>
<para>
A stream is referenced as:
<parameter>scheme</parameter>://<parameter>target</parameter>
@@ -33,9 +45,11 @@
<listitem>
<simpara>
<parameter>scheme</parameter>(string) -
- The name of the stream wrapper to be used. Examples include: file,
+ The name of the wrapper to be used. Examples include: file,
http, https, ftp, ftps, compress.zlib, compress.bz2, ssl, tls, and php. See
- <xref linkend="wrappers"/> for a list of PHP builtin wrappers.
+ <xref linkend="wrappers"/> for a list of PHP builtin wrappers. If
+ no wrapper is specified, the function default is used (typically
+ <literal>file</literal>://).
</simpara>
</listitem>
<listitem>
@@ -43,7 +57,7 @@
<parameter>target</parameter> -
Depends on the wrapper used. For filesystem related streams this is
typically a path and filename of the desired file. For network related
- streams this is typically a hostname often with a path appended. Again, see
+ streams this is typically a hostname, often with a path appended. Again, see
<xref linkend="wrappers"/> for a description of targets for builtin streams.
</simpara>
</listitem>
@@ -85,7 +99,34 @@
<section id="stream.constants">
&reftitle.constants;
- &no.constants;
+ <para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Constant</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><constant>STREAM_USE_PATH</constant></entry>
+ <entry><literal>Flag</literal> indicating if the <literal>stream</literal>
+ used the include path.
+ </entry>
+ </row>
+ <row>
+ <entry><constant>STREAM_REPORT_ERRORS</constant></entry>
+ <entry><literal>Flag</literal> indicating if the <literal>wrapper</literal>
+ if responsible for raising errors using <function>trigger_error</function>
+ during opening of the stream. If this flag is not set, you
+ should not raise any errors.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
</section>
<section id="stream.errors">
Index: phpdoc/en/reference/stream/functions/stream-register-filter.xml
diff -u phpdoc/en/reference/stream/functions/stream-register-filter.xml:1.1
phpdoc/en/reference/stream/functions/stream-register-filter.xml:1.2
--- phpdoc/en/reference/stream/functions/stream-register-filter.xml:1.1 Sat Jan 4
02:17:18 2003
+++ phpdoc/en/reference/stream/functions/stream-register-filter.xml Sat Jan 4
+23:25:06 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<refentry id="function.stream-register-filter">
<refnamediv>
<refname>stream_register_filter</refname>
@@ -45,6 +45,27 @@
so that the next filter in the chain can perform its filter.
When no filters remain, the stream will write <parameter>data</parameter>
in its final form.
+ <note>
+ <para>
+ If your filter alters the length of <parameter>data</parameter>, for
+ example by removing the first character, before passing onto
+ <literal>parent::write($data);</literal> it must be certain to include
+ that stolen character in the return count.
+ </para>
+ </note>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+class myfilter extends php_user_filter {
+ function write($data) {
+ $data = substr($data,1);
+ $written_by_parent = parent::write($data);
+ return ($written_by_parent + 1);
+ }
+}
+]]>
+ </programlisting>
+ </informalexample>
</para>
<methodsynopsis>
@@ -88,13 +109,23 @@
<type>void</type><methodname>oncreate</methodname>
<void/>
</methodsynopsis>
- <!-- When is this called? -->
+ <para>
+ This method is called during instantiation of the filter class
+ object. If your filter allocates or initializes any other resources
+ (such as a buffer), this is the place to do it.
+ </para>
<methodsynopsis>
<type>void</type><methodname>onclose</methodname>
<void/>
</methodsynopsis>
- <!-- When is this called? -->
+ <para>
+ This method is called upon filter shutdown (typically, this is also
+ during stream shutdown), and is executed <emphasis>after</emphasis>
+ the <literal>flush</literal> method is called. If any resources
+ were allocated or initialzed during <literal>oncreate</literal>
+ this would be the time to destroy or dispose of them.
+ </para>
<para>
The example below implements a filter named <literal>rot13</literal>
Index: phpdoc/en/reference/stream/functions/stream-get-filters.xml
+++ phpdoc/en/reference/stream/functions/stream-get-filters.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.stream-get-filters">
<refnamediv>
<refname>stream_get_filters</refname>
<refpurpose>Retrieve list of registered filters</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>stream_get_filters</methodname>
<void/>
</methodsynopsis>
<para>
Returns an indexed array containing the name of all stream filters
available on the running system.
</para>
<para>
See Also:
<function>stream_register_filter</function>, and
<function>stream_get_wrappers</function>
</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:"../../../../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
-->
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
