com-event-sink.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.com-event-sink" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>com_event_sink</refname>
  <refpurpose>Connect events from a COM object to a PHP object</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>com_event_sink</methodname>
   <methodparam><type>variant</type><parameter>variant</parameter></methodparam>
   <methodparam><type>object</type><parameter>sink_object</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>string</type><type>null</type></type><parameter>sink_interface</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Instructs COM to sink events generated by
   <parameter>variant</parameter> into the PHP object
   <parameter>sink_object</parameter>.
  </para>
  <para>
   Be careful how you use this feature; if you are doing something similar
   to the example below, then it doesn't really make sense to run it in a
   web server context.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>variant</parameter></term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>sink_object</parameter></term>
     <listitem>
      <para>
       <parameter>sink_object</parameter> should be an instance of a class with
       methods named after those of the desired dispinterface; you may use
       <function>com_print_typeinfo</function> to help generate a template class
       for this purpose.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>sink_interface</parameter></term>
     <listitem>
      <para>
       PHP will attempt to use the default dispinterface type specified by
       the typelibrary associated with <parameter>variant</parameter>, but
       you may override this choice by setting
       <parameter>sink_interface</parameter> to the name of the dispinterface
       that you want to use.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </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.0.0</entry>
      <entry>
       <parameter>sink_interface</parameter> is nullable now.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>COM event sink example</title>
    <programlisting role="php">
<![CDATA[
<?php
class IEEventSinker {
    var $terminated = false;

   function ProgressChange($progress, $progressmax) {
      echo "Download progress: $progress / $progressmax\n";
    }

    function DocumentComplete(&$dom, $url) {
      echo "Document $url complete\n";
    }

    function OnQuit() {
      echo "Quit!\n";
      $this->terminated = true;
    }
}
$ie = new COM("InternetExplorer.Application");
$sink = new IEEventSinker();
com_event_sink($ie, $sink, "DWebBrowserEvents2");
$ie->Visible = true;
$ie->Navigate("http://www.example.org");
while(!$sink->terminated) {
  com_message_pump(4000);
}
$ie = null;
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <caution>
   <para>
    Prior to PHP 8.0.0, calling <function>exit</function> from any of the event
    handlers is not supported, and may cause PHP to hang. This can be worked around
    by throwing an exception from the event handler, catching the exception in
    the main code, and calling <function>exit</function> from there.
   </para>
  </caution>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>com_print_typeinfo</function></member>
    <member><function>com_message_pump</function></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
-->