<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.31 $ -->
<reference id="ref.com"> 
  <title>COM support functions for Windows</title> 
  <titleabbrev>COM</titleabbrev> 
  <partintro> 
   <simpara>
    COM is a technology which allows the reuse of code written in any
    language (by any language) using a standard calling convention and hiding
    behind APIs the implementation details such as what machine the Component is
    stored on and the executable which houses it. It can be thought of as a super
    Remote Procedure Call (RPC) mechanism with some basic object roots. It
    separates implementation from interface.
   </simpara> 
   <simpara>
    COM encourages versioning, separation of implementation from
    interface and hiding the implementation details such as executable location and
    the language it was written in.
   </simpara> 
   <simpara>
    COM functions are only available on the Windows version of PHP.
   </simpara> 
   <simpara>
    For further information on COM read the <ulink url="&url.comspecs;">COM
    specification</ulink> or perhaps take a look at Don Box's 
    <ulink url="&url.yacl;"> Yet Another COM Library (YACL)</ulink> 
   </simpara> 
  </partintro> 
 
 <refentry id="class.com">
  <refnamediv>
   <refname>COM</refname>
   <refpurpose>COM class</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
  <synopsis>$obj = new <classname>COM</classname>("server.object")</synopsis>
  </refsynopsisdiv>
  <refsect1 id="class.com.class">
   <title>Description</title>
   <simpara>
    The COM class provides a framework to integrate (D)COM components into
    your php scripts.
   </simpara>
  </refsect1>
  <refsect1 id="class.com.constructor">
   <title>Methods</title>
    <methodsynopsis>
     <type>string</type><methodname>COM::COM</methodname>
     <methodparam><type>string</type><parameter>module_name</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>server_name</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>codepage</parameter></methodparam>
    </methodsynopsis>
   <para>
    COM class constructor. Parameters:
    <variablelist>
    <varlistentry><term>module_name</term>
    <listitem>
     <simpara>
      name or class-id of the requested component.
     </simpara>
    </listitem>
    </varlistentry>
    <varlistentry><term>server_name</term>
    <listitem>
     <simpara>
      name of the DCOM server from which the component should be fetched.
      If &null;, <literal>localhost</literal> is assumed.
      To allow DCOM <constant>com.allow_dcom</constant> has to be set to 
      &true; in <filename>php.ini</filename>.
     </simpara>
    </listitem>
    </varlistentry>
    <varlistentry><term>codepage</term>
    <listitem>
     <simpara>
      specifies the codepage that is used to convert php-strings to
      unicode-strings and vice versa. Possible values are
      <constant>CP_ACP</constant>, <constant>CP_MACCP</constant>,
      <constant>CP_OEMCP</constant>, <constant>CP_SYMBOL</constant>,
      <constant>CP_THREAD_ACP</constant>, <constant>CP_UTF7</constant>
      and <constant>CP_UTF8</constant>.
     </simpara>
    </listitem>
    </varlistentry>
    </variablelist>
   </para>
   <para>
    <example id="example.com1">
     <title>COM example (1)</title>
     <programlisting role="php">
<![CDATA[
// starting word
$word = new COM("word.application") or die("Unable to instanciate Word");
print "Loaded Word, version {$word->Version}\n";

//bring it to front
$word->Visible = 1;

//open an empty document
$word->Documents->Add();

//do some weird stuff
$word->Selection->TypeText("This is a test...");
$word->Documents[1]->SaveAs("Useless test.doc");

//closing word
$word->Quit();

//free the object
$word->Release();
$word = null;
]]>
     </programlisting>
    </example>
   </para>
   <para>
    <example id="example.com2">
     <title>COM example (2)</title>
     <programlisting role="php">
<![CDATA[
$conn = new COM("ADODB.Connection") or die("Cannot start ADO");
$conn->Open("Provider=SQLOLEDB; Data Source=localhost;
Initial Catalog=database; User ID=user; Password=password");

$rs = $conn->Execute("SELECT * FROM sometable");    // Recordset

$num_columns = $rs->Fields->Count();
echo $num_columns . "\n";

for ($i=0; $i < $num_columns; $i++)
{
    $fld[$i] = $rs->Fields($i);
}

$rowcount = 0;
while (!$rs->EOF)
{
    for ($i=0; $i < $num_columns; $i++)
    {
        echo $fld[$i]->value . "\t";
    }
    echo "\n";
    $rowcount++;            // increments rowcount
    $rs->MoveNext();
}

$rs->Close();
$conn->Close();

$rs->Release();
$conn->Release();

$rs = null;
$conn = null;
]]>
     </programlisting>
    </example>
   </para>
  </refsect1>
 </refentry>
 
 <refentry id="class.variant">
  <refnamediv>
   <refname>VARIANT</refname>
   <refpurpose>VARIANT class</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
  <synopsis>$vVar = new <classname>VARIANT</classname>($var)</synopsis>
  </refsynopsisdiv>
  <refsect1 id="class.variant.class">
   <title>Description</title>
   <simpara>
    A simple container to wrap variables into VARIANT structures.
   </simpara>
  </refsect1>
  <refsect1 id="class.variant.constructor">
   <title>Methods</title>
    <methodsynopsis>
     <type>string</type><methodname>VARIANT::VARIANT</methodname>
     <methodparam choice="opt"><type>mixed</type><parameter>value</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>type</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>codepage</parameter></methodparam>
    </methodsynopsis>
   <para>
    VARIANT class constructor. Parameters:
    <variablelist>
    <varlistentry><term>value</term>
    <listitem>
     <simpara>
      initial value. if omitted an VT_EMPTY object is created.
     </simpara>
    </listitem>
    </varlistentry>
    <varlistentry><term>type</term>
    <listitem>
     <simpara>
      specifies the content type of the VARIANT object. Possible values are
      <constant>VT_UI1</constant>, <constant>VT_UI2</constant>, <constant>VT_UI4</constant>, 
      <constant>VT_I1</constant>, <constant>VT_I2</constant>, <constant>VT_I4</constant>, 
      <constant>VT_R4</constant>, <constant>VT_R8</constant>, <constant>VT_INT</constant>, <constant>VT_UINT</constant>,
      <constant>VT_BOOL</constant>, <constant>VT_ERROR</constant>, <constant>VT_CY</constant>, 
      <constant>VT_DATE</constant>, <constant>VT_BSTR</constant>, <constant>VT_DECIMAL</constant>, 
      <constant>VT_UNKNOWN</constant>, <constant>VT_DISPATCH</constant> and <constant>VT_VARIANT</constant>. These values are
      mutual exclusive, but they can be combined with <constant>VT_BYREF</constant> to specify being a value. If omitted,
      the type of <parameter>value</parameter> is used. Consult the msdn library for additional information.
     </simpara>
    </listitem>
    </varlistentry>
    <varlistentry><term>codepage</term>
    <listitem>
     <simpara>
      specifies the codepage that is used to convert php-strings to
      unicode-strings and vice versa. Possible values are
      <constant>CP_ACP</constant>, <constant>CP_MACCP</constant>,
      <constant>CP_OEMCP</constant>, <constant>CP_SYMBOL</constant>,
      <constant>CP_THREAD_ACP</constant>, <constant>CP_UTF7</constant>
      and <constant>CP_UTF8</constant>.
     </simpara>
    </listitem>
    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
 </refentry>
 
 <refentry id="function.com-load">
  <refnamediv>
   <refname>com_load</refname>
   <refpurpose>
    Creates a new reference to a COM component
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>string</type><methodname>com_load</methodname>
     <methodparam><type>string</type><parameter>module name</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>
      server name
      </parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>
      codepage
      </parameter></methodparam>
    </methodsynopsis>
   <para>
    <function>com_load</function> creates a new COM component and
    returns a reference to it. Returns &false; on failure. Possible
    values for <parameter>codepage</parameter> are
    <constant>CP_ACP</constant>, <constant>CP_MACCP</constant>,
    <constant>CP_OEMCP</constant>, <constant>CP_SYMBOL</constant>,
    <constant>CP_THREAD_ACP</constant>, <constant>CP_UTF7</constant>
    and <constant>CP_UTF8</constant>.
   </para>
  </refsect1>
 </refentry>
 
 <refentry id="function.com-invoke">
  <refnamediv>
   <refname>com_invoke</refname>
   <refpurpose>
    Calls a COM component's method.
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>mixed</type><methodname>com_invoke</methodname>
     <methodparam><type>resource</type><parameter>com_object</parameter></methodparam>
     <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
     <methodparam choice="opt"><type>mixed</type><parameter>
      function parameters, ...
      </parameter></methodparam>
    </methodsynopsis>
   <para>
    <function>com_invoke</function> invokes a method of the COM
    component referenced by
    <parameter>com_object</parameter>. Returns
    &false; on error, returns the
    <parameter>function_name</parameter>'s return value on success.
   </para>
  </refsect1>
 </refentry>
 
 <refentry id="function.com-propget">
  <refnamediv>
   <refname>com_propget</refname>
   <refpurpose>
    Gets the value of a COM Component's property
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>mixed</type><methodname>com_propget</methodname>
     <methodparam><type>resource</type><parameter>com_object</parameter></methodparam>
     <methodparam><type>string</type><parameter>property</parameter></methodparam>
    </methodsynopsis>
   <para>
    This function is an alias for <function>com_get</function>.
   </para>
  </refsect1>
 </refentry>
 
 <refentry id="function.com-get">
  <refnamediv>
   <refname>com_get</refname>
   <refpurpose>
    Gets the value of a COM Component's property
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>mixed</type><methodname>com_get</methodname>
     <methodparam><type>resource</type><parameter>com_object</parameter></methodparam>
     <methodparam><type>string</type><parameter>property</parameter></methodparam>
    </methodsynopsis>
   <para>
    Returns the value of the <parameter>property</parameter> of the
    COM component referenced by <parameter>com_object</parameter>.
    Returns &false; on error.
   </para>
  </refsect1>
 </refentry>
 
 <refentry id="function.com-propput">
  <refnamediv>
   <refname>com_propput</refname>
   <refpurpose>
    Assigns a value to a COM component's property
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>void</type><methodname>com_propput</methodname>
     <methodparam><type>resource</type><parameter>com_object</parameter></methodparam>
     <methodparam><type>string</type><parameter>property</parameter></methodparam>
     <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
    </methodsynopsis>
   <para>
    This function is an alias for <function>com_set</function>.    
   </para>
  </refsect1>
 </refentry>
 
 <refentry id="function.com-propset">
  <refnamediv>
   <refname>com_propset</refname>
   <refpurpose>
    Assigns a value to a COM component's property
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>void</type><methodname>com_propset</methodname>
     <methodparam><type>resource</type><parameter>com_object</parameter></methodparam>
     <methodparam><type>string</type><parameter>property</parameter></methodparam>
     <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
    </methodsynopsis>
   <para>
    This function is an alias for <function>com_set</function>.
   </para>
  </refsect1>
 </refentry>
 
 <refentry id="function.com-set">
  <refnamediv>
   <refname>com_set</refname>
   <refpurpose>
    Assigns a value to a COM component's property
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>void</type><methodname>com_set</methodname>
     <methodparam><type>resource</type><parameter>com_object</parameter></methodparam>
     <methodparam><type>string</type><parameter>property</parameter></methodparam>
     <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
    </methodsynopsis>
   <para>
    Sets the value of the <parameter>property</parameter> of the COM
    component referenced by <parameter>com_object</parameter>.
    Returns the newly set value if succeeded, &false; on error.
   </para>
  </refsect1>
 </refentry>
 
 <refentry id="function.com-addref">
  <refnamediv>
   <refname>com_addref</refname>
   <refpurpose>
    Increases the components reference counter.
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
      <type>void</type><methodname>com_addref</methodname>
      <void/>
    </methodsynopsis>
   <para>
    Increases the components reference counter.
   </para>
  </refsect1>
 </refentry>
 
 <refentry id="function.com-release">
  <refnamediv>
   <refname>com_release</refname>
   <refpurpose>
    Decreases the components reference counter.
   </refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
      <type>void</type><methodname>com_release</methodname>
      <void/>
    </methodsynopsis>
   <para>
    Decreases the components reference counter.
   </para>
  </refsect1>
 </refentry>

  <refentry id='function.com-isenum'>
   <refnamediv>
    <refname>com_isenum</refname>
    <refpurpose>Grabs an IEnumVariant</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>com_isenum</methodname>
      <methodparam><type>object</type><parameter>com_module</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.com-load-typelib'>
   <refnamediv>
    <refname>com_load_typelib</refname>
    <refpurpose>Loads a Typelib</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>com_load_typelib</methodname>
      <methodparam><type>string</type><parameter>typelib_name</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>case_insensitive</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

</reference>

<!-- 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:"../../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
-->