win32-create-service.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 95fe2d7de6477ae5e28ae2e6f11eb4025f427b4f Maintainer: jbnahan Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.win32-create-service" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>win32_create_service</refname>
  <refpurpose>Crée une nouvelle entrée pour service dans la base de données SCM</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>void</type><methodname>win32_create_service</methodname>
   <methodparam><type>array</type><parameter>details</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>machine</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Tente d'ajouter un service dans la base de données SCM. Des privilèges 
   d'administrateur sont nécessaires pour que cela réussisse.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>details</parameter></term>
     <listitem>
      <para>
       Un tableau des détails des services :
       <variablelist>
        <varlistentry>
         <term><parameter>service</parameter></term>
         <listitem>
          <para>
           Le nom court du service. C'est le nom que vous utiliserez pour
           contrôler le service en utilisant la commande
           <literal>net</literal>. Le service doit être unique (deux services
           ne peuvent partager le même nom), et idéalement, devrait éviter
           d'avoir des espaces dans son nom.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>display</parameter></term>
         <listitem>
          <para>Le nom d'affichage du service. C'est le nom que vous verrez
           dans l'Applet Services.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>description</parameter></term>
         <listitem>
          <para>
           La description longue du service.
           C'est la description que vous verrez dans l'Applet des
           services.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>user</parameter></term>
         <listitem>
          <para>
           Le nom de l'utilisateur sous lequel vous voulez que le service
           s'exécute. Si oublié, le service fonctionnera en tant que
           LocalSystem. Si le nom de l'utilisateur est spécifié, vous devez
           aussi fournir un mot de passe.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>password</parameter></term>
         <listitem>
          <para>
           Le mot de passe qui correspond à <parameter>user</parameter>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>path</parameter></term>
         <listitem>
          <para>
           Le chemin complet au module exécutable qui sera démarré lorsque le
           service est démarré. Si oublié, le chemin du processus courant de
           PHP sera utilisé.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>params</parameter></term>
         <listitem>
          <para>
           Paramètres de commande à passer au service lorsqu'il démarre.
           Si vous voulez exécuter un script PHP en tant que service, alors
           le premier paramètre devrait être le chemin complet au script PHP
           que vous prévoyez exécuter. Si le nom du script ou le chemin 
           contiennent des espaces, alors, entourez le chemin complet du script
           PHP par des <literal>"</literal>
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>load_order</parameter></term>
         <listitem>
          <para>
           Contrôle le load_order. Cela n'est pas encore complètement
           supporté.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>svc_type</parameter></term>
         <listitem>
          <para>
           Fixe le type de service. Si oublié, la valeur par défaut est
           <constant>WIN32_SERVICE_WIN32_OWN_PROCESS</constant>. Ne changez
           pas ceci à moins que vous savez vraiment ce que vous faites.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>start_type</parameter></term>
         <listitem>
          <para>
           Spécifie comment le service devrait être démarré. La valeur par
           défaut est <constant>WIN32_SERVIDE_AUTO_START</constant> qui
           signifie que le service sera démarré lorsque la machine démarrera.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>error_control</parameter></term>
         <listitem>
          <para>
           Informe le SCM à propos de ce qu'il devrait faire lorsqu'il détecte
           un problème avec le service. La valeur par défaut est
           <constant>WIN32_SERVER_ERROR_IGNORE</constant>. Le changement de
           cette valeur n'est pas encore complètement supporté.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>delayed_start</parameter></term>
         <listitem>
          <para>
           Si <parameter>delayed_start</parameter> est défini à
           &true;, alors il informera le SCM que ce service doit être
           démarré après les services démarrés automatiquement et un certain
           délai.
          </para>
          <para>
           N'importe quel service peut être marqué comme étant un service
           retardé après le démarrage automatique ; cependant, cette configuration
           n'a aucun effet tant que le paramètre <parameter>start_type</parameter>
           du service vaut <constant>WIN32_SERVICE_AUTO_START</constant>.
          </para>
          <para>
           Cette configuration n'est application que sous Windows Vista et les
           serveurs Windows 2008 et suivants.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>base_priority</parameter></term>
         <listitem>
          <para>
           Pour réduire l'impacte sur l'utilisation du processeur, il peut
           être nécessaire de définir une priorité plus basse qu'à la normale.
          </para>
          <para>
           Le paramètre <parameter>base_priority</parameter> peut être défini à
           une des constantes définies dans les
           <link linkend="win32service.constants.basepriorities">classes de basse priorité Win32</link>.
          </para>
         </listitem>
        </varlistentry>        <varlistentry>
         <term><parameter>dependencies</parameter></term>
         <listitem>
          <para>
           Pour définir les dépendances de votre service, il est nécessaire de 
           définir ce paramètre avec la liste des noms des service dans un tableau.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_delay</parameter></term>
         <listitem>
          <para>
           Ce paramètre défini le délai entre la défaillance et l'exécution de 
           l'action de récupération. La valeur est en millisecondes.
          </para>
          <para>
           La valeur par défaut est 60000.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_action_1</parameter></term>
         <listitem>
          <para>
           L'action qui sera exécuté lors de la première défaillance. L'action 
           par défaut est <constant>WIN32_SC_ACTION_NONE</constant>.
          </para>
          <para>
           Le paramètre <parameter>recovery_action_1</parameter> peut être défini 
           avec l'une des constantes définie dans les
           <link linkend="win32service.constants.recovery-action">Actions de récupération Win32</link>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_action_2</parameter></term>
         <listitem>
          <para>
           L'action qui sera exécuté lors de la deuxième défaillance. L'action 
           par défaut est <constant>WIN32_SC_ACTION_NONE</constant>.
          </para>
          <para>
           Le paramètre <parameter>recovery_action_2</parameter> peut être défini 
           avec l'une des constantes définie dans les
           <link linkend="win32service.constants.recovery-action">Actions de récupération Win32</link>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_action_3</parameter></term>
         <listitem>
          <para>
           L'action qui sera exécuté lors des défaillances suivantes. L'action 
           par défaut est <constant>WIN32_SC_ACTION_NONE</constant>.
          </para>
          <para>
           Le paramètre <parameter>recovery_action_3</parameter> peut être défini 
           avec l'une des constantes définie dans les
           <link linkend="win32service.constants.recovery-action">Actions de récupération Win32</link>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_reset_period</parameter></term>
         <listitem>
          <para>
           Le compteur des défaillance sera réinitialisé après le délai défini 
           dans ce paramètre. Le délai est exprimé en secondes.
          </para>
          <para>
           La valeur par défaut est <literal>86400</literal>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_enabled</parameter></term>
         <listitem>
          <para>
           Définir ce paramètre à &true; pour activer les options de récupération, et &false; 
           pour les désactiver. 
          </para>
          <para>
           La valeur par défaut est &false;
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_reboot_msg</parameter></term>
         <listitem>
          <para>
           Ajouter ce paramètre pour définir le message enregistré dans le jounal 
           d'évènements Windows avant le redémarrage. Utilisé uniquement si l'une 
           des actions est défini à 
           <constant>WIN32_SC_ACTION_REBOOT</constant>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_command</parameter></term>
         <listitem>
          <para>
           Ajouter ce paramètre pour définir la commande a exécuter lorsqu'une 
           action est définie à 
           <constant>WIN32_SC_ACTION_RUN_COMMAND</constant>.
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>machine</parameter></term>
     <listitem>
      <para>
       Le nom optionnel de la machine sur lequel vous voulez créer le service.
       Si oublié, cela utilisera la machine locale.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.void;
  </para>
  <para>
    Avant la version 1.0.0, &win32service.noerror.false.error;
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Une <classname>ValueError</classname> est levée si la valeur du paramètre 
   <parameter>service</parameter>est vide.
  </para>
  <para>
   Une <classname>ValueError</classname> est levée si la valeur du paramètre 
   <parameter>path</parameter> est omis ou vide.
  </para>
  <para>
   Une <classname>ValueError</classname> est levée si la valeur du paramètre 
   <parameter>svc_type</parameter> est incorrect.
  </para>
  <para>
   Une <classname>ValueError</classname> est levée si la valeur du paramètre 
   <parameter>start_type</parameter> est incorrect.
  </para>
  <para>
   Une <classname>ValueError</classname> est levée si la valeur du paramètre 
   <parameter>error_control</parameter> est incorrect.
  </para>
  <para>
   Une <classname>ValueError</classname> est levée si la valeur du paramètre 
   <parameter>base_priority</parameter> est incorrect.
  </para>
  <para>
   Une <classname>ValueError</classname> est levée si la valeur du paramètre 
   <parameter>recovery_delay</parameter> n'est pas entre 
   0 et PHP_INT_MAX.
  </para>
  <para>
   Une <classname>ValueError</classname> est levée si la valeur du paramètre 
   <parameter>recovery_action_1</parameter> est incorrect.
  </para>
  <para>
   Une <classname>ValueError</classname> est levée si la valeur du paramètre 
   <parameter>recovery_action_2</parameter> est incorrect.
  </para>
  <para>
   Une <classname>ValueError</classname> est levée si la valeur du paramètre 
   <parameter>recovery_action_3</parameter> est incorrect.
  </para>
  <para>
   Une <classname>ValueError</classname> est levée si la valeur du paramètre 
   <parameter>recovery_reset_period</parameter> n'est pas entre 
    0 et PHP_INT_MAX.
  </para>
  <para>
   Une <classname>Win32ServiceException</classname> est levée en cas d'erreur.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>PECL win32service 1.0.0</entry>
       <entry>
        Lance une <classname>ValueError</classname> si un paramètre est invalide,
        avant &false; était retourné.
       </entry>
      </row>
      <row>
       <entry>PECL win32service 1.0.0</entry>
       <entry>
        Lance une <classname>Win32ServiceException</classname> en cas d'erreur,
        avant un
        <link xmlns="http://docbook.org/ns/docbook" linkend="win32service.constants.errors">Code d'erreur Win32</link>
        était retourné.
       </entry>
      </row>
      <row>
       <entry>PECL win32service 1.0.0</entry>
       <entry>
        Le type de retour est maintenant <type>void</type>, avant il était <type>mixed</type>.
       </entry>
      </row>
      <row>
       <entry>PECL win32service 0.4.0</entry>
       <entry>
        Les paramètres <parameter>dependencies</parameter>, <parameter>recovery_delay</parameter>,
        <parameter>recovery_action_1</parameter>, <parameter>recovery_action_2</parameter>,
        <parameter>recovery_action_3</parameter>, <parameter>recovery_reset_period</parameter>,
        <parameter>recovery_enabled</parameter>, <parameter>recovery_reboot_msg</parameter>
        et <parameter>recovery_command</parameter> ont été ajoutés.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>win32_create_service</function></title>
    <para>
     Crée un service dont le nom court est 'dummyphp'.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$x = win32_create_service(array(
    'service'     => 'dummyphp',                                        // le nom de votre service
    'display'     => 'service PHP simple PHP',                            // la description courte
    'description' => 'Ceci est un service Windows créé en utilisant PHP', // la description longue
    'params'      => '"' . __FILE__ . '"  run',                           // chemin vers le script ainsi que les paramètres
));
debug_zval_dump($x);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Un exemple <function>win32_create_service</function> avec les dépendances</title>
    <para>
     Crée un service dont le nom court est 'dummyphp' avec des dépendances.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$x = win32_create_service(array(
    'service'      => 'dummyphp',                                       // Le nom du service
    'display'               => 'service PHP simple PHP',                             // Une courte description
    'description'           => 'Ceci est un service Windows créé en utilisant PHP.', // Une longue description
    'params'                => '"' . __FILE__ . '"  run',                            // chemin vers le script ainsi que les paramètres
    'dependencies' => array("Netman"),                                      // La liste des dépendances
));
debug_zval_dump($x);
?>
]]>
     </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Exemple de <function>win32_create_service</function> avec les options de récupération</title>
    <para>
     Crée un service dont le nom court est 'dummyphp' avec les options de récupération.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$x = win32_create_service(array(
    'service'               => 'dummyphp',                                           // Le nom du service
    'display'               => 'service PHP simple PHP',                             // Une courte description
    'description'           => 'Ceci est un service Windows créé en utilisant PHP.', // Une longue description
    'params'                => '"' . __FILE__ . '"  run',                            // chemin vers le script ainsi que les paramètres
    'recovery_delay'        => 120000,                                               // Les actions de récupération seront exécuté après 2 minutes
    'recovery_action_1'     => WIN32_SC_ACTION_RESTART,                              // Première défaillance, redémarrage du service
    'recovery_action_2'     => WIN32_SC_ACTION_RUN_COMMAND,                          // Deuxième défaillance, exécution d'une commande
    'recovery_action_3'     => WIN32_SC_ACTION_NONE,                                 // Défaillance suivante, ne rien faire
    'recovery_reset_period' => 86400,                                                // Réinitialiser le compteur des défaillance après 1 jour (86400 minutes)
    'recovery_enabled'      => true,                                                 // Activer les options de récupération
    'recovery_reboot_msg'   => null,                                                 // Ne pas définir de message de redémarrage, il n'est pas utile.
    'recovery_command'      => "c:\clean-service.bat",                               // Lorsque l'action est WIN32_SC_ACTION_RUN_COMMAND, exécuter cette commande.
));
debug_zval_dump($x);
?>
]]>
     </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>win32_delete_service</function></member>
    <member><link linkend="win32service.constants.basepriorities">Les classes de basse priorité Win32</link></member>
    <member><link linkend="win32service.constants.recovery-action">Les actions de récupération Win32</link></member>
    <member><link linkend="win32service.constants.errors">Les codes erreurs Win32</link></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
-->