Additional context documentation, reorg refernce slightly

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@123120 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Sara Golemon 2003-04-11 05:47:43 +00:00
parent a57f482b31
commit c8458e7fcc
2 changed files with 142 additions and 10 deletions

View file

@ -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;
@ -98,6 +98,94 @@
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>
</tgroup>
</informaltable>

View file

@ -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">
@ -79,11 +128,6 @@
</para>
</section>
<section id="stream.configuration">
&reftitle.runtime;
&no.config;
</section>
<section id="stream.resources">
<title>Stream Classes</title>
<simpara>