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

_ATL_MODULE

CAtlModule

CAtlModuleT

CAtlExeModuleT

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

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 appropriate 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 appropriate 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).

See also

CAtlExeModuleT Class
Class Overview