win32-create-service.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 95fe2d7de6477ae5e28ae2e6f11eb4025f427b4f Maintainer: takagi Status: ready -->
<!-- Generated by xml_proto.php v2.3. Found in /scripts directory of phpdoc. -->
<!-- Credits: mumumu -->
<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>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>
   SCM データベースに新しいサービスの追加を試みます。
   この操作を成功させるには、管理者権限が必要です。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>details</parameter></term>
     <listitem>
      <para>
       サービスの詳細情報を含む配列。
       <variablelist>
        <varlistentry>
         <term><parameter>service</parameter></term>
         <listitem>
          <para>
           サービスの短い名前。<literal>net</literal> コマンドでサービスを
           制御する際に、この名前を使用します。この名前は一意である（同名の
           サービスが 2 つ存在することがない）必要があり、スペースを含む
           名前は可能な限り避けるべきです。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>display</parameter></term>
         <listitem>
          <para>
           サービスの表示名。これは、サービスアプレットに表示される名前です。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>description</parameter></term>
         <listitem>
          <para>
           サービスの長い名前。これは「サービス」アプレットで表示される名前です。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>user</parameter></term>
         <listitem>
          <para>
           サービスを実行するユーザー名。指定しなかった場合、サービスは
           LocalSystem アカウントで実行されます。ユーザー名が指定された場合、
           password も指定する必要があります。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>password</parameter></term>
         <listitem>
          <para>
           <parameter>user</parameter> に対応するパスワード。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>path</parameter></term>
         <listitem>
          <para>
           サービスの開始時に起動される実行モジュールのフルパス。
           指定しなかった場合、現在の PHP プロセスへのパスが使用されます。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>params</parameter></term>
         <listitem>
          <para>
           サービスの開始時に渡されるコマンドラインパラメータ。
           PHP スクリプトをサービスとして実行したい場合は、最初のパラメータは
           実行するスクリプトへのフルパスとなります。
           スクリプト名やパスにスペースを含む場合は、PHP スクリプトへのフルパスを
           <literal>"</literal> で囲まなければなりません。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>load_order</parameter></term>
         <listitem>
          <para>
           load_order を制御します。現時点では完全にはサポートされていません。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>svc_type</parameter></term>
         <listitem>
          <para>
           サービスの型を指定します。指定しなかった場合、デフォルト値は
           <constant>WIN32_SERVICE_WIN32_OWN_PROCESS</constant> です。
           よくわからない場合はこの値を変更しないでください。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>start_type</parameter></term>
         <listitem>
          <para>
           サービスをどのように開始させるかを指定します。デフォルトは
           <constant>WIN32_SERVICE_AUTO_START</constant> で、これは
           マシンの起動時にサービスを開始させることを意味します。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>error_control</parameter></term>
         <listitem>
          <para>
           サービスに問題が発生した際にとるべき行動を SCM に指示します。
           デフォルトは <constant>WIN32_SERVER_ERROR_IGNORE</constant> です。
           この値を変更することは、現時点では完全にはサポートされていません。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>delayed_start</parameter></term>
         <listitem>
          <para>
           <parameter>delayed_start</parameter> を &true; にすると、
           他の自動起動サービスが開始したあとで少し間をおいてサービスが起動するようになります。
          </para>
          <para>
           任意のサービスに対してこれを指定することができますが、そのサービスの
           <parameter>start_type</parameter> が
           <constant>WIN32_SERVICE_AUTO_START</constant>
           でない場合は何の効果も及ぼしません。
          </para>
          <para>
           この設定が使えるのは、Windows Vista および Windows Server
           2008 以降のみです。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>base_priority</parameter></term>
         <listitem>
          <para>
           プロセッサの使用状況への影響を考慮すると、
           ベース優先度は通常より低めに設定しておかなければなりません。
          </para>
          <para>
           <parameter>base_priority</parameter> には、
           <link linkend="win32service.constants.basepriorities">Win32 ベース優先度クラス</link>
           で定義された定数のいずれかを設定します。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>dependencies</parameter></term>
         <listitem>
          <para>
           サービスへの依存性を定義します。
           サービス名の一覧を配列として設定する必要があるかもしれません。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_delay</parameter></term>
         <listitem>
          <para>
           失敗時とリカバリアクションの実行の間に取る時間を定義します。
           この値はマイクロ秒単位です。
          </para>
          <para>
           デフォルトは 60000 です。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_action_1</parameter></term>
         <listitem>
          <para>
           最初の失敗時に実行されるアクションです。
           デフォルトの値は <constant>WIN32_SC_ACTION_NONE</constant> です。
          </para>
          <para>
           <parameter>recovery_action_1</parameter> は、 
           <link linkend="win32service.constants.recovery-action">Win32 Recovery action</link>
           で定義された定数のうちのひとつを設定できます。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_action_2</parameter></term>
         <listitem>
          <para>
           二回目の失敗時に実行されるアクションです。
           デフォルトの値は <constant>WIN32_SC_ACTION_NONE</constant> です。
          </para>
          <para>
           <parameter>recovery_action_2</parameter> は、 
           <link linkend="win32service.constants.recovery-action">Win32 Recovery action</link>
           で定義された定数のうちのひとつを設定できます。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_action_3</parameter></term>
         <listitem>
          <para>
           3回目以降の失敗時に実行されるアクションです。
           デフォルトの値は <constant>WIN32_SC_ACTION_NONE</constant> です。
          </para>
          <para>
           <parameter>recovery_action_3</parameter> は、 
           <link linkend="win32service.constants.recovery-action">Win32 Recovery action</link>
           で定義された定数のうちのひとつを設定できます。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_reset_period</parameter></term>
         <listitem>
          <para>
           ここで定義された時間が経過すると、失敗のカウンタがリセットされます。
           秒単位で設定します。
          </para>
          <para>
           デフォルト値は <literal>86400</literal> です。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_enabled</parameter></term>
         <listitem>
          <para>
           リカバリ設定を有効にする場合は &true; を設定します。
           無効にする場合は &false; を設定します。
          </para>
          <para>
           デフォルトは &false; です。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_reboot_msg</parameter></term>
         <listitem>
          <para>
           リブート時に Windows のイベントログに記録されるメッセージを設定します。
           アクションを <constant>WIN32_SC_ACTION_REBOOT</constant> に設定する場合にだけ使ってください。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>recovery_command</parameter></term>
         <listitem>
          <para>
           アクションが <constant>WIN32_SC_ACTION_RUN_COMMAND</constant> に設定された場合に、実行されるコマンドを設定します。
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>machine</parameter></term>
     <listitem>
      <para>
       オプションで、サービスを作成したいマシン名を指定します。
       指定しなかった場合は、ローカルマシンを使用します。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.void;
  </para>
  <para>
   バージョン 1.0.0 より前では、&win32service.noerror.false.error;
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   <parameter>service</parameter> 引数が空の場合、
   <classname>ValueError</classname> がスローされます。
  </para>
  <para>
   <parameter>path</parameter> 引数が渡されていないか、空の場合、
   <classname>ValueError</classname> がスローされます。
  </para>
  <para>
   <parameter>svc_type</parameter> 引数が不正な場合は、
   <classname>ValueError</classname> がスローされます。
  </para>
  <para>
   <parameter>start_type</parameter> 引数が不正な場合は、
   <classname>ValueError</classname> がスローされます。
  </para>
  <para>
   <parameter>error_control</parameter> 引数が不正な場合は、
   <classname>ValueError</classname> がスローされます。
  </para>
  <para>
   <parameter>base_priority</parameter> 引数が不正な場合は、
   <classname>ValueError</classname> がスローされます。
  </para>
  <para>
   <parameter>recovery_delay</parameter> 引数が
   0 と PHP_INT_MAX の間にない場合は、
   <classname>ValueError</classname> がスローされます。
  </para>
  <para>
   <parameter>recovery_action_1</parameter> 引数が不正な場合は、
   <classname>ValueError</classname> がスローされます。
  </para>
  <para>
   <parameter>recovery_action_2</parameter> 引数が不正な場合は、
   <classname>ValueError</classname> がスローされます。
  </para>
  <para>
   <parameter>recovery_action_3</parameter> 引数が不正な場合は、
   <classname>ValueError</classname> がスローされます。
  </para>
  <para>
   <parameter>recovery_reset_period</parameter> 引数が
   0 と PHP_INT_MAX の間にない場合は、
   <classname>ValueError</classname> がスローされます。
  </para>
  <para>
   エラーが発生した場合は、<classname>Win32ServiceException</classname> がスローされます。
  </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>
        引数に不正な値があった場合、
        <classname>ValueError</classname> をスローするようになりました。
        これより前のバージョンでは、&false; を返していました。
       </entry>
      </row>
      <row>
       <entry>PECL win32service 1.0.0</entry>
       <entry>
        エラー時に
        <classname>Win32ServiceException</classname> をスローするようになりました。
        これより前のバージョンでは、
        <link xmlns="http://docbook.org/ns/docbook" linkend="win32service.constants.errors">Win32 エラーコード</link> を返していました。
       </entry>
      </row>
      <row>
       <entry>PECL win32service 1.0.0</entry>
       <entry>
        戻り値の型が <type>void</type> になりました。
        これより前のバージョンでは、<type>mixed</type> でした。
       </entry>
      </row>
      <row>
       <entry>PECL win32service 0.4.0</entry>
       <entry>
        <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>
        および <parameter>recovery_command</parameter> パラメータが追加されました。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1><!-- }}} -->

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>win32_create_service</function> の例</title>
    <para>
     'dummyphp' というショートネームのサービスを作ります。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$x = win32_create_service(array(
    'service'     => 'dummyphp',                                           // サービスの名前
    'display'     => 'sample dummy PHP service',                           // 短い説明
    'description' => 'This is a dummy Windows service created using PHP.', // 長い説明
    'params'      => '"' . __FILE__ . '"  run',                            // スクリプトへのパスとパラメータ
));
debug_zval_dump($x);
?>
]]>
     </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>依存性を用いた <function>win32_create_service</function> の例</title>
    <para>
     依存性がある 'dummyphp' というショートネームのサービスを作ります。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$x = win32_create_service(array(
    'service'      => 'dummyphp',                                           // サービスの名前
    'display'      => 'sample dummy PHP service',                           // 短い説明
    'description'  => 'This is a dummy Windows service created using PHP.', // 長い説明
    'params'       => '"' . __FILE__ . '"  run',                            // スクリプトへのパスとパラメータ
    'dependencies' => array("Netman"),                                      // 依存性のリスト
));
debug_zval_dump($x);
?>
]]>
     </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>リカバリ設定を用いた <function>win32_create_service</function> の例</title>
    <para>
     リカバリ設定がある 'dummyphp' というショートネームのサービスを作ります。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$x = win32_create_service(array(
    'service'               => 'dummyphp',                                           // サービスの名前
    'display'               => 'sample dummy PHP service',                           // 短い説明
    'description'           => 'This is a dummy Windows service created using PHP.', // 長い説明
    'params'                => '"' . __FILE__ . '"  run',                            // スクリプトへのパスとパラメータ
    'recovery_delay'        => 120000,                                               // 2分後に実行されるリカバリアクション
    'recovery_action_1'     => WIN32_SC_ACTION_RESTART,                              // 最初の失敗時にサービスを再起動する
    'recovery_action_2'     => WIN32_SC_ACTION_RUN_COMMAND,                          // 2回目の失敗時にはコマンドを実行
    'recovery_action_3'     => WIN32_SC_ACTION_NONE,                                 // その他の失敗時には何もしない
    'recovery_reset_period' => 86400,                                                // 1日後には失敗のカウンタをリセット
    'recovery_enabled'      => true,                                                 // リカバリパラメータを有効にする
    'recovery_reboot_msg'   => null,                                                 // 不要ならリブート時のメッセージは定義するな
    'recovery_command'      => "c:\clean-service.bat",                               // アクションが WIN32_SC_ACTION_RUN_COMMAND の場合、このコマンドが実行される
));
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">Win32 Base Priority Classes</link></member>
    <member><link linkend="win32service.constants.recovery-action">Win32 Recovery action</link></member>
    <member><link linkend="win32service.constants.errors">Win32 Error Codes</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
-->