stream-notification-callback.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<refentry xml:id="function.stream-notification-callback" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>stream_notification_callback</refname>
  <refpurpose>A callback function for the <literal>notification</literal> context parameter</refpurpose>
 </refnamediv>
 
 <refsect1 role="description"><!-- {{{ -->
  &reftitle.description;
  <methodsynopsis>
   <type>void</type><methodname><replaceable>stream_notification_callback</replaceable></methodname>
   <methodparam><type>int</type><parameter>notification_code</parameter></methodparam>
   <methodparam><type>int</type><parameter>severity</parameter></methodparam>
   <methodparam><type class="union"><type>string</type><type>null</type></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>
  <para>
   A <type>callable</type> function, used by the
   <link linkend="context.params.notification">notification context parameter</link>,
   called during an event.
  </para>
  <note>
   <para>
    This is <emphasis>not</emphasis> a real function, only a prototype of how the function should
    be.
   </para>
  </note>
 </refsect1><!-- }}} -->
 
 <refsect1 role="parameters"><!-- {{{ -->
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>notification_code</parameter></term>
     <listitem>
      <para>
       One of the <constant>STREAM_NOTIFY_<replaceable>*</replaceable></constant> notification constants.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>severity</parameter></term>
     <listitem>
      <para>
       One of the <constant>STREAM_NOTIFY_SEVERITY_<replaceable>*</replaceable></constant> notification constants.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>message</parameter></term>
     <listitem>
      <para>
       Passed if a descriptive message is available for the event.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>message_code</parameter></term>
     <listitem>
      <para>
       Passed if a descriptive message code is available for the event.
      </para>
      <para>
       The meaning of this value is dependent on the specific wrapper in use.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>bytes_transferred</parameter></term>
     <listitem>
      <para>
       If applicable, the <parameter>bytes_transferred</parameter> will be
       populated.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>bytes_max</parameter></term>
     <listitem>
      <para>
       If applicable, the <parameter>bytes_max</parameter> will be
       populated.
      </para>
     </listitem>
    </varlistentry>

   </variablelist>
  </para>
 </refsect1><!-- }}} -->
 
 <refsect1 role="returnvalues"><!-- {{{ -->
  &reftitle.returnvalues;
  <para>
   &return.void;
  </para>
 </refsect1><!-- }}} -->

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.3.0</entry>
      <entry>
       Support for <constant>STREAM_NOTIFY_COMPLETED</constant> implemented,
       earlier PHP versions would never trigger this notification.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples"><!-- {{{ -->
  &reftitle.examples;
  <para>
   <example xml:id="stream-notification-callback.example.basic"><!-- {{{ -->
    <title><function>stream_notification_callback</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
function stream_notification_callback($notification_code, $severity, $message, $message_code, $bytes_transferred, $bytes_max) {

    switch($notification_code) {
        case STREAM_NOTIFY_RESOLVE:
        case STREAM_NOTIFY_AUTH_REQUIRED:
        case STREAM_NOTIFY_COMPLETED:
        case STREAM_NOTIFY_FAILURE:
        case STREAM_NOTIFY_AUTH_RESULT:
            var_dump($notification_code, $severity, $message, $message_code, $bytes_transferred, $bytes_max);
            /* Ignore */
            break;

        case STREAM_NOTIFY_REDIRECTED:
            echo "Being redirected to: ", $message;
            break;

        case STREAM_NOTIFY_CONNECT:
            echo "Connected...";
            break;

        case STREAM_NOTIFY_FILE_SIZE_IS:
            echo "Got the filesize: ", $bytes_max;
            break;

        case STREAM_NOTIFY_MIME_TYPE_IS:
            echo "Found the mime-type: ", $message;
            break;

        case STREAM_NOTIFY_PROGRESS:
            echo "Made some progress, downloaded ", $bytes_transferred, " so far";
            break;
    }
    echo "\n";
}

$ctx = stream_context_create();
stream_context_set_params($ctx, array("notification" => "stream_notification_callback"));

file_get_contents("http://php.net/contact", false, $ctx);
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Connected...
Found the mime-type: text/html; charset=utf-8
Being redirected to: http://no.php.net/contact
Connected...
Got the filesize: 0
Found the mime-type: text/html; charset=utf-8
Being redirected to: http://no.php.net/contact.php
Connected...
Got the filesize: 4589
Found the mime-type: text/html;charset=utf-8
Made some progress, downloaded 0 so far
Made some progress, downloaded 0 so far
Made some progress, downloaded 0 so far
Made some progress, downloaded 1440 so far
Made some progress, downloaded 2880 so far
Made some progress, downloaded 4320 so far
Made some progress, downloaded 5760 so far
Made some progress, downloaded 6381 so far
Made some progress, downloaded 7002 so far
]]>
    </screen>
   </example><!-- }}} -->
  </para>
  <para>
   <example xml:id="stream-notification-callback.example.download"><!-- {{{ -->
    <title>Simple progressbar for commandline download client</title>
    <programlisting role="php">
<![CDATA[
<?php
function usage($argv) {
    echo "Usage:\n";
    printf("\tphp %s <http://example.com/file> <localfile>\n", $argv[0]);
    exit(1);
}

function stream_notification_callback($notification_code, $severity, $message, $message_code, $bytes_transferred, $bytes_max) {
    static $filesize = null;

    switch($notification_code) {
    case STREAM_NOTIFY_RESOLVE:
    case STREAM_NOTIFY_AUTH_REQUIRED:
    case STREAM_NOTIFY_COMPLETED:
    case STREAM_NOTIFY_FAILURE:
    case STREAM_NOTIFY_AUTH_RESULT:
        /* Ignore */
        break;

    case STREAM_NOTIFY_REDIRECTED:
        echo "Being redirected to: ", $message, "\n";
        break;

    case STREAM_NOTIFY_CONNECT:
        echo "Connected...\n";
        break;

    case STREAM_NOTIFY_FILE_SIZE_IS:
        $filesize = $bytes_max;
        echo "Filesize: ", $filesize, "\n";
        break;

    case STREAM_NOTIFY_MIME_TYPE_IS:
        echo "Mime-type: ", $message, "\n";
        break;

    case STREAM_NOTIFY_PROGRESS:
        if ($bytes_transferred > 0) {
            if (!isset($filesize)) {
                printf("\rUnknown filesize.. %2d kb done..", $bytes_transferred/1024);
            } else {
                $length = (int) (($bytes_transferred/$filesize)*100);
                printf("\r[%-100s] %d%% (%2d/%2d kb)", str_repeat("=", $length). ">", $length, ($bytes_transferred/1024), $filesize/1024);
            }
        }
        break;
    }
}

isset($argv[1], $argv[2]) or usage($argv);

$ctx = stream_context_create();
stream_context_set_params($ctx, array("notification" => "stream_notification_callback"));

$fp = fopen($argv[1], "r", false, $ctx);
if (is_resource($fp) && file_put_contents($argv[2], $fp)) {
    echo "\nDone!\n";
    exit(0);
}

$err = error_get_last();
echo "\nErrrrrorr..\n", $err["message"], "\n";
exit(1);
?>
]]>
    </programlisting>
    <para>
     Executing the example above with:
     <literal>php -n fetch.php
     http://no2.php.net/get/php-5-LATEST.tar.bz2/from/this/mirror
     php-latest.tar.bz2</literal> will output something similar too:
    </para>
    <screen>
<![CDATA[
Connected...
Mime-type: text/html; charset=utf-8
Being redirected to: http://no2.php.net/distributions/php-5.2.5.tar.bz2
Connected...
Filesize: 7773024
Mime-type: application/octet-stream
[========================================>                                                           ] 40% (3076/7590 kb)
]]>
    </screen>
   </example>
  </para>
 </refsect1><!-- }}} -->

 <refsect1 role="seealso"><!-- {{{ -->
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><xref linkend="context.params" /></member>
   </simplelist>
  </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:"~/.phpdoc/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
-->