win32_create_service
(PECL win32service >=0.1.0)
win32_create_service — SCM データベースに新しいサービスのエントリを作成する
説明
win32_create_service
( array $details
[, string $machine
] ) : void
SCM データベースに新しいサービスの追加を試みます。 この操作を成功させるには、管理者権限が必要です。
パラメータ
detailsサービスの詳細情報を含む配列。
serviceサービスの短い名前。
netコマンドでサービスを 制御する際に、この名前を使用します。この名前は一意である（同名の サービスが 2 つ存在することがない）必要があり、スペースを含む 名前は可能な限り避けるべきです。displayサービスの表示名。これは、サービスアプレットに表示される名前です。
descriptionサービスの長い名前。これは「サービス」アプレットで表示される名前です。
userサービスを実行するユーザー名。指定しなかった場合、サービスは LocalSystem アカウントで実行されます。ユーザー名が指定された場合、 password も指定する必要があります。
passworduserに対応するパスワード。pathサービスの開始時に起動される実行モジュールのフルパス。 指定しなかった場合、現在の PHP プロセスへのパスが使用されます。
paramsサービスの開始時に渡されるコマンドラインパラメータ。 PHP スクリプトをサービスとして実行したい場合は、最初のパラメータは 実行するスクリプトへのフルパスとなります。 スクリプト名やパスにスペースを含む場合は、PHP スクリプトへのフルパスを
"で囲まなければなりません。load_orderload_order を制御します。現時点では完全にはサポートされていません。
svc_typeサービスの型を指定します。指定しなかった場合、デフォルト値は
WIN32_SERVICE_WIN32_OWN_PROCESSです。 よくわからない場合はこの値を変更しないでください。start_typeサービスをどのように開始させるかを指定します。デフォルトは
WIN32_SERVICE_AUTO_STARTで、これは マシンの起動時にサービスを開始させることを意味します。error_controlサービスに問題が発生した際にとるべき行動を SCM に指示します。 デフォルトは
WIN32_SERVER_ERROR_IGNOREです。 この値を変更することは、現時点では完全にはサポートされていません。delayed_startdelayed_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_33回目以降の失敗時に実行されるアクションです。 デフォルトの値は
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 がスローされます。
例
例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);?>
変更履歴
| バージョン | 説明 |
|---|---|
| PECL win32service 1.0.0 | 引数に不正な値があった場合、
ValueError をスローするようになりました。
これより前のバージョンでは、 |
| PECL win32service 1.0.0 | エラー時に
Win32ServiceException をスローするようになりました。 これより前のバージョンでは、 Win32 エラーコード を返していました。 |
| PECL win32service 1.0.0 | 返り値の型が void になりました。
これより前のバージョンでは、mixed でした。 |
| PECL win32service 0.4.0 | dependencies, recovery_delay,
|
参考
- win32_delete_service() - SCM データベースからサービスのエントリを削除する
- Win32 Base Priority Classes
- Win32 Recovery action
- Win32 Error Codes
