通过

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 类。 有关详细信息，请参阅 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 部分中所述的值之一。 默认值为 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 部分中所述的值之一。

返回值

如果成功，则返回 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 部分中所述的值之一。

返回值

返回服务的返回值。

注解

此方法处理命令行（使用 CAtlServiceModuleT::ParseCommandLine），然后启动服务（使用 CAtlServiceModuleT::Start）。

另请参阅

CAtlExeModuleT 类
类概述