LPHANDLER_FUNCTION

アプリケーション定義のコールバック関数で、 RegisterServiceCtrlHandler 関数と共に使用します。サービスプログラムは、これを特定のサービスのコントロールハンドラー関数として使用できます。

LPHANDLER_FUNCTION 型は、この関数へのポインターを定義します。 Handler は、アプリケーション定義の名前を表すプレースホルダーです。

この関数は、 RegisterServiceCtrlHandlerEx 関数と共に使用される HandlerEx コントロールハンドラー関数に置き換えられました。サービスはどちらのコントロールハンドラーも使用できますが、新しいコントロールハンドラーはユーザー定義のコンテキストデータと追加の拡張コントロールコードをサポートします。

サービスが開始されると、その ServiceMain 関数は直ちに RegisterServiceCtrlHandler 関数を呼び出して、コントロール要求を処理する Handler 関数を指定する必要があります。

サービスプロセスのメインスレッドにあるコントロールディスパッチャーは、サービスコントロールマネージャーからコントロール要求を受け取るたびに、指定されたサービスのコントロールハンドラー関数を呼び出します。コントロール要求の処理後、サービスの状態が変化した場合は、コントロールハンドラーが SetServiceStatus 関数を呼び出して、新しい状態をサービスコントロールマネージャーに報告する必要があります。

コントロールハンドラー関数は、通知を受け取ったら直ちに復帰することを想定しています。コールバック関数はパラメーターを保存し、追加の処理を行うための別のスレッドを作成してください。(アプリケーションは、サービスを停止する前にそれらのスレッドが終了していることを保証する必要があります。) 特に、コントロールハンドラーではロックの取得などブロックする可能性のある操作を避けてください。デッドロックやシステムの応答停止を招くおそれがあるためです。

サービスコントロールマネージャーは、サービスにコントロールコードを送信すると、ハンドラー関数が復帰するまで待ってから、他のサービスに追加のコントロールコードを送信します。コントロールハンドラーは、できるだけ早く復帰する必要があります。30 秒以内に復帰しない場合、SCM はエラーを返します。コントロールハンドラーの実行中に長時間の処理が必要な場合、サービスは別のスレッドを作成してその処理を実行し、コントロールハンドラーからは復帰してください。これにより、サービスがコントロールディスパッチャーを占有し、他のサービスがコントロールコードを受信できなくなることを防げます。

SERVICE_CONTROL_SHUTDOWN コントロールコードは、シャットダウン時にどうしてもクリーンアップが必要なサービスだけが処理すべきです。サービスのシャットダウンに使用できる時間は限られている (約 20 秒) ためです。この時間が経過すると、サービスのシャットダウンが完了しているかどうかに関係なく、システムのシャットダウンが進行します。なお、システムがシャットダウン状態のまま (再起動も電源切断もされずに) 残された場合、サービスは実行を継続します。サービスが SERVICE_CONTROL_SHUTDOWN を受け付けるように登録している場合は、このコントロールコードを処理して速やかに停止する必要があります。そうしないと、システムはサービスのシャットダウンに許された時間が経過するまで待たなければシステムのシャットダウンを進行できないため、サービスがシステムのシャットダウンに要する時間を長くしてしまう可能性があります。

クリーンアップにさらに時間が必要な場合、サービスは待機ヒントを添えて STOP_PENDING 状態メッセージを送信し、サービスのシャットダウンが完了したとシステムに報告するまでどれだけ待てばよいかをサービスコントローラーに知らせる必要があります。ただし、サービスがシャットダウンを妨げないように、サービスコントローラーが待機する時間には上限があります。サービス スナップインからサービスをシャットダウンする場合、上限は 125 秒です。オペレーティングシステムが再起動する場合、制限時間は次のレジストリキーの WaitToKillServiceTimeout 値で指定されます。

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

サービスは、SetConsoleCtrlHandler 関数を使用してシャットダウン通知を受け取ることもできます。この通知は、実行中のアプリケーションがシャットダウンするときに受け取ります。これは、サービスがシャットダウンされる前に発生します。

例

例については、 コントロールハンドラー関数の記述を参照してください。