doc-fr/reference/com/functions/class.com.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.23 $ -->
<!-- EN-Revision: 1.10 Maintainer: yannick Status: ready -->
 <refentry id="class.com">
  <refnamediv>
   <refname>COM</refname>
   <refpurpose>Classe COM</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
  <synopsis>$obj = new <classname>COM</classname>("Application.ID")</synopsis>
  </refsynopsisdiv>
  <refsect1 id="class.com.class">
   &reftitle.description;
   <simpara>
    La classe COM vous permet d'instancier un objet COM compatible OLE, d'appeler ces méthodes
    et d'accéder à ces propriétés.
   </simpara>
  </refsect1>
  <refsect1 id="class.com.constructor">
   <title>Méthodes</title>
    <methodsynopsis>
     <type>com</type><methodname>COM::COM</methodname>
     <methodparam><type>string</type><parameter>module_name</parameter></methodparam>
     <methodparam choice="opt"><type>mixed</type><parameter>server_name</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>codepage</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>typelib</parameter></methodparam>
    </methodsynopsis>
   <para>
    Constructeur de la classe COM. Paramètres :
    <variablelist>
    <varlistentry><term>module_name</term>
    <listitem>
     <simpara>
      Peut être un ProgID, un Class ID ou un Moniker qui nomment un composant à charger.
     </simpara>
     <simpara>
      Un ProgID est typiquement une application ou le nom d'une DLL, suivi d'une période, 
      suivi par le nom de l'objet. e.g : <literal>Word.Application</literal>.
     </simpara>
     <simpara>
      Un Class ID est un UUID qui identifie de manière unique une classe donnée.
     </simpara>
     <simpara>
      Un Moniker est une manière spéciale de nommage, similaire dans le concept au schéma d'URL,
      qui identifie une ressource et spécifie comment elle doit être chargée. 
      Par exemple, vous pouvez charger Word et prendre un objet représentant
      un document Word en spécifiant le chemin complet du document Word comme nom de module,
      ou bien, vous pouvez utiliser <literal>LDAP:</literal> comme un Moniker pour utiliser
      l'interface ADSI pour LDAP.
     </simpara>
    </listitem>
    </varlistentry>
    <varlistentry><term>server_name</term>
    <listitem>
     <simpara>
      Le nom du serveur DCOM sur lequel le composant devrait être chargé et lancé.
      Si le paramètre vaut &null;, l'objet courant utilisera la valeur par défaut pour l'application.
      La valeur par défaut est typiquement <literal>localhost</literal> bien que l'administrateur
      peut avoir configuré l'application pour qu'elle s'exécute sur une machine différente.
     </simpara>
     <simpara>
      Si vous spécifiez une valeur non-&null; pour le serveur, &php; peut refuser de charger 
      l'objet tant que <xref linkend="ini.com.allow-dcom"/> l'option de configuration ne vaut pas &true;.
     </simpara>
     <para>
      Si <parameter>server_name</parameter> est un tableau, il doit contenir 
      les éléments suivants (sensible à la casse). Notez qu'ils sont tous optionnels (bien que vous devez 
      spécifier et USERNAME, et PASSWORD) ; si vous omettez les paramètres du serveur, 
      le serveur par défaut sera utiliser (comme mentionné plus haut), et l'instanciation de l'objet ne
      sera pas affecté par <xref linkend="ini.com.allow-dcom"/> la directive.
      <table>
       <title>DCOM server name</title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry>clé <parameter>server_name</parameter></entry>
          <entry>type</entry>
          <entry>description</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>Server</entry>
          <entry>chaîne</entry>
          <entry>Le nom du serveur.</entry>
         </row>
         <row>
          <entry>Username</entry>
          <entry>chaîne</entry>
          <entry>L'utilisateur de connexion.</entry>
         </row>
         <row>
          <entry>Password</entry>
          <entry>chaîne</entry>
          <entry>Le mot de passe de l'utilisateur <parameter>Username</parameter>.</entry>
         </row>
         <row>
          <entry>Flags</entry>
          <entry>&integer;</entry>
          <entry>Une ou plusieurs des constantes suivantes
           <constant>CLSCTX_INPROC_SERVER</constant>,
           <constant>CLSCTX_INPROC_HANDLER</constant>,
           <constant>CLSCTX_LOCAL_SERVER</constant>,
           <constant>CLSCTX_REMOTE_SERVER</constant>,
           <constant>CLSCTX_SERVER</constant> et
           <constant>CLSCTX_ALL</constant>. La valeur par défaut est 
           <constant>CLSCTX_SERVER</constant> si vous omettez également
           <parameter>Server</parameter>, ou bien 
           <constant>CLSCTX_REMOTE_SERVER</constant> si vous spécifiez un serveur.
           Vous devriez consulter la dcumentation Mcrosoft concernant CoCreateInstance pour 
           plus d'informations sur cesconstantes ; vous ne devriez pas les utiliser dans un cas
           typique.
          </entry>
         </row>
        </tbody>
        </tgroup>
       </table>
      </para>
    </listitem>
    </varlistentry>
    <varlistentry><term>codepage</term>
    <listitem>
     <simpara>
      Spécifie le code qui est utilisé pour transformer les chaînes de
      caractères &php; en chaînes unicode, et vice-versa. La conversion est appliquée même
      si une chaîne &php; est passée en paramètre ou bien retournée d'une méthode de cette
      objet COM. Le code est "collé" en &php; 5, ce qui siginifie qu'il se propagera aux objets
      et aux variables retournés par cette objet.
     </simpara>
     <simpara>
      Les valeurs possibles sont : 
      <constant>CP_ACP</constant> (utilise le code système par défaut 
      d'ANSI - valeur par défaut si le paramètre est omis), 
      <constant>CP_MACCP</constant>,
      <constant>CP_OEMCP</constant>, <constant>CP_SYMBOL</constant>,
      <constant>CP_THREAD_ACP</constant> (utilise la valeur du code local pour
      l'exécution courant), <constant>CP_UTF7</constant> et 
      <constant>CP_UTF8</constant>. Vous devriez également utiliser le numéro
      pour un code donné ; consultez la documentation de Microsoft pour plus 
      de détails sur les codes et leurs valeurs numériques.
     </simpara>
    </listitem>
    </varlistentry>
    </variablelist>
   </para>
   </refsect1>
   
   
   <refsect1 id="class.com.overloadedmethods">
   <title>Méthodes surchargés</title>

   <para>
    L'objet retourné est un objet surchargé, ce qui signifie que &php; ne voit
    aucune méthode fixe comme il le fait avec les classes habituelles ; au lieu de cela, 
    chaque accès à une propriété ou une méthode est effectué à travers COM.
   </para>

   <para>
    A partir de &php; 5, &php; détectera automatiquement les méthodes qui acceptent
    les paramètres par référence, et convertira automatiquement les variables &php; classiques
    en une forme pouvant être passée par référence. Cela signifie que vous pouvez appeler
    les méthodes de façon naturelle ; vous n'avez pas d'efforts supplémentaires à faire dans votre code.
   </para>

   <para>
    En &php; 4, pour passer les paramètres par référence, vous devez créer une instance 
    de <xref linkend="class.variant"/> la classe pour utiliser les paramètres par référence.
   </para>

  </refsect1>
  
  <refsect1 id="class.com.falsemethods">
   <title>Les pseudos méthodes</title>
   
   <para>
    Dans les versions antérieures à &php; 5, des hacks faisaient que les noms des méthodes suivantes
    n'étaient pas passés à COM et étaient directement gérés par &php;. &php; 5 élimine cela ; 
    lisez les détails suivants pour déterminer comment corrger vos scripts. Ces noms de méthodes
    ne sont pas sensibles à la casse.
   </para>

    <methodsynopsis>
     <type>void</type><methodname>COM::AddRef</methodname>
     <void/>
    </methodsynopsis>
    <simpara>
     Ajoute artificiellement un compteur de référence à l'objet COM.
    </simpara>
    <warning>
     <simpara>
      Vous ne devriez jamais avoir besoin d'utiliser cette méthode. Il existe un complément logique
      à la méthode Release() ci-dessous.
     </simpara>
    </warning>
    
    <methodsynopsis>
     <type>void</type><methodname>COM::Release</methodname>
     <void/>
    </methodsynopsis>
    <simpara>
     Supprime artificellement un compteur de référence à un objet COM.
    </simpara>
    <warning>
     <simpara>
      Vous ne devriez jamais avoir besoin d'utiliser cette méthode. Son existence en &php; est un bogue
      fait pour résoudre un autre bogue qui conserve les objets COM fonctionnels plus 
      longtemps qu'ils ne devraient l'être.
    </simpara>
   </warning>
   </refsect1>
   
   <refsect1 id="class.com.iteratormethods">
    <title>Les pseudos méthodes pour itération</title>
    
    <para>
     Ces pseudos méthodes ne sont valables que si <function>com_isenum</function>
     retourne &true; et dans ce cas, elles cachent toutes autres méthodes portant le même nom
     qui pourraient provenir de l'objet COM. Ces méthodes ont été éliminées de &php; 5, et vous devez
     utiliser <xref linkend="com.foreach"/> en lieu et place.
    </para>

    <methodsynopsis>
     <type>variant</type><methodname>COM::All</methodname>
     <void/>
    </methodsynopsis>
    <simpara>
     Retourne une variante représentant un "SafeArray" qui possède 10 éléments ; 
     chaque élément sera une variante vide ou nulle. Cette fonction 
     est supposée retourner un tableau contenant tous les éléments de l'itération,
     mais ne sera jamais complet. Ne pas l'utiliser.
    </simpara>

    <methodsynopsis>
     <type>variant</type><methodname>COM::Next</methodname>
     <void/>
    </methodsynopsis>
    <simpara>
     Retourne une variante représentant l'élément disponible suivant de l'itération ou 
     &false; lorsqu'il n'y a plus d'élément.
    </simpara>

    <methodsynopsis>
     <type>variant</type><methodname>COM::Prev</methodname>
     <void/>
    </methodsynopsis>
    <simpara>
     Retourne une variante représentant l'élément disponible précédent de l'itération ou 
     &false; lorsqu'il n'y a plus d'élément.
    </simpara>

    <methodsynopsis>
     <type>void</type><methodname>COM::Reset</methodname>
     <void/>
    </methodsynopsis>
    <simpara>
     Replace l'itération au début.
    </simpara>
   </refsect1>
   
   <refsect1 id="class.com.examples">
    <title>COM examples</title> 
   <para>
    <example id="example.com1">
     <title>Exemple COM (1)</title>
     <programlisting role="php">
<![CDATA[
<?php

/* Démarrage de Word */
$word = new COM("word.application") or die("Impossible d'instancier l'application Word");
echo "Word lancé, version {$word->Version}\n";

/* Amener Word devant */
$word->Visible = 1;

/* Cree un document vide */
$word->Documents->Add();

/* Quelques commandes */
$word->Selection->TypeText("Ceci est un test...");
$word->Documents[1]->SaveAs("test.doc");

/* Fermeture de word */
$word->Quit();

/* Libération des ressources */
$word = null;
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    <example id="example.com2">
     <title>Exemple COM (2)</title>
     <programlisting role="php">
<![CDATA[
<?php
$conn = new COM("ADODB.Connection") or die("Impossible de démarrer ADO");
$conn->Open("Provider=SQLOLEDB; Data Source=localhost;
Initial Catalog=database; User ID=user; Password=password");

/* Jeux d'enregistrement */
$rs = $conn->Execute("SELECT * FROM sometable");    

$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";
    
    /* Incrémentation */
    $rowcount++;
    $rs->MoveNext();
}

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

$rs = null;
$conn = null;

?>
]]>
     </programlisting>
    </example>
   </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:"../../../../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
-->