Document com_get_active_object().

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@158252 c90b9560-bf6c-de11-be94-00142212c4b1

reference/com/functions/com-get-active-object.xml

@@ -0,0 +1,79 @@
+<?xml version='1.0' encoding='iso-8859-1'?>
+<!-- $Revision: 1.1 $ -->
+  <refentry id="function.com-get-active-object">
+   <refnamediv>
+    <refname>com_get_active_object</refname>
+    <refpurpose>
+     Returns a handle to an already running instance of a COM object
+    </refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+    <methodsynopsis>
+     <type>object</type><methodname>com_get_active_object</methodname>
+     <methodparam><type>string</type><parameter>progid</parameter></methodparam>
+     <methodparam choice="opt"><type>int</type><parameter>code_page</parameter></methodparam>
+    </methodsynopsis>
+
+    <para>
+     <function>com_get_active_object</function> is similar to creating a new
+     instance of a <xref linkend="class.com"/> object, except that it will
+     only return an object to your script if the object is already running.
+     OLE applications use something known as the Running Object Table to
+     allow well-known applications to be launched only once; this function
+     exposes the COM library function GetActiveObject() to get a handle on a
+     running instance.
+    </para>
+    <para>
+     <parameter>progid</parameter> must be either the ProgID or CLSID for the
+     object that you want to access (for example
+     <literal>Word.Application</literal>).  <parameter>code_page</parameter>
+     acts in precisely the same way that it does for the <xref
+     linkend="class.com"/> class.
+    </para>
+    <para>
+     If the requestested object is running, it will be returned to your script
+     just like any other COM object.  Otherwise a <literal>com_exception</literal>
+     will be raised.  There are a variety of reasons why
+     this function might fail, the most common being that the object is not
+     already running.  In that situation, the exception error code will be
+     <constant>MK_E_UNAVAILABLE</constant>; you can use the
+     <literal>getCode</literal> method of the exception object to check the
+     exception code.
+    </para>
+
+    <warning>
+     <para>
+      Using <function>com_get_active_object</function> in a web server context
+      is not always a smart idea.  Most COM/OLE applications are not designed
+      to handle more than one client concurrently, even (or especially!)
+      Microsoft Office.  You should read <ulink
+      url="&url.msoffice.serverside;">Considerations for Server-Side
+      Automation of Office</ulink> for more information on the general issues
+      involved.
+     </para>
+    </warning>
+
+   </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:"../../../../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
+-->