ServiceMain 関数の記述

  • [アーティクル]

次の例の SvcMain 関数は、サンプル サービスの ServiceMain 関数です。 SvcMain は、コンソール アプリケーションのメイン関数と同様に、サービスのコマンド ライン引数にアクセスできます。 最初のパラメーターには、2 番目のパラメーターでサービスに渡される引数の数が含まれています。 引数は常に少なくとも 1 つ存在します。 2 番目のパラメーターは、文字列ポインターの配列へのポインターです。 配列の最初の項目は常にサービス名です。

SvcMain 関数は、まず RegisterServiceCtrlHandler 関数を呼び出して、SvcCtrlHandler 関数をサービスの Handler 関数として登録し、初期化を開始します。 RegisterServiceCtrlHandler は ServiceMain の最初の非failing関数である必要があります。そのため、サービスは、この関数によって返される状態ハンドルを使用して、エラーが発生した場合にSERVICE_STOPPED状態で SetServiceStatus を呼び出すことができます。

次に、SvcMain 関数は ReportSvcStatus 関数を呼び出して、その初期状態がSERVICE_START_PENDINGであることを示します。 サービスがこの状態にある間は、コントロールは受け入れされません。 サービスのロジックを簡略化するために、初期化の実行中は、サービスがコントロールを受け入れないことをお勧めします。

最後に、SvcMain 関数は SvcInit 関数を呼び出してサービス固有の初期化を実行し、サービスによって実行される作業を開始します。

サンプル初期化関数 SvcInit は非常に単純な例です。追加のスレッドの作成など、より複雑な初期化タスクは実行されません。 サービス制御ハンドラーが通知してサービスを停止する必要があることを示すイベントを作成し、ReportSvcStatus を呼び出して、サービスがSERVICE_RUNNING状態に入っていることを示します。 この時点で、サービスは初期化を完了し、コントロールを受け入れる準備ができました。 最適なシステム パフォーマンスを得るには、アプリケーションが 25 から 100 ミリ秒以内に実行状態に入る必要があります。

このサンプル サービスは実際のタスクを完了しないため、SvcInit は WaitForSingleObject 関数を呼び出してサービス停止イベントが通知されるのを待ち、ReportSvcStatus を呼び出してサービスがSERVICE_STOPPED状態に入っていることを示し、 を返します。 (を返すと引数に割り当てられたメモリをクリーンアップできるため、ExitThread 関数を呼び出すのではなく、関数がを返す必要があることに注意してください)。WaitForSingleObject の代わりに RegisterWaitForSingleObject 関数を使用して、追加のクリーンアップ タスクを実行できます。 ServiceMain 関数を実行しているスレッドは終了しますが、サービス自体は引き続き実行されます。 サービス コントロール ハンドラーがイベントを通知すると、スレッド プールのスレッドがコールバックを実行して、状態を SERVICE_STOPPED に設定するなど、追加のクリーンアップを実行します。

この例では、SvcReportEvent を使用してエラー イベントをイベント ログに書き込みます。 SvcReportEvent のソース コードについては、「 Svc.cpp」を参照してください。 コントロール ハンドラー関数の例については、「コントロール ハンドラー関数の記述」を参照してください。

このサンプルでは、次のグローバル定義を使用します。

#define SVCNAME TEXT("SvcName")

SERVICE_STATUS          gSvcStatus; 
SERVICE_STATUS_HANDLE   gSvcStatusHandle; 
HANDLE                  ghSvcStopEvent = NULL;

完全なサービス サンプルから次のサンプル フラグメントを取得します。

//
// Purpose: 
//   Entry point for the service
//
// Parameters:
//   dwArgc - Number of arguments in the lpszArgv array
//   lpszArgv - Array of strings. The first string is the name of
//     the service and subsequent strings are passed by the process
//     that called the StartService function to start the service.
// 
// Return value:
//   None.
//
VOID WINAPI SvcMain( DWORD dwArgc, LPTSTR *lpszArgv )
{
    // Register the handler function for the service

    gSvcStatusHandle = RegisterServiceCtrlHandler( 
        SVCNAME, 
        SvcCtrlHandler);

    if( !gSvcStatusHandle )
    { 
        SvcReportEvent(TEXT("RegisterServiceCtrlHandler")); 
        return; 
    } 

    // These SERVICE_STATUS members remain as set here

    gSvcStatus.dwServiceType = SERVICE_WIN32_OWN_PROCESS; 
    gSvcStatus.dwServiceSpecificExitCode = 0;    

    // Report initial status to the SCM

    ReportSvcStatus( SERVICE_START_PENDING, NO_ERROR, 3000 );

    // Perform service-specific initialization and work.

    SvcInit( dwArgc, lpszArgv );
}

//
// Purpose: 
//   The service code
//
// Parameters:
//   dwArgc - Number of arguments in the lpszArgv array
//   lpszArgv - Array of strings. The first string is the name of
//     the service and subsequent strings are passed by the process
//     that called the StartService function to start the service.
// 
// Return value:
//   None
//
VOID SvcInit( DWORD dwArgc, LPTSTR *lpszArgv)
{
    // TO_DO: Declare and set any required variables.
    //   Be sure to periodically call ReportSvcStatus() with 
    //   SERVICE_START_PENDING. If initialization fails, call
    //   ReportSvcStatus with SERVICE_STOPPED.

    // Create an event. The control handler function, SvcCtrlHandler,
    // signals this event when it receives the stop control code.

    ghSvcStopEvent = CreateEvent(
                         NULL,    // default security attributes
                         TRUE,    // manual reset event
                         FALSE,   // not signaled
                         NULL);   // no name

    if ( ghSvcStopEvent == NULL)
    {
        ReportSvcStatus( SERVICE_STOPPED, NO_ERROR, 0 );
        return;
    }

    // Report running status when initialization is complete.

    ReportSvcStatus( SERVICE_RUNNING, NO_ERROR, 0 );

    // TO_DO: Perform work until service stops.

    while(1)
    {
        // Check whether to stop the service.

        WaitForSingleObject(ghSvcStopEvent, INFINITE);

        ReportSvcStatus( SERVICE_STOPPED, NO_ERROR, 0 );
        return;
    }
}

//
// Purpose: 
//   Sets the current service status and reports it to the SCM.
//
// Parameters:
//   dwCurrentState - The current state (see SERVICE_STATUS)
//   dwWin32ExitCode - The system error code
//   dwWaitHint - Estimated time for pending operation, 
//     in milliseconds
// 
// Return value:
//   None
//
VOID ReportSvcStatus( DWORD dwCurrentState,
                      DWORD dwWin32ExitCode,
                      DWORD dwWaitHint)
{
    static DWORD dwCheckPoint = 1;

    // Fill in the SERVICE_STATUS structure.

    gSvcStatus.dwCurrentState = dwCurrentState;
    gSvcStatus.dwWin32ExitCode = dwWin32ExitCode;
    gSvcStatus.dwWaitHint = dwWaitHint;

    if (dwCurrentState == SERVICE_START_PENDING)
        gSvcStatus.dwControlsAccepted = 0;
    else gSvcStatus.dwControlsAccepted = SERVICE_ACCEPT_STOP;

    if ( (dwCurrentState == SERVICE_RUNNING) ||
           (dwCurrentState == SERVICE_STOPPED) )
        gSvcStatus.dwCheckPoint = 0;
    else gSvcStatus.dwCheckPoint = dwCheckPoint++;

    // Report the status of the service to the SCM.
    SetServiceStatus( gSvcStatusHandle, &gSvcStatus );
}

Service ServiceMain 関数

完全なサービス サンプル