array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'ja', ), 'this' => array ( 0 => 'function.win32-create-service.php', 1 => 'win32_create_service', 2 => 'SCM データベースに新しいサービスのエントリを作成する', ), 'up' => array ( 0 => 'ref.win32service.php', 1 => 'win32service 関数', ), 'prev' => array ( 0 => 'function.win32-continue-service.php', 1 => 'win32_continue_service', ), 'next' => array ( 0 => 'function.win32-delete-service.php', 1 => 'win32_delete_service', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'ja', 'path' => 'reference/win32service/functions/win32-create-service.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

win32_create_service

(PECL win32service >=0.1.0)

win32_create_service — SCM データベースに新しいサービスのエントリを作成する

説明

win32_create_service(array $details, string $machine = null): void

SCM データベースに新しいサービスの追加を試みます。 この操作を成功させるには、管理者権限が必要です。

パラメータ

details

サービスの詳細情報を含む配列。

service

サービスの短い名前。net コマンドでサービスを 制御する際に、この名前を使用します。この名前は一意である（同名の サービスが 2 つ存在することがない）必要があり、スペースを含む 名前は可能な限り避けるべきです。

display

サービスの表示名。これは、サービスアプレットに表示される名前です。

description

サービスの長い名前。これは「サービス」アプレットで表示される名前です。

user

サービスを実行するユーザー名。指定しなかった場合、サービスは LocalSystem アカウントで実行されます。ユーザー名が指定された場合、 password も指定する必要があります。

password

user に対応するパスワード。

path

サービスの開始時に起動される実行モジュールのフルパス。 指定しなかった場合、現在の PHP プロセスへのパスが使用されます。

params

サービスの開始時に渡されるコマンドラインパラメータ。 PHP スクリプトをサービスとして実行したい場合は、最初のパラメータは 実行するスクリプトへのフルパスとなります。 スクリプト名やパスにスペースを含む場合は、PHP スクリプトへのフルパスを " で囲まなければなりません。

load_order

load_order を制御します。現時点では完全にはサポートされていません。

svc_type

サービスの型を指定します。指定しなかった場合、デフォルト値は WIN32_SERVICE_WIN32_OWN_PROCESS です。 よくわからない場合はこの値を変更しないでください。

start_type

サービスをどのように開始させるかを指定します。デフォルトは WIN32_SERVICE_AUTO_START で、これは マシンの起動時にサービスを開始させることを意味します。

error_control

サービスに問題が発生した際にとるべき行動を SCM に指示します。 デフォルトは WIN32_SERVER_ERROR_IGNORE です。 この値を変更することは、現時点では完全にはサポートされていません。

delayed_start

delayed_start を true にすると、 他の自動起動サービスが開始したあとで少し間をおいてサービスが起動するようになります。

任意のサービスに対してこれを指定することができますが、そのサービスの start_type が WIN32_SERVICE_AUTO_START でない場合は何の効果も及ぼしません。

この設定が使えるのは、Windows Vista および Windows Server 2008 以降のみです。

base_priority

プロセッサの使用状況への影響を考慮すると、 ベース優先度は通常より低めに設定しておかなければなりません。

base_priority には、 Win32 ベース優先度クラス で定義された定数のいずれかを設定します。

dependencies

サービスへの依存性を定義します。 サービス名の一覧を配列として設定する必要があるかもしれません。

recovery_delay

失敗時とリカバリアクションの実行の間に取る時間を定義します。 この値はマイクロ秒単位です。

デフォルトは 60000 です。

recovery_action_1

最初の失敗時に実行されるアクションです。 デフォルトの値は WIN32_SC_ACTION_NONE です。

recovery_action_1 は、 Win32 Recovery action で定義された定数のうちのひとつを設定できます。

recovery_action_2

二回目の失敗時に実行されるアクションです。 デフォルトの値は WIN32_SC_ACTION_NONE です。

recovery_action_2 は、 Win32 Recovery action で定義された定数のうちのひとつを設定できます。

recovery_action_3

3回目以降の失敗時に実行されるアクションです。 デフォルトの値は WIN32_SC_ACTION_NONE です。

recovery_action_3 は、 Win32 Recovery action で定義された定数のうちのひとつを設定できます。

recovery_reset_period

ここで定義された時間が経過すると、失敗のカウンタがリセットされます。 秒単位で設定します。

デフォルト値は 86400 です。

recovery_enabled

リカバリ設定を有効にする場合は true を設定します。 無効にする場合は false を設定します。

デフォルトは false です。

recovery_reboot_msg

リブート時に Windows のイベントログに記録されるメッセージを設定します。 アクションを WIN32_SC_ACTION_REBOOT に設定する場合にだけ使ってください。

recovery_command

アクションが WIN32_SC_ACTION_RUN_COMMAND に設定された場合に、実行されるコマンドを設定します。

machine

オプションで、サービスを作成したいマシン名を指定します。 指定しなかった場合は、ローカルマシンを使用します。

戻り値

値を返しません。

バージョン 1.0.0 より前では、成功した場合に WIN32_NO_ERROR を返していました。パラメータに問題がある場合は false、失敗した場合は Win32 エラーコード を返します。

エラー / 例外

service 引数が空の場合、 ValueError がスローされます。

path 引数が渡されていないか、空の場合、 ValueError がスローされます。

svc_type 引数が不正な場合は、 ValueError がスローされます。

start_type 引数が不正な場合は、 ValueError がスローされます。

error_control 引数が不正な場合は、 ValueError がスローされます。

base_priority 引数が不正な場合は、 ValueError がスローされます。

recovery_delay 引数が 0 と PHP_INT_MAX の間にない場合は、 ValueError がスローされます。

recovery_action_1 引数が不正な場合は、 ValueError がスローされます。

recovery_action_2 引数が不正な場合は、 ValueError がスローされます。

recovery_action_3 引数が不正な場合は、 ValueError がスローされます。

recovery_reset_period 引数が 0 と PHP_INT_MAX の間にない場合は、 ValueError がスローされます。

エラーが発生した場合は、Win32ServiceException がスローされます。

変更履歴

バージョン 説明
PECL win32service 1.0.0 引数に不正な値があった場合、 ValueError をスローするようになりました。 これより前のバージョンでは、false を返していました。
PECL win32service 1.0.0 エラー時に Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。
PECL win32service 1.0.0 戻り値の型が void になりました。 これより前のバージョンでは、mixed でした。
PECL win32service 0.4.0 dependencies, recovery_delay, recovery_action_1, recovery_action_2, recovery_action_3, recovery_reset_period, recovery_enabled, recovery_reboot_msg および recovery_command パラメータが追加されました。

例

例1 win32_create_service() の例

'dummyphp' というショートネームのサービスを作ります。

<?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);
?>

例2 依存性を用いた win32_create_service() の例

依存性がある 'dummyphp' というショートネームのサービスを作ります。

<?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);
?>

例3 リカバリ設定を用いた win32_create_service() の例

リカバリ設定がある 'dummyphp' というショートネームのサービスを作ります。

<?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);
?>

参考