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 模块类。
继承层次结构
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）。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈