From ea5012655f5671dad26f4788a59c4df5992045dc Mon Sep 17 00:00:00 2001
From: Sara Golemon <pollita@php.net>
Date: Thu, 8 May 2003 21:04:24 +0000
Subject: [PATCH] A few extra chunks of streams api documentation.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@126289 c90b9560-bf6c-de11-be94-00142212c4b1
---
 chapters/streams.common.xml  | 60 ++++++++++++++++++++--
 chapters/streams.structs.xml | 96 +++++++++++++++++++++++++++++++++++-
 chapters/streams.xml         | 11 ++++-
 3 files changed, 159 insertions(+), 8 deletions(-)

diff --git a/chapters/streams.common.xml b/chapters/streams.common.xml
index 634b641938..ddb9e721e5 100755
--- a/chapters/streams.common.xml
+++ b/chapters/streams.common.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <!-- Author: Wez Furlong <wez@thebrainroom.com>
   Please contact me before making any major amendments to the
   content of this section.  Splitting/Merging are fine if they are
@@ -975,10 +975,60 @@
      into an ANSI stdio FILE* and returns that instead of the stream.
      This is a convenient shortcut for extensions that pass FILE* to third-party libraries.
     </para>
-    </refsect1>
-    </refentry>
-
-  
+   </refsect1>
+  </refentry>
+  <refentry id="streams.php-stream-filter-register-facory">
+   <refnamediv>
+    <refname>php_stream_filter_register_factory</refname>
+    <refpurpose>Registers a filter factory with the Streams API</refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+    <methodsynopsis>
+     <type>int</type><methodname>php_stream_filter_register_factory</methodname>
+     <methodparam><type>const char *</type><parameter>filterpattern</parameter></methodparam>
+     <methodparam><type>php_stream_filter_factory *</type><parameter>factory</parameter></methodparam>
+    </methodsynopsis>
+    <para>
+     Use this function to register a filter factory with the name given by
+     <parameter>filterpattern</parameter>.  <parameter>filterpattern</parameter>
+     can be either a normal string name (i.e. <literal>myfilter</literal>) or
+     a global pattern (i.e. <literal>myfilterclass.*</literal>) to allow a single
+     filter to perform different operations depending on the exact name of the filter
+     invoked (i.e. <literal>myfilterclass.foo</literal>, <literal>myfilterclass.bar</literal>,
+     etc...)
+    </para>
+    <note>
+     <simpara>
+      Filters registered by a loadable extension must be certain to call
+      php_stream_filter_unregister_factory() during MSHUTDOWN.
+     </simpara>
+    </note>
+   </refsect1>
+  </refentry>
+  <refentry id="streams.php-stream-filter-unregister-facory">
+   <refnamediv>
+    <refname>php_stream_filter_unregister_factory</refname>
+    <refpurpose>Deregisters a filter factory with the Streams API</refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+    <methodsynopsis>
+     <type>int</type><methodname>php_stream_filter_unregister_factory</methodname>
+     <methodparam><type>const char *</type><parameter>filterpattern</parameter></methodparam>
+    </methodsynopsis>
+    <para>
+     Deregisters the <parameter>filterfactory</parameter> specified by the
+     <parameter>filterpattern</parameter> making it no longer available for use.
+    </para>
+    <note>
+     <simpara>
+      Filters registered by a loadable extension must be certain to call
+      php_stream_filter_unregister_factory() during MSHUTDOWN.
+     </simpara>
+    </note>
+   </refsect1>
+  </refentry>
 </sect1>
 
 <!-- Keep this comment at the end of the file
diff --git a/chapters/streams.structs.xml b/chapters/streams.structs.xml
index e1bc721bc5..c66f4e5ad8 100755
--- a/chapters/streams.structs.xml
+++ b/chapters/streams.structs.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- Author: Wez Furlong <wez@thebrainroom.com>
   Please contact me before making any major amendments to the
   content of this section.  Splitting/Merging are fine if they are
@@ -72,8 +72,102 @@
      </programlisting>
     </refsect1>
   </refentry>
+  <refentry id="streams.struct-php-stream-wrapper">
+    <refnamediv>
+        <refname>struct php_stream_wrapper</refname>
+        <refpurpose>Holds wrapper properties and pointer to operations</refpurpose>
+    </refnamediv>
+    <refsect1>
+     <title>Description</title>
+     <programlisting role="c">
+        struct _php_stream_wrapper  {
+            php_stream_wrapper_ops *wops;   /* operations the wrapper can perform */
+            void *abstract;                 /* context for the wrapper */
+            int is_url;                     /* so that PG(allow_url_fopen) can be respected */
 
+            /* support for wrappers to return (multiple) error messages to the stream opener */
+            int err_count;
+            char **err_stack;
+        } php_stream_wrapper;
+     </programlisting>
+    </refsect1>
+  </refentry>
+  <refentry id="streams.struct-php-stream-wrapper-ops">
+    <refnamediv>
+        <refname>struct php_stream_wrapper_ops</refname>
+        <refpurpose>Holds member functions for a stream wrapper implementation</refpurpose>
+    </refnamediv>
+    <refsect1>
+     <title>Description</title>
+     <programlisting role="c">
+        typedef struct _php_stream_wrapper_ops {
+            /* open/create a wrapped stream */
+            php_stream *(*stream_opener)(php_stream_wrapper *wrapper, char *filename, char *mode,
+                    int options, char **opened_path, php_stream_context *context STREAMS_DC TSRMLS_DC);
+            /* close/destroy a wrapped stream */
+            int (*stream_closer)(php_stream_wrapper *wrapper, php_stream *stream TSRMLS_DC);
+            /* stat a wrapped stream */
+            int (*stream_stat)(php_stream_wrapper *wrapper, php_stream *stream, php_stream_statbuf *ssb TSR$
+            /* stat a URL */
+            int (*url_stat)(php_stream_wrapper *wrapper, char *url, php_stream_statbuf *ssb TSRMLS_DC);
+            /* open a "directory" stream */
+            php_stream *(*dir_opener)(php_stream_wrapper *wrapper, char *filename, char *mode,
+                    int options, char **opened_path, php_stream_context *context STREAMS_DC TSRMLS_DC);
 
+            const char *label;
+        } php_stream_wrapper_ops;
+     </programlisting>
+    </refsect1>
+  </refentry>
+  <refentry id="streams.struct-php-stream-filter">
+    <refnamediv>
+        <refname>struct php_stream_filter</refname>
+        <refpurpose>Holds filter properties and pointer to operations</refpurpose>
+    </refnamediv>
+    <refsect1>
+     <title>Description</title>
+     <programlisting role="c">
+        struct _php_stream_filter {
+            php_stream_filter_ops *fops;
+            void *abstract; /* for use by filter implementation */
+            php_stream_filter *next;
+            php_stream_filter *prev;
+            int is_persistent;
+
+            /* link into stream and chain */
+            php_stream_filter_chain *chain;
+
+            /* buffered buckets */
+            php_stream_bucket_brigade buffer;
+        } php_stream_filter;
+     </programlisting>
+    </refsect1>
+  </refentry>
+  <refentry id="streams.struct-php-stream-filter-ops">
+    <refnamediv>
+        <refname>struct php_stream_filter_ops</refname>
+        <refpurpose>Holds member functions for a stream filter implementation</refpurpose>
+    </refnamediv>
+    <refsect1>
+     <title>Description</title>
+     <programlisting role="c">
+        typedef struct _php_stream_filter_ops {
+            php_stream_filter_status_t (*filter)(
+                    php_stream *stream,
+                    php_stream_filter *thisfilter,
+                    php_stream_bucket_brigade *buckets_in,
+                    php_stream_bucket_brigade *buckets_out,
+                    size_t *bytes_consumed,
+                    int flags
+                    TSRMLS_DC);
+
+            void (*dtor)(php_stream_filter *thisfilter TSRMLS_DC);
+
+            const char *label;
+} php_stream_filter_ops;
+     </programlisting>
+    </refsect1>
+  </refentry>
  </sect1>
  
  
diff --git a/chapters/streams.xml b/chapters/streams.xml
index 4d14506281..3416fd9594 100755
--- a/chapters/streams.xml
+++ b/chapters/streams.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <!-- Author: Wez Furlong <wez@thebrainroom.com>
   Please contact me before making any major amendments to the
   content of this section.  Splitting/Merging are fine if they are
@@ -32,7 +32,14 @@
     the API defines php_stream objects to represent streamable data sources.
     On a slightly higher level, the API defines php_stream_wrapper objects
     which "wrap" around the lower level API to provide support for retrieving
-    data and meta-data from URLs.
+    data and meta-data from URLs.  An additional <literal>context</literal>
+    parameter, accepted by most stream creation functions, is passed to the
+    wrapper's <literal>stream_opener</literal> method to fine-tune the behavior
+    of the wrapper.
+  </para>
+  <para>
+   Any stream, once opened, can also have any number of <literal>filters</literal>
+   applied to it, which process data as it is read from/written to the stream.
   </para>
   <para>
    Streams can be cast (converted) into other types of file-handles, so that they