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.

System_CAPS_ICON_important.jpg Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

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.

Public Constructors

NameDescription
CAtlServiceModuleT::CAtlServiceModuleTThe constructor.

Public Methods

NameDescription
CAtlServiceModuleT::HandlerThe handler routine for the service.
CAtlServiceModuleT::InitializeSecurityProvides the default security settings for the service.
CAtlServiceModuleT::InstallInstalls and creates the service.
CAtlServiceModuleT::IsInstalledConfirms that the service has been installed.
CAtlServiceModuleT::LogEventWrites to the event log.
CAtlServiceModuleT::OnContinueOverride this method to continue the service.
CAtlServiceModuleT::OnInterrogateOverride this method to interrogate the service.
CAtlServiceModuleT::OnPauseOverride this method to pause the service.
CAtlServiceModuleT::OnShutdownOverride this method to shut down the service
CAtlServiceModuleT::OnStopOverride this method to stop the service
CAtlServiceModuleT::OnUnknownRequestOverride this method to handle unknown requests to the service
CAtlServiceModuleT::ParseCommandLineParses the command line and performs registration if necessary.
CAtlServiceModuleT::PreMessageLoopThis method is called immediately before entering the message loop.
CAtlServiceModuleT::RegisterAppIdRegisters the service in the registry.
CAtlServiceModuleT::RunRuns the service.
CAtlServiceModuleT::ServiceMainThe method called by the Service Control Manager.
CAtlServiceModuleT::SetServiceStatusUpdates the service status.
CAtlServiceModuleT::StartCalled by CAtlServiceModuleT::WinMain when the service starts.
CAtlServiceModuleT::UninstallStops and removes the service.
CAtlServiceModuleT::UnlockDecrements the service's lock count.
CAtlServiceModuleT::UnregisterAppIdRemoves the service from the registry.
CAtlServiceModuleT::WinMainThis method implements the code required to run the service.

Public Data Members

NameDescription
CAtlServiceModuleT::m_bServiceFlag indicating the program is running as a service.
CAtlServiceModuleT::m_dwThreadIDMember variable storing the thread identifier.
CAtlServiceModuleT::m_hServiceStatusMember variable storing a handle to the status information structure for the current service.
CAtlServiceModuleT::m_statusMember variable storing the status information structure for the current service.
CAtlServiceModuleT::m_szServiceNameThe name of the service being registered.

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.

_ATL_MODULE

CAtlModule

CAtlModuleT

CAtlExeModuleT

CAtlServiceModuleT

Header: atlbase.h

The constructor.

CAtlServiceModuleT() throw();

Remarks

Initializes the data members and sets the initial service status.

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 codeMeaning
SERVICE_CONTROL_STOPStops the service. Override the method CAtlServiceModuleT::OnStop in atlbase.h to change the behavior.
SERVICE_CONTROL_PAUSEUser implemented. Override the empty method CAtlServiceModuleT::OnPause in atlbase.h to pause the service.
SERVICE_CONTROL_CONTINUEUser implemented. Override the empty method CAtlServiceModuleT::OnContinue in atlbase.h to continue the service.
SERVICE_CONTROL_INTERROGATEUser implemented. Override the empty method CAtlServiceModuleT::OnInterrogate in atlbase.h to interrogate the service.
SERVICE_CONTROL_SHUTDOWNUser 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.

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;
   }
};

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.

Confirms that the service has been installed.

BOOL IsInstalled() throw();

Return Value

Returns TRUE if the service is installed, FALSE otherwise.

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.

Flag indicating the program is running as a service.

BOOL m_bService;

Remarks

Used to distinguish a Service EXE from an Application EXE.

Member variable storing the thread identifier of the Service.

DWORD m_dwThreadID;

Remarks

This variable stores the thread identifier of the current thread.

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.

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.

The name of the service being registered.

TCHAR [256] m_szServiceName;

Remarks

A null-terminated string which stores the name of the service.

Override this method to continue the service.

void OnContinue() throw();

Override this method to interrogate the service.

void OnInterrogate() throw();

Override this method to pause the service.

void OnPause() throw();

Override this method to shut down the service.

void OnShutdown() throw();

Override this method to stop the service.

void OnStop() throw();

Override this method to handle unknown requests to the service.

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

Parameters

/* dwOpcode */
Reserved.

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.

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.

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.

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.

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.

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.

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.

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.

Decrements the service's lock count.

LONG Unlock() throw();

Return Value

Returns the lock count, which may be useful for diagnostics and debugging.

Removes the service from the registry.

HRESULT UnregisterAppId() throw();

Return Value

Returns S_OK on success, or an error HRESULT on failure.

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

CAtlExeModuleT Class
Class Overview

Show: