CAtlServiceModuleT クラス

  • [アーティクル]

このクラスは、サービスを実装します。

重要

このクラスとそのメンバーは、Windows ランタイムで実行するアプリケーションで使用することはできません。

構文

template <class T, UINT nServiceNameID>
class ATL_NO_VTABLE CAtlServiceModuleT : public CAtlExeModuleT<T>

パラメーター

T
CAtlServiceModuleT から派生したクラス。

nServiceNameID
サービスのリソース識別子。

メンバー

パブリック コンストラクター

名前 説明
CAtlServiceModuleT::CAtlServiceModuleT コンストラクター。

パブリック メソッド

名前 説明
CAtlServiceModuleT::Handler サービスのハンドラー ルーチン。
CAtlServiceModuleT::InitializeSecurity サービスの既定のセキュリティ設定を提供します。
CAtlServiceModuleT::Install サービスをインストールおよび作成します。
CAtlServiceModuleT::IsInstalled サービスがインストールされたことを確認します。
CAtlServiceModuleT::LogEvent イベント ログに書き込みます。
CAtlServiceModuleT::OnContinue サービスを続行するには、このメソッドをオーバーライドします。
CAtlServiceModuleT::OnInterrogate サービスを調査するには、このメソッドをオーバーライドします。
CAtlServiceModuleT::OnPause サービスを一時停止するには、このメソッドをオーバーライドします。
CAtlServiceModuleT::OnShutdown サービスをシャットダウンするには、このメソッドをオーバーライドします
CAtlServiceModuleT::OnStop サービスを停止するには、このメソッドをオーバーライドします
CAtlServiceModuleT::OnUnknownRequest サービスに対する不明の要求を処理するには、このメソッドをオーバーライドします
CAtlServiceModuleT::ParseCommandLine コマンド ラインを解析し、必要に応じて登録を実行します。
CAtlServiceModuleT::PreMessageLoop このメソッドは、メッセージ ループを入力する直前に呼び出されます。
CAtlServiceModuleT::RegisterAppId サービスをレジストリに登録します。
CAtlServiceModuleT::Run サービスを実行します。
CAtlServiceModuleT::ServiceMain サービス コントロール マネージャーによって呼び出されるメソッド。
CAtlServiceModuleT::SetServiceStatus サービスの状態を更新します。
CAtlServiceModuleT::Start サービスの開始時に CAtlServiceModuleT::WinMain によって呼び出されます。
CAtlServiceModuleT::Uninstall サービスを停止して削除します。
CAtlServiceModuleT::Unlock サービスのロック カウントを減分します。
CAtlServiceModuleT::UnregisterAppId レジストリからサービスを削除します。
CAtlServiceModuleT::WinMain このメソッドは、サービスの実行に必要なコードを実装します。

パブリック データ メンバー

名前 説明
CAtlServiceModuleT::m_bService プログラムがサービスとして実行されていることを示すフラグ。
CAtlServiceModuleT::m_dwThreadID スレッド識別子を格納するメンバー変数。
CAtlServiceModuleT::m_hServiceStatus 現在のサービスの状態情報構造体へのハンドルを格納するメンバー変数。
CAtlServiceModuleT::m_status 現在のサービスの状態情報構造体を格納するメンバー変数。
CAtlServiceModuleT::m_szServiceName 登録するサービスの名前。

解説

CAtlExeModuleT から派生する CAtlServiceModuleT は、ATL サービス モジュールを実装します。 CAtlServiceModuleT では、コマンドラインの処理、インストール、登録、削除のためのメソッドが提供されます。 追加の機能が必要な場合、これらと他のメソッドをオーバーライドできます。

このクラスは、ATL の以前のバージョンで使用されていた古い CComModule Class に代わるものです。 詳細については、「ATL モジュール クラス」を参照してください。

継承階層

_ATL_MODULE

CAtlModule

CAtlModuleT

CAtlExeModuleT

CAtlServiceModuleT

必要条件

ヘッダー: atlbase.h

CAtlServiceModuleT::CAtlServiceModuleT

コンストラクター。

CAtlServiceModuleT() throw();

解説

データ メンバーを初期化し、初期サービスの状態を設定します。

CAtlServiceModuleT::Handler

サービスのハンドラー ルーチン。

void Handler(DWORD dwOpcode) throw();

パラメーター

dwOpcode
ハンドラー操作を定義するスイッチ。 詳細については、「解説」を参照してください。

解説

これは、サービス コントロール マネージャー (SCM) がサービスの状態を取得して、停止や一時停止などの命令を発行するために呼び出すコードです。 SCM は、次に示す操作コードを Handler に渡して、サービスで実行する必要がある操作を指示します。

操作コード 意味
SERVICE_CONTROL_STOP サービスを停止します。 動作を変更するには、atlbase.h 内のメソッド CAtlServiceModuleT::OnStop をオーバーライドします。
SERVICE_CONTROL_PAUSE ユーザーによる実装。 サービスを一時停止するには、atlbase.h 内の空のメソッド CAtlServiceModuleT::OnPause をオーバーライドします。
SERVICE_CONTROL_CONTINUE ユーザーによる実装。 サービスを続行するには、atlbase.h 内の空のメソッド CAtlServiceModuleT::OnContinue をオーバーライドします。
SERVICE_CONTROL_INTERROGATE ユーザーによる実装。 サービスを調査するには、atlbase.h 内の空のメソッド CAtlServiceModuleT::OnInterrogate をオーバーライドします。
SERVICE_CONTROL_SHUTDOWN ユーザーによる実装。 サービスをシャットダウンするには、atlbase.h 内の空のメソッド CAtlServiceModuleT::OnShutdown をオーバーライドします。

操作コードが認識されない場合、メソッド CAtlServiceModuleT::OnUnknownRequest が呼び出されます。

既定の ATL によって生成されるサービスでは、停止命令のみが処理されます。 SCM が停止命令を渡した場合、サービスは、プログラムがまもなく停止することを SCM に通知します。 その後、サービスは PostThreadMessage を呼び出して、終了メッセージを自身にポストします。 これにより、メッセージ ループは終了し、サービスは最終的に閉じられます。

CAtlServiceModuleT::InitializeSecurity

サービスの既定のセキュリティ設定を提供します。

HRESULT InitializeSecurity() throw();

戻り値

成功した場合は S_OK、失敗した場合はエラー HRESULT を返します。

解説

CAtlServiceModuleT から派生するクラスは、派生クラスでこのメソッドを実装する必要があります。

CoInitializeSecurity の呼び出しで、PKT レベルの認証、RPC_C_IMP_LEVEL_IDENTIFY の偽装レベル、null 以外の適切なセキュリティ記述子を使用します。

ウィザードで生成され、属性のないサービス プロジェクトの場合、次のようになります

class CNonAttribServiceModule : public CAtlServiceModuleT< CNonAttribServiceModule, IDS_SERVICENAME >
{
public :
   DECLARE_LIBID(LIBID_NonAttribServiceLib)
   DECLARE_REGISTRY_APPID_RESOURCEID(IDR_NONATTRIBSERVICE, "{29160736-339F-4A1C-ABEF-C320CE103E12}")
   HRESULT InitializeSecurity() throw()
   {
      // TODO : Call CoInitializeSecurity and provide the appropriate security settings for 
      // your service
      // Suggested - PKT Level Authentication, 
      // Impersonation Level of RPC_C_IMP_LEVEL_IDENTIFY 
      // and an appropriate Non NULL Security Descriptor.

      return S_OK;
   }
};

属性が設定されているサービス プロジェクトの場合、次のようになります

[ module(SERVICE, uuid = "{D3103322-7B70-4581-8E59-12769BD9A62B}", 
   name = "AttribService", 
   helpstring = "AttribService 1.0 Type Library", 
   resource_name="IDS_SERVICENAME") ]
class CAttribServiceModule
{
public:
   HRESULT InitializeSecurity() throw()
   {
      // TODO : Call CoInitializeSecurity and provide the appropriate security settings for 
      // your service
      // Suggested - PKT Level Authentication, 
      // Impersonation Level of RPC_C_IMP_LEVEL_IDENTIFY 
      // and an appropriate Non NULL Security Descriptor.

      return S_OK;
   }
};

CAtlServiceModuleT::Install

サービスをインストールおよび作成します。

BOOL Install() throw();

戻り値

成功した場合は TRUE を返し、失敗した場合は FALSE を返します。

解説

サービスをサービス コントロール マネージャー (SCM) データベースにインストールし、サービス オブジェクトを作成します。 サービスを作成できなかった場合、メッセージ ボックスが表示され、メソッドから FALSE が返されます。

CAtlServiceModuleT::IsInstalled

サービスがインストールされたことを確認します。

BOOL IsInstalled() throw();

戻り値

サービスがインストールされている場合は TRUE、それ以外の場合は FALSE が返されます。

CAtlServiceModuleT::LogEvent

イベント ログに書き込みます。

void __cdecl LogEvent(LPCTSTR pszFormat, ...) throw();

パラメーター

pszFormat
イベント ログに書き込む文字列。

...
イベント ログに書き込まれる追加文字列 (省略可能)。

解説

このメソッドは、関数 ReportEvent を使用して、イベント ログに詳細を書き込みます。 サービスが実行されている場合、文字列はコンソールに送信されます。

CAtlServiceModuleT::m_bService

プログラムがサービスとして実行されていることを示すフラグ。

BOOL m_bService;

解説

サービス EXE とアプリケーション EXE を区別するために使用されます。

CAtlServiceModuleT::m_dwThreadID

サービスのスレッド識別子を格納するメンバー変数。

DWORD m_dwThreadID;

解説

この変数には、現在のスレッドのスレッド識別子が格納されます。

CAtlServiceModuleT::m_hServiceStatus

現在のサービスの状態情報構造体へのハンドルを格納するメンバー変数。

SERVICE_STATUS_HANDLE m_hServiceStatus;

解説

SERVICE_STATUS 構造体には、サービスに関する情報が含まれます。

CAtlServiceModuleT::m_status

現在のサービスの状態情報構造体を格納するメンバー変数。

SERVICE_STATUS m_status;

解説

SERVICE_STATUS 構造体には、サービスに関する情報が含まれます。

CAtlServiceModuleT::m_szServiceName

登録するサービスの名前。

TCHAR [256] m_szServiceName;

解説

サービスの名前を格納する文字列。null で終了します。

CAtlServiceModuleT::OnContinue

サービスを続行するには、このメソッドをオーバーライドします。

void OnContinue() throw();

CAtlServiceModuleT::OnInterrogate

サービスを調査するには、このメソッドをオーバーライドします。

void OnInterrogate() throw();

CAtlServiceModuleT::OnPause

サービスを一時停止するには、このメソッドをオーバーライドします。

void OnPause() throw();

CAtlServiceModuleT::OnShutdown

サービスをシャットダウンするには、このメソッドをオーバーライドします。

void OnShutdown() throw();

CAtlServiceModuleT::OnStop

サービスを停止するには、このメソッドをオーバーライドします。

void OnStop() throw();

CAtlServiceModuleT::OnUnknownRequest

サービスに対する不明の要求を処理するには、このメソッドをオーバーライドします。

void OnUnknownRequest(DWORD /* dwOpcode*/) throw();

パラメーター

dwOpcode
予約済み。

CAtlServiceModuleT::ParseCommandLine

コマンド ラインを解析し、必要に応じて登録を実行します。

bool ParseCommandLine(LPCTSTR lpCmdLine, HRESULT* pnRetCode) throw();

パラメーター

lpCmdLine
コマンド ライン。

pnRetCode
登録に対応する HRESULT (登録が行われた場合)。

戻り値

成功した場合は TRUE を返し、コマンド ラインで指定された RGS ファイルを登録できなかった場合は FALSE を返します。

解説

コマンド ラインを解析し、必要に応じて、指定された RGS ファイルの登録または登録解除を行います。 このメソッドは、CAtlExeModuleT::ParseCommandLine を呼び出して、/RegServer および /UnregServer を確認します。 引数 -/Service を追加すると、サービスが登録されます。

CAtlServiceModuleT::PreMessageLoop

このメソッドは、メッセージ ループを入力する直前に呼び出されます。

HRESULT PreMessageLoop(int nShowCmd) throw();

パラメーター

nShowCmd
このパラメーターは CAtlExeModuleT::PreMessageLoop に渡されます。

戻り値

成功した場合は S_OK、失敗した場合はエラー HRESULT を返します。

解説

サービスのカスタム初期化コードを追加するには、このメソッドをオーバーライドします。

CAtlServiceModuleT::RegisterAppId

サービスをレジストリに登録します。

inline HRESULT RegisterAppId(bool bService = false) throw();

パラメーター

bService
サービスとして登録するには、TRUE である必要があります。

戻り値

成功した場合は S_OK、失敗した場合はエラー HRESULT を返します。

CAtlServiceModuleT::Run

サービスを実行します。

HRESULT Run(int nShowCmd = SW_HIDE) throw();

パラメーター

nShowCmd
ウィンドウの表示方法を指定します。 このパラメーター、WinMain に関するセクションで説明されている値の 1 つになります。 既定値は SW_HIDE です。

戻り値

成功した場合は S_OK、失敗した場合はエラー HRESULT を返します。

解説

呼び出された後、Run は、CAtlServiceModuleT::PreMessageLoop、CAtlExeModuleT::RunMessageLoop、CAtlExeModuleT::PostMessageLoop を呼び出します。

CAtlServiceModuleT::ServiceMain

このメソッドは、サービス コントロール マネージャーによって呼び出されます。

void ServiceMain(DWORD dwArgc, LPTSTR* lpszArgv) throw();

パラメーター

dwArgc
argc 引数。

lpszArgv
argv 引数。

解説

コントロール パネルでサービス アプリケーションを開いてサービスを選択し、[開始] を選択すると、サービス コントロール マネージャー (SCM) は ServiceMain を呼び出します。

SCM が ServiceMain を呼び出した後、サービスでは、SCM にハンドラー関数を提供する必要があります。 この関数を使用すると、SCM は、サービスの状態を取得し、特定の命令 (一時停止や停止など) を渡すことができます。 その後、CAtlServiceModuleT::Run が呼び出され、サービスのメイン作業が実行されます。 Run は、サービスが停止されるまで、実行を継続します。

CAtlServiceModuleT::SetServiceStatus

このメソッドは、サービスの状態を更新します。

void SetServiceStatus(DWORD dwState) throw();

パラメーター

dwState
新しい状態。 使用可能な値については、SetServiceStatus に関するページを参照してください。

解説

サービスのサービス コントロール マネージャーの状態情報を更新します。 これは、CAtlServiceModuleT::Run、CAtlServiceModuleT::ServiceMain、その他のハンドラー メソッドによって呼び出されます。 状態は、メンバー変数 CAtlServiceModuleT::m_statusにも格納されます。

CAtlServiceModuleT::Start

サービスの開始時に CAtlServiceModuleT::WinMain によって呼び出されます。

HRESULT Start(int nShowCmd) throw();

パラメーター

nShowCmd
ウィンドウの表示方法を指定します。 このパラメーター、WinMain に関するセクションで説明されている値の 1 つになります。

戻り値

成功した場合は S_OK、失敗した場合はエラー HRESULT を返します。

解説

CAtlServiceModuleT::WinMain メソッドは、登録とインストールの両方を処理するだけでなく、レジストリ エントリの削除およびモジュールのアンインストールに関係するタスクも処理します。 サービスが実行されている場合、WinMain は Start を呼び出します。

CAtlServiceModuleT::Uninstall

サービスを停止して削除します。

BOOL Uninstall() throw();

戻り値

成功した場合は TRUE を返し、失敗した場合は FALSE を返します。

解説

サービスの実行を停止し、サービス コントロール マネージャー データベースから削除します。

CAtlServiceModuleT::Unlock

サービスのロック カウントを減分します。

LONG Unlock() throw();

戻り値

診断およびデバッグに役立つ可能性のあるロック カウントを返します。

CAtlServiceModuleT::UnregisterAppId

レジストリからサービスを削除します。

HRESULT UnregisterAppId() throw();

戻り値

成功した場合は S_OK、失敗した場合はエラー HRESULT を返します。

CAtlServiceModuleT::WinMain

このメソッドは、サービスの開始に必要なコードを実装します。

int WinMain(int nShowCmd) throw();

パラメーター

nShowCmd
ウィンドウの表示方法を指定します。 このパラメーター、WinMain に関するセクションで説明されている値の 1 つになります。

戻り値

サービスの戻り値を返します。

解説

このメソッドは、(CAtlServiceModuleT::ParseCommandLineを使用して) コマンド ラインを処理し、(CAtlServiceModuleT::Start を使用して) サービスを開始します。

関連項目

CAtlExeModuleT クラス
クラスの概要