LPHANDLER_FUNCTION コールバック関数 (winsvc.h)

  • [アーティクル]

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

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

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

構文

LPHANDLER_FUNCTION LphandlerFunction;

void LphandlerFunction(
  DWORD dwControl
)
{...}

パラメーター

dwControl

戻り値

なし

解説

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

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

コントロール ハンドラー関数は、通知を受信してすぐに返すことを目的としています。 コールバック関数は、そのパラメーターを保存し、追加の作業を実行するために他のスレッドを作成する必要があります。 (アプリケーションでは、サービスを停止する前に、このようなスレッドが終了していることを確認する必要があります)。特に、コントロール ハンドラーでは、デッドロックが発生したり、システムが応答を停止したりする可能性があるため、ロックの取得など、ブロックする可能性のある操作を回避する必要があります。

サービス コントロール マネージャーは、コントロール コードをサービスに送信すると、ハンドラー関数が返されるのを待ってから、他のサービスに追加のコントロール コードを送信します。 コントロール ハンドラーは、可能な限り迅速にを返す必要があります。30 秒以内にが返されない場合、SCM はエラーを返します。 サービスがコントロール ハンドラーの実行時に長い処理を行う必要がある場合は、長い処理を実行するセカンダリ スレッドを作成してから、コントロール ハンドラーから戻る必要があります。 これにより、サービスがコントロール ディスパッチャーを接続し、他のサービスが制御コードを受信するのをブロックできなくなります。

SERVICE_CONTROL_SHUTDOWN制御コードは、サービスのシャットダウンに使用できる時間 (約 20 秒) が限られているため、シャットダウン中に絶対にクリーンする必要があるサービスによってのみ処理する必要があります。 この時間が経過すると、サービスのシャットダウンが完了したかどうかに関係なく、システムのシャットダウンが続行されます。 システムがシャットダウン状態のまま (再起動または電源オフではない) 場合、サービスは引き続き実行されることに注意してください。 サービスが SERVICE_CONTROL_SHUTDOWNを受け入れるように登録する場合は、コントロール コードを処理し、タイムリーに停止する必要があります。 そうしないと、システムのシャットダウンを続行する前に、システムがサービスのシャットダウンに許可されている完全な時間を待機する必要があるため、システムのシャットダウンに必要な時間が増える可能性があります。

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

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

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

例

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

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー winsvc.h (Windows.h を含む)

こちらもご覧ください

HandlerEx

RegisterServiceCtrlHandler

サービス コントロール ハンドラー関数

サービス関数

ServiceMain

SetServiceStatus