cvs: phpdoc /en/chapters streams.common.xml streams.structs.xml streams.xml

pollita Thu May 8 17:04:24 2003 EDT Modified files: /phpdoc/en/chapters streams.common.xml streams.structs.xml streams.xml Log: A few extra chunks of streams api documentation.

Index: phpdoc/en/chapters/streams.common.xml diff -u phpdoc/en/chapters/streams.common.xml:1.5 phpdoc/en/chapters/streams.common.xml:1.6 --- phpdoc/en/chapters/streams.common.xml:1.5 Mon May 5 20:11:18 2003 +++ phpdoc/en/chapters/streams.common.xml Thu May 8 17:04:24 2003 @@ -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 Index: phpdoc/en/chapters/streams.structs.xml diff -u phpdoc/en/chapters/streams.structs.xml:1.2 phpdoc/en/chapters/streams.structs.xml:1.3 --- phpdoc/en/chapters/streams.structs.xml:1.2 Sun Jan 19 05:11:24 2003 +++ phpdoc/en/chapters/streams.structs.xml Thu May 8 17:04:24 2003 @@ -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> Index: phpdoc/en/chapters/streams.xml diff -u phpdoc/en/chapters/streams.xml:1.6 phpdoc/en/chapters/streams.xml:1.7 --- phpdoc/en/chapters/streams.xml:1.6 Fri Jan 24 13:34:34 2003 +++ phpdoc/en/chapters/streams.xml Thu May 8 17:04:24 2003 @@ -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