HANDLER_FUNCTION

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

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

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

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

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

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

サービス コントロール マネージャーは、サービスに制御コードを送信すると、ハンドラー関数が戻るまで待機してから、他のサービスへ次の制御コードを送信します。制御ハンドラーはできる限り速やかに戻る必要があります。30 秒以内に戻らない場合、SCM はエラーを返します。制御ハンドラーの実行中に時間のかかる処理が必要な場合、サービスはその処理を行う二次スレッドを作成してから制御ハンドラーを抜けてください。これにより、サービスが制御ディスパッチャーを占有して他のサービスの制御コード受信を妨げることを防げます。

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

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

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

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

例

例については、 Writing a Control Handler Function を参照してください。