CAtlServiceModuleT Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CAtlServiceModuleT Class.
This class implements a service.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
template <class T, UINT nServiceNameID>
class ATL_NO_VTABLE CAtlServiceModuleT : public CAtlExeModuleT<T>
Parameters
T
Your class derived from CAtlServiceModuleT.
nServiceNameID
The resource identifier of the service.
Members
Public Constructors
| Name | Description |
|---|---|
| CAtlServiceModuleT::CAtlServiceModuleT | The constructor. |
Public Methods
| Name | Description |
|---|---|
| CAtlServiceModuleT::Handler | The handler routine for the service. |
| CAtlServiceModuleT::InitializeSecurity | Provides the default security settings for the service. |
| CAtlServiceModuleT::Install | Installs and creates the service. |
| CAtlServiceModuleT::IsInstalled | Confirms that the service has been installed. |
| CAtlServiceModuleT::LogEvent | Writes to the event log. |
| CAtlServiceModuleT::OnContinue | Override this method to continue the service. |
| CAtlServiceModuleT::OnInterrogate | Override this method to interrogate the service. |
| CAtlServiceModuleT::OnPause | Override this method to pause the service. |
| CAtlServiceModuleT::OnShutdown | Override this method to shut down the service |
| CAtlServiceModuleT::OnStop | Override this method to stop the service |
| CAtlServiceModuleT::OnUnknownRequest | Override this method to handle unknown requests to the service |
| CAtlServiceModuleT::ParseCommandLine | Parses the command line and performs registration if necessary. |
| CAtlServiceModuleT::PreMessageLoop | This method is called immediately before entering the message loop. |
| CAtlServiceModuleT::RegisterAppId | Registers the service in the registry. |
| CAtlServiceModuleT::Run | Runs the service. |
| CAtlServiceModuleT::ServiceMain | The method called by the Service Control Manager. |
| CAtlServiceModuleT::SetServiceStatus | Updates the service status. |
| CAtlServiceModuleT::Start | Called by CAtlServiceModuleT::WinMain when the service starts. |
| CAtlServiceModuleT::Uninstall | Stops and removes the service. |
| CAtlServiceModuleT::Unlock | Decrements the service's lock count. |
| CAtlServiceModuleT::UnregisterAppId | Removes the service from the registry. |
| CAtlServiceModuleT::WinMain | This method implements the code required to run the service. |
Public Data Members
| Name | Description |
|---|---|
| CAtlServiceModuleT::m_bService | Flag indicating the program is running as a service. |
| CAtlServiceModuleT::m_dwThreadID | Member variable storing the thread identifier. |
| CAtlServiceModuleT::m_hServiceStatus | Member variable storing a handle to the status information structure for the current service. |
| CAtlServiceModuleT::m_status | Member variable storing the status information structure for the current service. |
| CAtlServiceModuleT::m_szServiceName | The name of the service being registered. |
Remarks
CAtlServiceModuleT, derived from CAtlExeModuleT, implements a ATL Service module. CAtlServiceModuleT provides methods for command-line processing, installation, registering, and removal. If extra functionality is required, these and other methods can be overridden.
This class replaces the obsolete CComModule Class used in earlier versions of ATL. See ATL Module Classes for more details.
Inheritance Hierarchy
CAtlServiceModuleT
Requirements
Header: atlbase.h
CAtlServiceModuleT::CAtlServiceModuleT
The constructor.
CAtlServiceModuleT() throw();
Remarks
Initializes the data members and sets the initial service status.
CAtlServiceModuleT::Handler
The handler routine for the service.
void Handler(DWORD dwOpcode) throw();
Parameters
dwOpcode
A switch that defines the handler operation. For details, see the Remarks.
Remarks
This is the code that the Service Control Manager (SCM) calls to retrieve the status of the service and issue instructions such as stop or pause. The SCM passes an operation code, shown below, to Handler to indicate what the service should do.
| Operation code | Meaning |
|---|---|
| SERVICE_CONTROL_STOP | Stops the service. Override the method CAtlServiceModuleT::OnStop in atlbase.h to change the behavior. |
| SERVICE_CONTROL_PAUSE | User implemented. Override the empty method CAtlServiceModuleT::OnPause in atlbase.h to pause the service. |
| SERVICE_CONTROL_CONTINUE | User implemented. Override the empty method CAtlServiceModuleT::OnContinue in atlbase.h to continue the service. |
| SERVICE_CONTROL_INTERROGATE | User implemented. Override the empty method CAtlServiceModuleT::OnInterrogate in atlbase.h to interrogate the service. |
| SERVICE_CONTROL_SHUTDOWN | User implemented. Override the empty method CAtlServiceModuleT::OnShutdown in atlbase.h to shutdown the service. |
If the operation code isn't recognized, the method CAtlServiceModuleT::OnUnknownRequest is called.
A default ATL-generated service only handles the stop instruction. If the SCM passes the stop instruction, the service tells the SCM that the program is about to stop. The service then calls PostThreadMessage to post a quit message to itself. This terminates the message loop and the service will ultimately close.
CAtlServiceModuleT::InitializeSecurity
Provides the default security settings for the service.
HRESULT InitializeSecurity() throw();
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
In Visual Studio .NET 2003, this method is not implemented in the base class. The Visual Studio project wizard includes this method in the generated code, but a compilation error will occur if a project created in an earlier version of Visual C++ is compiled using ATL 7.1. Any class that derives from CAtlServiceModuleT must implement this method in the derived class.
Use PKT-level authentication, impersonation level of RPC_C_IMP_LEVEL_IDENTIFY and an appropriate non-null security descriptor in the call to CoInitializeSecurity.
For wizard-generated nonattributed service projects, this would be in
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 appropiate Non NULL Security Descriptor.
return S_OK;
}
};
For attributed service projects, this would be in
[ 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 appropiate Non NULL Security Descriptor.
return S_OK;
}
};
CAtlServiceModuleT::Install
Installs and creates the service.
BOOL Install() throw();
Return Value
Returns TRUE on success, FALSE on failure.
Remarks
Installs the service into the Service Control Manager (SCM) database and then creates the service object. If the service could not be created, a message box is displayed and the method returns FALSE.
CAtlServiceModuleT::IsInstalled
Confirms that the service has been installed.
BOOL IsInstalled() throw();
Return Value
Returns TRUE if the service is installed, FALSE otherwise.
CAtlServiceModuleT::LogEvent
Writes to the event log.
void __cdecl LogEvent(LPCTSTR pszFormat, ...) throw();
Parameters
pszFormat
The string to write to the event log.
...
Optional extra strings to be written to the event log.
Remarks
This method writes details out to an event log, using the function ReportEvent. If no service is running, the string is sent to the console.
CAtlServiceModuleT::m_bService
Flag indicating the program is running as a service.
BOOL m_bService;
Remarks
Used to distinguish a Service EXE from an Application EXE.
CAtlServiceModuleT::m_dwThreadID
Member variable storing the thread identifier of the Service.
DWORD m_dwThreadID;
Remarks
This variable stores the thread identifier of the current thread.
CAtlServiceModuleT::m_hServiceStatus
Member variable storing a handle to the status information structure for the current service.
SERVICE_STATUS_HANDLE m_hServiceStatus;
Remarks
The SERVICE_STATUS structure contains information about a service.
CAtlServiceModuleT::m_status
Member variable storing the status information structure for the current service.
SERVICE_STATUS m_status;
Remarks
The SERVICE_STATUS structure contains information about a service.
CAtlServiceModuleT::m_szServiceName
The name of the service being registered.
TCHAR [256] m_szServiceName;
Remarks
A null-terminated string which stores the name of the service.
CAtlServiceModuleT::OnContinue
Override this method to continue the service.
void OnContinue() throw();
CAtlServiceModuleT::OnInterrogate
Override this method to interrogate the service.
void OnInterrogate() throw();
CAtlServiceModuleT::OnPause
Override this method to pause the service.
void OnPause() throw();
CAtlServiceModuleT::OnShutdown
Override this method to shut down the service.
void OnShutdown() throw();
CAtlServiceModuleT::OnStop
Override this method to stop the service.
void OnStop() throw();
CAtlServiceModuleT::OnUnknownRequest
Override this method to handle unknown requests to the service.
void OnUnknownRequest(DWORD /* dwOpcode*/) throw();
Parameters
/* dwOpcode */
Reserved.
CAtlServiceModuleT::ParseCommandLine
Parses the command line and performs registration if necessary.
bool ParseCommandLine(LPCTSTR lpCmdLine, HRESULT* pnRetCode) throw();
Parameters
lpCmdLine
The command line.
pnRetCode
The HRESULT corresponding to the registration (if it took place).
Return Value
Returns true on success, or false if the RGS file supplied in the command line could not be registered.
Remarks
Parses the command line and registers or unregisters the supplied RGS file if necessary. This method calls CAtlExeModuleT::ParseCommandLine to check for /RegServer and /UnregServer. Adding the argument -/Service will register the service.
CAtlServiceModuleT::PreMessageLoop
This method is called immediately before entering the message loop.
HRESULT PreMessageLoop(int nShowCmd) throw();
Parameters
nShowCmd
This parameter is passed to CAtlExeModuleT::PreMessageLoop.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
Override this method to add custom initialization code for the Service.
CAtlServiceModuleT::RegisterAppId
Registers the service in the registry.
inline HRESULT RegisterAppId(bool bService = false) throw();
Parameters
bService
Must be true to register as a service.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
CAtlServiceModuleT::Run
Runs the service.
HRESULT Run(int nShowCmd = SW_HIDE) throw();
Parameters
nShowCmd
Specifies how the window is to be shown. This parameter can be one of the values discussed in the WinMain section. The default value is SW_HIDE.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
After being called, Run calls CAtlServiceModuleT::PreMessageLoop, CAtlExeModuleT::RunMessageLoop, and CAtlExeModuleT::PostMessageLoop.
CAtlServiceModuleT::ServiceMain
This method is called by the Service Control Manager.
void ServiceMain(DWORD dwArgc, LPTSTR* lpszArgv) throw();
Parameters
dwArgc
The argc argument.
lpszArgv
The argv argument.
Remarks
The Service Control Manager (SCM) calls ServiceMain when you open the Services application in the Control Panel, select the service, and click Start.
After the SCM calls ServiceMain, a service must give the SCM a handler function. This function lets the SCM obtain the service's status and pass specific instructions (such as pausing or stopping). Subsequently, CAtlServiceModuleT::Run is called to perform the main work of the service. Run continues to execute until the service is stopped.
CAtlServiceModuleT::SetServiceStatus
This method updates the service status.
void SetServiceStatus(DWORD dwState) throw();
Parameters
dwState
The new status. See SetServiceStatus for possible values.
Remarks
Updates the Service Control Manager's status information for the service. It is called by CAtlServiceModuleT::Run, CAtlServiceModuleT::ServiceMain and other handler methods. The status is also stored in the member variable CAtlServiceModuleT::m_status.
CAtlServiceModuleT::Start
Called by CAtlServiceModuleT::WinMain when the service starts.
HRESULT Start(int nShowCmd) throw();
Parameters
nShowCmd
Specifies how the window is to be shown. This parameter can be one of the values discussed in the WinMain section.
Return Value
Returns S_OK on success, or an error HRESULT on failure.
Remarks
The CAtlServiceModuleT::WinMain method handles both registration and installation, as well as tasks involved in removing registry entries and uninstalling the module. When the service is run, WinMain calls Start.
CAtlServiceModuleT::Uninstall
Stops and removes the service.
BOOL Uninstall() throw();
Return Value
Returns TRUE on success, FALSE on failure.
Remarks
Stops the service from running and removes it from the Service Control Manager database.
CAtlServiceModuleT::Unlock
Decrements the service's lock count.
LONG Unlock() throw();
Return Value
Returns the lock count, which may be useful for diagnostics and debugging.
CAtlServiceModuleT::UnregisterAppId
Removes the service from the registry.
HRESULT UnregisterAppId() throw();
Return Value
Returns S_OK on success, or an error HRESULT on failure.
CAtlServiceModuleT::WinMain
This method implements the code required to start the service.
int WinMain(int nShowCmd) throw();
Parameters
nShowCmd
Specifies how the window is to be shown. This parameter can be one of the values discussed in the WinMain section.
Return Value
Returns the service's return value.
Remarks
This method processes the command line (with CAtlServiceModuleT::ParseCommandLine) and then starts the service (using CAtlServiceModuleT::Start).