説明

win32_start_service_ctrl_dispatcher(string $name, bool $gracefulMode = true): void

サービスコントロールマネージャ経由で起動させる際、サービスプロセスは「チェックイン」を要求され、これによってサービスのモニタリングや通信の機能を確立します。この関数は、サービスコントロールマネージャとの低レベル通信を処理するスレッドを生成し、チェックインを実行します。

サービスが開始したら、サービスプロセスで行わなければならないことは次のふたつです。まず最初は、サービスが実行中であることをサービスコントロールマネージャに通知することです。これは、win32_set_service_status() に定数 WIN32_SERVICE_RUNNING を指定してコールすれば実現できます。サービスが実際に動き出すまでに何らかの長い処理を要する場合は、定数 WIN32_SERVICE_START_PENDING を使うこともできます。もうひとつは、常にサービスコントロールマネージャにチェックインし続け、サービスをいつ終了させるべきかを確認することです。これは、定期的に win32_get_last_control_message() をコールして戻り値を適切に処理することで実現できます。

警告

0.2.0 以降では、この関数は "cli" SAPI でのみ動作します。他の SAPI では、この関数は無効になっています。

パラメータ

name: サービスの短い名前。win32_create_service() で登録されたもの。
gracefulMode: true の場合、graceful に終了します。 false の場合、エラーで終了します。詳細は win32_set_service_exit_mode() を参照ください。

戻り値

値を返しません。

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

エラー / 例外

バージョン 1.0.0 より前では、 SAPI が "cli" でない場合、この関数は E_ERROR レベルのエラーを発生させていました。

バージョン 1.0.0 以降では、 SAPI が "cli" でない場合、 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 gracefulMode パラメータが追加されました。

PECL win32service 0.2.0 この関数は "cli" SAPI でのみ動作するようになりました。

バージョン	説明
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	`gracefulMode` パラメータが追加されました。
PECL win32service 0.2.0	この関数は `"cli"` SAPI でのみ動作するようになりました。

例

例1 win32_start_service_ctrl_dispatcher() の例

サービスが SCM で実行されているかどうかを調べます。

<?php
if (!win32_start_service_ctrl_dispatcher('dummyphp')) {
  die("I'm probably not running under the service control manager");
}

win32_set_service_status(WIN32_SERVICE_START_PENDING);

// このサービスを処理するための、何らかの長い処理をします

win32_set_service_status(WIN32_SERVICE_RUNNING);

while (WIN32_SERVICE_CONTROL_STOP != win32_get_last_control_message()) {
  # ここでなんらかの処理をします。1 回のループに 30 秒以上かからない
  # ように心がけてください。
}
?>

参考

win32_set_service_status() - サービスの状態を更新する
win32_get_last_control_message() - サービスに送信された直近の制御メッセージを返す
win32_set_service_exit_mode() - Define or return the exit mode for the current running service
win32_set_service_exit_code() - Define or return the exit code for the current running service
Win32 エラーコード