win32-create-service.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 95fe2d7de6477ae5e28ae2e6f11eb4025f427b4f Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes Maintainer: Marqitos -->
<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>Crea una nueva entrada para servicio en la base de datos 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>
   Intenta añadir un servicio en la base de datos SCM. Se necesitan privilegios
   de administrador para que esto tenga éxito.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>details</parameter></term>
     <listitem>
      <para>
       Un array de detalles del servicio:
       <variablelist>
        <varlistentry>
         <term><parameter>service</parameter></term>
         <listitem>
          <para>
           El nombre corto del servicio. Este es el nombre que se utilizará
           para controlar el servicio utilizando el comando
           <literal>net</literal>. El servicio debe ser único (dos servicios
           no pueden compartir el mismo nombre), e idealmente, debería evitar
           tener espacios en su nombre.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>display</parameter></term>
         <listitem>
          <para>El nombre de visualización del servicio. Este es el nombre que se verá
           en la Applet Servicios.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>description</parameter></term>
         <listitem>
          <para>
           La descripción larga del servicio.
           Esta es la descripción que se verá en la Applet de Servicios.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>user</parameter></term>
         <listitem>
          <para>
           El nombre de usuario bajo el cual se desea que el servicio se ejecute. Si se omite, el servicio funcionará como
           LocalSystem. Si se especifica el nombre de usuario, también se debe proporcionar una contraseña.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>password</parameter></term>
         <listitem>
          <para>
           La contraseña que corresponde a <parameter>user</parameter>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>path</parameter></term>
         <listitem>
          <para>
           La ruta completa al módulo ejecutable que se iniciará cuando el
           servicio se inicie. Si se omite, se utilizará la ruta del proceso actual de
           PHP.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>params</parameter></term>
         <listitem>
          <para>
           Argumentos de comando a pasar al servicio cuando se inicie.
           Si se desea ejecutar un script PHP como servicio, entonces
           el primer argumento debería ser la ruta completa al script PHP
           que se planea ejecutar. Si el nombre del script o la ruta
           contienen espacios, entonces, rodee la ruta completa del script
           PHP con <literal>"</literal>
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>load_order</parameter></term>
         <listitem>
          <para>
           Controla el load_order. Esto aún no está completamente soportado.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>svc_type</parameter></term>
         <listitem>
          <para>
           Establece el tipo de servicio. Si se omite, el valor por omisión es
           <constant>WIN32_SERVICE_WIN32_OWN_PROCESS</constant>. No se debe cambiar esto a menos que se sepa realmente lo que se está haciendo.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>start_type</parameter></term>
         <listitem>
          <para>
           Especifica cómo debe iniciarse el servicio. El valor por omisión es <constant>WIN32_SERVIDE_AUTO_START</constant> lo que significa que el servicio se iniciará cuando la máquina se inicie.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>error_control</parameter></term>
         <listitem>
          <para>
           Informa al SCM sobre qué hacer cuando detecte un problema con el servicio. El valor por omisión es
           <constant>WIN32_SERVER_ERROR_IGNORE</constant>. Cambiar este valor aún no está completamente soportado.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>delayed_start</parameter></term>
         <listitem>
          <para>
           Si <parameter>delayed_start</parameter> está establecido a
           &true;, entonces informará al SCM que este servicio debe iniciarse después de los servicios iniciados automáticamente y un cierto retraso.
          </para>
          <para>
           Cualquier servicio puede ser marcado como un servicio retrasado después del inicio automático; sin embargo, esta configuración no tiene ningún efecto mientras el parámetro <parameter>start_type</parameter>
           del servicio valga <constant>WIN32_SERVICE_AUTO_START</constant>.
          </para>
          <para>
           Esta configuración solo se aplica en Windows Vista y servidores Windows 2008 y posteriores.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>base_priority</parameter></term>
         <listitem>
          <para>
           Para reducir el impacto en el uso del procesador, puede ser necesario establecer una prioridad más baja que la normal.
          </para>
          <para>
           El parámetro <parameter>base_priority</parameter> puede ser establecido a
           una de las constantes definidas en las
           <link linkend="win32service.constants.basepriorities">clases de baja prioridad Win32</link>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>dependencies</parameter></term>
         <listitem>
          <para>
           Para definir las dependencias del servicio, es necesario establecer este parámetro con la lista de nombres de servicios en un array.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_delay</parameter></term>
         <listitem>
          <para>
           Este parámetro define el retraso entre el fallo y la ejecución de
           la acción de recuperación. El valor es en milisegundos.
          </para>
          <para>
           El valor por omisión es 60000.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_action_1</parameter></term>
         <listitem>
          <para>
           La acción que se ejecutará en caso de la primera falla. La acción por omisión es <constant>WIN32_SC_ACTION_NONE</constant>.
          </para>
          <para>
           El parámetro <parameter>recovery_action_1</parameter> puede ser establecido
           con una de las constantes definidas en las
           <link linkend="win32service.constants.recovery-action">Acciones de recuperación Win32</link>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_action_2</parameter></term>
         <listitem>
          <para>
           La acción que se ejecutará en caso de la segunda falla. La acción por omisión es <constant>WIN32_SC_ACTION_NONE</constant>.
          </para>
          <para>
           El parámetro <parameter>recovery_action_2</parameter> puede ser establecido
           con una de las constantes definidas en las
           <link linkend="win32service.constants.recovery-action">Acciones de recuperación Win32</link>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_action_3</parameter></term>
         <listitem>
          <para>
           La acción que se ejecutará en caso de fallas subsiguientes. La acción por omisión es <constant>WIN32_SC_ACTION_NONE</constant>.
          </para>
          <para>
           El parámetro <parameter>recovery_action_3</parameter> puede ser establecido
           con una de las constantes definidas en las
           <link linkend="win32service.constants.recovery-action">Acciones de recuperación Win32</link>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_reset_period</parameter></term>
         <listitem>
          <para>
           El contador de fallas se reiniciará después del retraso definido
           en este parámetro. El retraso se expresa en segundos.
          </para>
          <para>
           El valor por omisión es <literal>86400</literal>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_enabled</parameter></term>
         <listitem>
          <para>
           Establecer este parámetro a &true; para habilitar las opciones de recuperación, y &false;
           para deshabilitarlas.
          </para>
          <para>
           El valor por omisión es &false;
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_reboot_msg</parameter></term>
         <listitem>
          <para>
           Añadir este parámetro para definir el mensaje registrado en el registro
           de eventos de Windows antes del reinicio. Solo se utiliza si una
           de las acciones está definida a
           <constant>WIN32_SC_ACTION_REBOOT</constant>.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_command</parameter></term>
         <listitem>
          <para>
           Añadir este parámetro para definir el comando a ejecutar cuando una
           acción está definida a
           <constant>WIN32_SC_ACTION_RUN_COMMAND</constant>.
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>machine</parameter></term>
     <listitem>
      <para>
       El nombre opcional de la máquina en la que se desea crear el servicio.
       Si se omite, se utilizará la máquina local.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.void;
  </para>
  <para>
    Antes de la versión 1.0.0, &win32service.noerror.false.error;
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Se lanzará una <classname>ValueError</classname> si el valor del parámetro
   <parameter>service</parameter> está vacío.
  </para>
  <para>
   Se lanzará una <classname>ValueError</classname> si el valor del parámetro
   <parameter>path</parameter> está omitido o vacío.
  </para>
  <para>
   Se lanzará una <classname>ValueError</classname> si el valor del parámetro
   <parameter>svc_type</parameter> es incorrecto.
  </para>
  <para>
   Se lanzará una <classname>ValueError</classname> si el valor del parámetro
   <parameter>start_type</parameter> es incorrecto.
  </para>
  <para>
   Se lanzará una <classname>ValueError</classname> si el valor del parámetro
   <parameter>error_control</parameter> es incorrecto.
  </para>
  <para>
   Se lanzará una <classname>ValueError</classname> si el valor del parámetro
   <parameter>base_priority</parameter> es incorrecto.
  </para>
  <para>
   Se lanzará una <classname>ValueError</classname> si el valor del parámetro
   <parameter>recovery_delay</parameter> no está entre
   0 y PHP_INT_MAX.
  </para>
  <para>
   Se lanzará una <classname>ValueError</classname> si el valor del parámetro
   <parameter>recovery_action_1</parameter> es incorrecto.
  </para>
  <para>
   Se lanzará una <classname>ValueError</classname> si el valor del parámetro
   <parameter>recovery_action_2</parameter> es incorrecto.
  </para>
  <para>
   Se lanzará una <classname>ValueError</classname> si el valor del parámetro
   <parameter>recovery_action_3</parameter> es incorrecto.
  </para>
  <para>
   Se lanzará una <classname>ValueError</classname> si el valor del parámetro
   <parameter>recovery_reset_period</parameter> no está entre
   0 y PHP_INT_MAX.
  </para>
  <para>
   Se lanzará una <classname>Win32ServiceException</classname> en caso de error.
  </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>
        Se lanzará una <classname>ValueError</classname> si un parámetro es inválido,
        antes &false; era devuelto.
       </entry>
      </row>
      <row>
       <entry>PECL win32service 1.0.0</entry>
       <entry>
        Se lanzará una <classname>Win32ServiceException</classname> en caso de error,
        antes un
        <link xmlns="http://docbook.org/ns/docbook" linkend="win32service.constants.errors">Código de error Win32</link>
        era devuelto.
       </entry>
      </row>
      <row>
       <entry>PECL win32service 1.0.0</entry>
       <entry>
        El tipo de retorno ahora es <type>void</type>, antes era <type>mixed</type>.
       </entry>
      </row>
      <row>
       <entry>PECL win32service 0.4.0</entry>
       <entry>
        Los parámetros <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>
        y <parameter>recovery_command</parameter> han sido añadidos.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo con <function>win32_create_service</function></title>
    <para>
     Crea un servicio cuyo nombre corto es 'dummyphp'.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
\$x = win32_create_service(array(
    'service'     => 'dummyphp',                                          // el nombre del servicio
    'display'     => 'ejemplo de servicio PHP ficticio',                  // la descripción corta
    'description' => 'Este es un servicio Windows creado utilizando PHP', // la descripción larga
    'params'      => '"' . __FILE__ . '"  run',                           // ruta al script así como los argumentos
));
debug_zval_dump(\$x);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Un ejemplo <function>win32_create_service</function> con dependencias</title>
    <para>
     Crea un servicio cuyo nombre corto es 'dummyphp' con dependencias.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
\$x = win32_create_service(array(
    'service'      => 'dummyphp',                                                    // El nombre del servicio
    'display'               => 'ejemplo de servicio PHP ficticio',                   // Una descripción corta
    'description'           => 'Este es un servicio Windows creado utilizando PHP.', // Una descripción larga
    'params'                => '"' . __FILE__ . '"  run',                            // ruta al script así como los argumentos
    'dependencies' => array("Netman"),                                               // La lista de dependencias
));
debug_zval_dump(\$x);
?>
]]>
     </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Ejemplo de <function>win32_create_service</function> con opciones de recuperación</title>
    <para>
     Crea un servicio cuyo nombre corto es 'dummyphp' con opciones de recuperación.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
\$x = win32_create_service(array(
    'service'               => 'dummyphp',                                           // El nombre del servicio
    'display'               => 'ejemplo de servicio PHP ficticio',                   // Una descripción corta
    'description'           => 'Este es un servicio Windows creado utilizando PHP.', // Una descripción larga
    'params'                => '"' . __FILE__ . '"  run',                            // ruta al script así como los argumentos
    'recovery_delay'        => 120000,                                               // Las acciones de recuperación se ejecutarán después de 2 minutos
    'recovery_action_1'     => WIN32_SC_ACTION_RESTART,                              // Primera falla, reiniciar el servicio
    'recovery_action_2'     => WIN32_SC_ACTION_RUN_COMMAND,                          // Segunda falla, ejecutar un comando
    'recovery_action_3'     => WIN32_SC_ACTION_NONE,                                 // Fallas subsiguientes, no hacer nada
    'recovery_reset_period' => 86400,                                                // Reiniciar el contador de fallas después de 1 día (86400 minutos)
    'recovery_enabled'      => true,                                                 // Habilitar las opciones de recuperación
    'recovery_reboot_msg'   => null,                                                 // No definir un mensaje de reinicio, no es útil.
    'recovery_command'      => "c:\clean-service.bat",                               // Cuando la acción es WIN32_SC_ACTION_RUN_COMMAND, ejecutar este comando.
));
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">Las clases de baja prioridad Win32</link></member>
    <member><link linkend="win32service.constants.recovery-action">Las acciones de recuperación Win32</link></member>
    <member><link linkend="win32service.constants.errors">Los códigos de error 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
-->