cvs: phpdoc /en/reference/stream constants.xml reference.xml

pollita Fri Apr 11 01:47:43 2003 EDT Modified files: /phpdoc/en/reference/stream reference.xml constants.xml Log: Additional context documentation, reorg refernce slightly

Index: phpdoc/en/reference/stream/reference.xml diff -u phpdoc/en/reference/stream/reference.xml:1.11 phpdoc/en/reference/stream/reference.xml:1.12 --- phpdoc/en/reference/stream/reference.xml:1.11 Sun Feb 23 12:18:27 2003 +++ phpdoc/en/reference/stream/reference.xml Fri Apr 11 01:47:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.11 $ --> +<!-- $Revision: 1.12 $ --> <reference id="ref.stream"> <title>Stream functions</title> <titleabbrev>Streams</titleabbrev> @@ -31,6 +31,10 @@ 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> + </section> + + <section id="stream.filters"> + <title>Stream Filters</title> <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. @@ -66,9 +70,54 @@ </para> </section> - <section id="stream.requirements"> - &reftitle.required; - &no.requirement; + <section id="stream.contexts"> + <title>Stream Contexts</title> + <simpara> + A <literal>context</literal> is a set of <literal>parameters</literal> and + wrapper specific <literal>options</literal> which modify or enhance the + behavior of a stream. <literal>Contexts</literal> are created using + <function>stream_context_create</function> and can be passed to most + filesystem realted stream creation functions (i.e. <function>fopen</function>, + <function>file</function>, <function>file_get_contents</function>, etc...). + </simpara> + <simpara> + <literal>Options</literal> can be specified when calling + <function>stream_context_create</function>, or later using + <function>stream_context_set_option</function>. + + A list of wrapper specific <literal>options</literal> can be found with + the list of built-in wrappers (See <xref linkend="wrappers"/>). + </simpara> + <simpara> + In addition, <literal>parameters</literal> may be set on a <literal>context</literal> + using <function>stream_context_set_params</function>. Currently the only + <literal>context parameter</literal> supported by <literal>PHP</literal> is + <literal>notification</literal>. The value of this parameter must be the + name of a function to be called when an event occurs on a stream. + The notification function called during an event should accept the following + six parameters: + </simpara> + <methodsynopsis> + <type>void</type><methodname>my_notifier</methodname> + <methodparam><type>int</type><parameter>notification_code</parameter></methodparam> + <methodparam><type>int</type><parameter>severity</parameter></methodparam> + <methodparam><type>string</type><parameter>message</parameter></methodparam> + <methodparam><type>int</type><parameter>message_code</parameter></methodparam> + <methodparam><type>int</type><parameter>bytes_transferred</parameter></methodparam> + <methodparam><type>int</type><parameter>bytes_max</parameter></methodparam> + </methodsynopsis> + <simpara> + <parameter>notification_code</parameter> and <parameter>severity</parameter> + are numerical values which correspond to the <constant>STREAM_NOTIFY_*</constant> + constants listed below. + + If a descriptive message is available from the stream, <parameter>message</parameter> + and <parameter>message_code</parameter> will be populated with the appropriate values. + The meaning of these values is dependant on the specific wrapper in use. + + <parameter>bytes_transferred</parameter> and <parameter>bytes_max</parameter> will + be populated when applicable. + </simpara> </section> <section id="stream.installation"> @@ -77,11 +126,6 @@ Streams are an integral part of <literal>PHP</literal> as of version 4.3.0. No steps are required to enable them. </para> - </section> - - <section id="stream.configuration"> - &reftitle.runtime; - &no.config; </section> <section id="stream.resources"> Index: phpdoc/en/reference/stream/constants.xml diff -u phpdoc/en/reference/stream/constants.xml:1.4 phpdoc/en/reference/stream/constants.xml:1.5 --- phpdoc/en/reference/stream/constants.xml:1.4 Fri Apr 4 14:57:00 2003 +++ phpdoc/en/reference/stream/constants.xml Fri Apr 11 01:47:43 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <section id="stream.constants"> &reftitle.constants; &extension.constants; @@ -96,6 +96,94 @@ <entry>Tells a stream created with <function>stream_socket_server</function> and bound using the <constant>STREAM_SERVER_BIND</constant> flag to start listening on the socket. Server sockets should always include this flag. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_RESOLVE</constant></entry> + <entry> + A remote address required for this stream has been resolved, or the resolution + failed. See <parameter>severity</parameter> for an indication of which happened. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_CONNECT</constant></entry> + <entry> + A connection with an external resource has been established. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_AUTH_REQUIRED</constant></entry> + <entry> + Additional authorization is required to access the specified resource. + Typical issued with <parameter>severity</parameter> level of + <constant>STREAM_NOTIFY_SEVERITY_ERR</constant>. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_MIME_TYPE_IS</constant></entry> + <entry> + The <literal>mime-type</literal> of resource has been identified, + refer to <parameter>message</parameter> for a description of the + discovered type. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_FILE_SIZE_IS</constant></entry> + <entry> + The <literal>size</literal> of the resource has been discovered. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_REDIRECTED</constant></entry> + <entry> + The external resource has redirected the stream to an alternate + location. Refer to <parameter>message</parameter>. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_PROGRESS</constant></entry> + <entry> + Indicates current progress of the stream transfer in + <parameter>byets_transferred</parameter> and possibly + <parameter>bytes_max</parameter> as well. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_COMPLETED</constant></entry> + <entry> + There is no more data available on the stream. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_FAILURE</constant></entry> + <entry> + A generic error occured on the stream, consult + <parameter>message</parameter> and <parameter>message_code</parameter> + for details. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_AUTH_RESULT</constant></entry> + <entry> + Authorization has been completed (with or without success). + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_SEVERITY_INFO</constant></entry> + <entry> + Normal, non-error realted, notification. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_SEVERITY_WARN</constant></entry> + <entry> + Non critical error condition. Processing may continue. + </entry> + </row> + <row> + <entry><constant>STREAM_NOTIFY_SEVERITY_ERR</constant></entry> + <entry> + A critical error occured. Processing cannot continue. </entry> </row> </tbody>