CNTService v2.09

Welcome to CNTService, a collection of freeware C++ classes which provide a class framework for developing NT services.

For detailed information about NT services, how to develop them and their relationship to other NT subsystems, I would suggest you thoroughly read the relevant documentation which comes with the Windows SDK.

Features

• Simple and clean C++ interface using virtual functions.
• All the code is Unicode enabled and build configurations are provided.
• All code compiles cleanly at the highest warning level of 4. This is the case with all of my other code on my web site as well.
• Built in persistence functions which provide support similar to the built in MFC registry / ini functions.
• A simple test service has been provided to help you get started developing your own NT services.

Usage

• To use the classes in your code simple include ntserv*.cpp in your project and #include ntserv.h in which ever of your modules needs to make calls to the class and derive your own service class from CNTService and override the necessary functions.
• You should also copy across the "IDS_NTSERV..." string resources from the sample project into your service's project.
• You can optionally also develop a simple DLL of the same name as your service which includes just the MC resources. See the "TestSrvMsg" subproject in the sample for how this works. For further information on this check on the history details for v1.06 and v1.08 below.
• To see the class in action, have a look at the code in InitInstance in the module "app.cpp".
• As of v1.89, the code is now for Visual C++ 2017 or later.
• You must also compile CNTService using /std:c++17 or higher.

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

History

v2.09 (28 March 2024)

• Updated copyright details.
• Fixed a number of compiler issues reported by Visual Studio 2022.

v2.08 (23 September 2023)

• Updated SAL across the code.

v2.07 (10 May 2023)

• Updated copyright details
• Updated modules to indicate that it needs to be compiled using /std:c++17. Thanks to Martin Richter for reporting this issue.

v2.06 (5 February 2022)

• Updated the code to use C++ uniform initialization for all variable declarations
• Reworked CNTService::ReportStatus and CNTService::_ReportStatus methods to use std::optional for some of its parameters.

v2.05 (15 January 2022)

• Removed defunct _ServiceCtrlHandler method.
• Reworked CNTService::RegisterCtrlHandler and CNTService::_ServiceCtrlHandlerEx methods to use third parameter to RegisterServiceCtrlHandlerEx instead of need to use sm_pService static member variable.
• Updated the sample service included with the download to log the current system time to the registry value HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\PJSERVICE\Parameters\General\CurrentSystemTime.

v2.04 (9 January 2022)

• Updated copyright details
• Fixed more Clang-Tidy static code analysis warnings in VC 2022 in the code.

30 July 2021

• Updated copyright details.
• Updated compiler settings to more modern defaults.

v2.03 (26 July 2020)

• Fixed more Clang-Tidy static code analysis warnings in the code.
• Fixed a compile problem in ntservEventLogRecord.cpp in VC 2019 related to missing iterator header file.
• Updated the codebase to support GetSharedServiceRegistryStateKey and GetSharedServiceDirectory APIs.
• Fixed up the logic and return values for the CNTService::GetRegistryStateKey and CNTService::GetServiceDirectory methods now that there is proper documentation available for these APIs.

v2.02 (12 April 2020)

• Fixed more Clang-Tidy static code analysis warnings in the code.

v2.01 (5 January 2020)

• Fixed more Clang-Tidy static code analysis warnings in the code.

v2.0 (28 December 2019)

• Fixed various Clang-Tidy static code analysis warnings in the code.

v1.99 (6 November 2019)

• Removed unnecessary return value from CNTServiceControlManager::Attach method.
• Removed unnecessary return value from CNTScmService::Attach method.
• Removed unnecessary return value from CNTEventLogSource::Attach method.
• Removed unnecessary return value from CNTEventLog::Attach method.
• Replaced BOOL with bool in a number of places throughout the framework.

v1.98 (3 November 2019)

• Updated initialization of various structs to use C++ 11 list initialization

v1.97 (26 October 2019)

• Updated CNTServiceCommandLineInfo::ParseParam to handle text arguments which may include spaces. This means that for example using the command line form /switch:"Text with Blank" will be handled correctly. Thanks to Martin Richter for suggesting this nice addition.

v1.96 (17 September 2019)

• Remove noexcept attribute from a number of CNTService virtual methods

v1.95 (13 August 2019)

• Fixed some compile problems when _ATL_NO_AUTOMATIC_NAMESPACE is defined
• Fixed some further compiler warnings when using VC 2019 Preview v16.3.0 Preview 2.0
• Fixed a problem in CNTService::GetServiceParametersKey where the bReadOnly parameter was not being used to open some registry keys.

v1.94 (28 July 2019)

• Fixed some further compiler warnings when using VC 2019 Preview

v1.93 (2 June 2019)

• Updated copyright details
• Updated the code to clean compile on VC 2019
• Replaced all occurrences of ATL::CHeapPtr with std::vector

v1.92 (1 September 2018)

• Fixed up code which supports GetServiceRegistryStateKey and GetServiceDirectory APIs to reference correct Windows DLL.

v1.91 (29 August 2018)

• Fixed a number of compiler warnings when using VS 2017 15.8.1
• Updated the codebase to support GetServiceRegistryStateKey and GetServiceDirectory APIs

v1.90 (2 June 2018)

• Supressed final C++ core guidelines compiler warnings from the code.
• Tidied up various project settings in the sample solution and project files.

v1.89 (26 May 2018)

• Updated copyright details.
• Fixed a number of C++ core guidelines compiler warnings. These changes mean that the code will now only compile on VC 2017 or later.
• Removed all code which supports now defunct CNTSERVICE_MFC_EXTENSIONS code paths
• CNTService::Debug method is now passed unmodified command line parameters.

v1.88 (16 September 2017)

• Replaced CNTServiceString::operator LPC*STR() calls throughout the codebase with CNTServiceString::GetString calls.

v1.87 (27 April 2017)

• Updated the code to compile cleanly using /permissive-.

v1.86 (16 April 2017)

• Added support for SubscribeServiceChangeNotifications, UnsubscribeServiceChangeNotifications and WaitServiceState API calls from the latest Windows 10 SDK.
• Removed CNTScmService::AcceptStop, AcceptPauseContinue & AcceptShutdown methods as they provided not very useful encapsulated functionality.
• Added support for SERVICE_CONTROL_LOWRESOURCES & SERVICE_CONTROL_SYSTEMLOWRESOURCES from the latest Windows 10 SDK.

v1.85 (9 April 2017)

• Updated copyright details.
• Update the code to compile cleanly on VC 2017
• Replaced NULL throughout the codebase with nullptr. This means that the minimum requirement for the framework is now VC 2010.
• Removed all code which used function pointers for API calls prior to Windows XP / 2003.

v1.84 (15 November 2016)

• Updated the sample app's project settings to create the message file with the name "TestSrv.dll" in the directory where the "TestSrv.exe" binary for the sample service is created. Thanks to Brian Minor for reporting this issue.
• Corrected initialization of a local variable in the method CNTService::WriteServiceProfileString.

v1.83 (1 June 2016)

• Fixed a bug in the non MFC code path in CNTService::GetServiceProfileString where the code left a nullptr byte in the std::string return value prior to returning from the method. Therefore the returned string object contained a binary zero and cannot be used to concatenate other strings. Thanks to Martin Gamperl for spotting this bug.
• Some minor tidy-ups to the code style throughout the ntserv.cpp module.

v1.82 (19 April 2016)

• Updated copyright details.
• Addition of a new /EnableServiceLogonRight command line option. When this is passed and the /install and /U options are provided, the code will first enable the SeServiceLogonRight privilege for the specified account using the LsaAddAcountRights API.

v1.81 (18 December 2015)

• Updated copyright details.
• Verified code compiles cleanly on VC 2015.
• Updated CNTService::ProcessShellCommand to use string::find instead of std::find.
• Reviewed all the changes in the Windows 10 SDK to do with Services to make sure the classes support new functionality and compile correctly when used with this updated SDK.
• Added SAL annotations to all the code

v1.80 (1 January 2014)

• Updated copyright details.
• Updated code to clean compile on VC 2013
• Reworked the classes to optionally compile without MFC. By default the classes now use STL for strings and arrays but if you define CNTSERVICE_MFC_EXTENSIONS, the classes will revert back to using the MFC collection classes.
• Updated the codebase to support all Service features upto Windows 8.1. New features supported includes SERVICE_CONFIG_LAUCH_PROTECTED support available via CNTScmService::QueryLaunchProtected and CNTScmService::ChangeLaunchProtected and QueryServiceDynamicInformation support available via CNTService::QueryServiceDynamicInformation.

v1.79 (10 November 2012)

• Updated copyright details.
• Updated sample service code to clean compile on VC 2012.
• Reworked CNTScmService::WaitForServiceStatus method to avoid the need for calling GetTickCount.
• Fixed a bug in CNTEventLogSource::GetStringArrayFromRegistry where it could not handle empty MULTI_SZ strings. Thanks to Rolf Schatten for reporting this bug.
• CNTEventLogSource::Install now calls CRegKey::Create instead of CRegKey::Open when installing the HKLM\SYSTEM\CurrentControlSet\Services\EventLog\"LogName" registry key. This ensures that event log sources which are created with custom LogName's will be installed correctly. Thanks to Rolf Schatten for reporting this bug.

v1.78 (3 September 2010)

• Fixed a bug in CNTService::GetServiceProfileString where it would incorrectly return FALSE.
• Fixed a bug in CNTService::GetServiceProfileInt where it would incorrectly return FALSE.

v1.77 (1 August 2010)

• Updated copyright details.
• Updated the project settings to more modern default values.
• Fixed a trailing "," in the definition of the "ELErrorLoggingDetail" enum
• Updated the sample app to compile cleanly on VC 2010
• Updated the test code in App.cpp to only use the necessary rights when connecting to the SCM or opening a specific service. This avoids Access denied errors on Windows Vista or later when UAC is enabled. Thanks to Jan Bartels for reporting this issue.
• Added support for the following SERVICE_CONTROL_* defines: SERVICE_CONTROL_SESSIONCHANGE, SERVICE_CONTROL_PRESHUTDOWN, SERVICE_CONTROL_TIMECHANGE & SERVICE_CONTROL_TRIGGEREVENT. These control values represent new functionality for services on Windows Vista and Windows 7
• Added a comment to a #include to tell users to recompile TestSrvMsg if they get a compile error for "ntserv_msg.h". Thanks to Paul Pignon for reporting this issue.
• Updated code to compile correctly using _ATL_CNTServiceString_EXPLICIT_CONSTRUCTORS define
• Fixed a minor issue in CNTService::Win32ErrorToString with the use of printf format identifiers
• Reworked all the internal heap memory management code to use ATL::CHeapPtr
• Reworked all the internal registry management code to use ATL::CRegKey
• The CNTService::m_bRegisterEventLogSource value has been renamed to m_bEventLogSource. This is a breaking change and may require your service code to be updated if you reference this value from your code.
• CNTService::Install has been refactored. Internally now this function calls InstallEventLogSource and InstallServiceConfiguration
• Fixed a minor issue in CNTEventLogSource::Report with the use of printf format identifiers
• CNTEventLogSource::Install method now supports CategoryCount, CategoryMessageFile and ParameterMessageFile settings for event sources
• Included notes in documentation about using MSI in preference to "/install" / "/uninstall"
• Added support for NotifyServiceStatusChange
• Added support for ControlServiceEx
• Added support for SERVICE_CONFIG_DELAYED_AUTO_START_INFO
• Added support for SERVICE_CONFIG_FAILURE_ACTIONS_FLAG
• Added support for SERVICE_CONFIG_SERVICE_SID_INFO
• Added support for SERVICE_CONFIG_REQUIRED_PRIVILEGES_INFO
• Added support for SERVICE_CONFIG_PRESHUTDOWN_INFO
• Added support for SERVICE_CONFIG_TRIGGER_INFO
• Added support for SERVICE_CONFIG_PREFERRED_NODE
• CEventLogRecord::m_TimeGenerated and CEventLogRecord::m_TimeWritten values are now simple DWORD values instead of CTime instances.
• Added support for GetEventLogInformation
• Carried out a thorough code review to ensure all functionality is correct and functional on the Windows 7 and later

v1.76 (1 June 2008)

• Code now compiles cleanly using Code Analysis (/analyze)
• The code has now been updated to support VC 2005 or later only.

v1.75 (12 January 2008)

• Updated copyright details.
• Provided a link to my blog in the html documentation with details on compiling with VC 6.
• CNTService::Win32ErrorToString method has been reworked to now uses the FORMAT_MESSAGE_IGNORE_INSERTS flag. For more information please see Raymond Chen's blog at http://blogs.msdn.com/oldnewthing/archive/2007/11/28/6564257.aspx. Thanks to Alexey Kuznetsov for reporting this issue.
• Updated the sample app to clean compile on VC 2008.
• SecureEmptyString method is now defined as "FORCEINLINE".

v1.74 (19 November 2007)

• Minor update to display HRESULT's correctly.

v1.73 (22 March 2007)

• CNTService::SetServiceToStatus and CNTService::Uninstall no longer specifies that it requires the SC_MANAGER_LOCK access right to connect to the SCM. This change helps to allow services to be started and stopped from Power User accounts. Thanks to Matthias Miller for reporting this issue.
• CNTService::SetServiceToStatus no longer specifies the STANDARD_RIGHTS_REQUIRED access right when opening a service to control. This change helps to allow services to be started and stopped from Power User accounts. Thanks to Matthias Miller for reporting this issue.

v1.72 (2 February 2007)

• Updated copyright details.
• Optimized CNTEventLog constructor code.
• Reworked CNTService::SetServiceToStatus to allow the last error value to be reported back to client code. Thanks to Matthias Miller for reporting this issue.
• Optimized calls to Win32ErrorToString.

20 November 2006

• Minor update to use console I/O in the sample app instead of a MessageBox in CMyService::ShowHelp.
• Optimized the member variable construction in CMyService::CMyService.

v1.71 (21 September 2006)

• Minor update to use %X instead of %x in various TRACE statements and CNTEventLogSource::Report calls.

v1.70 (1 August 2006)

• Fix for two buffer size calculations using the new _tcscpy_s functions, one in CNTEventLogSource::SetStringArrayIntoRegistry and the other in CNTService::GetDependencies. Thanks to DmityShm on the codeproject forums for reporting this issue.

v1.69 (27 July 2006)

• The static versions of the profile functions in CNTService have now been renamed to include the word "Service" in their method names. This fixes a compiler error when the code is used in VC 2005.

v1.68 (2 July 2006)

• Optimized and tidied up DllMain code in TestSrvMsg.cpp
• All calls to m_EventLogSource.Report are now protected with "if (m_bRegisterEventLogSource)" check
• Removed now unused Project configurations from the VC 6 workspace file.

v1.67 (25 June 2006)

• Combined the functionality of the _NTSERV_SERVICCONTROLMANAGER_DATA class into the main CNTServiceControlManager class.
• Code now uses newer C++ style casts instead of C style casts.
• Combined the functionality of the _NTSERV_SCMSERVICE_DATA class into the main CNTScmService class.
• Made the item data parameter to CNTScmService::EnumDependents a void* instead of the current DWORD.
• Optimized CEventLogRecord constructor
• Combined the functionality of the _NTSERV_DATA class into the main CNTService class.
• The class framework now requires the Platform SDK if compiled using VC 6.
• Fixed code which was not securely resetting the command line username and password strings after they were used

v1.66 (24 June 2006)

• Added a missing MapResourceID call in CNTService::Win32ErrorToString.
• Updated the sample dsp and vcproj files to produce Unicode mc resources instead of ASCII.
• Framework now accepts the command line /console to mean the same as /debug i.e. run the program as a normal (console) application without interacting with the Service Control Manager.
• Updated code to compile cleanly using VC 2005.
• Included info in ntservEventLogSource.cpp on how to find further info on the various registry values which are required to create user defined event logs.

v1.65 (13 June 2006)

• Addition of a logname parameter to the CNTEventLogSource constructor to support user defined event logs instead of logging to the standard "Application" event log. Please note that the code added only enables the CNTService framework to use non "Application" event logs, but it does not contain code to create a custom event log. You will need to handle that in your application's install. Thanks to Jan Bartels for this addition.
• Also optimized the construction of member variables in the CNTEventLogSource constructors
• To allow customization in client projects, the resource id and message id values can now be customized through two new virtual functions, namely CNTService::MapResourceID and CNTService::MapMessageID. Thanks to Jan Bartels for this update.
• CNTService::SetServiceToStatus now exposes the interval to wait as a parameter as well as the polling interval as a parameter. In addition the command line timeout interval is now passed to all calls to SetServiceToStatus in CNTService::ProcessShellCommand. The additional command line operations which are passed the timeout value include starting, stopping, pausing and continuing the service, in addition to uninstalling the service which when it was introduced in v1.27 was the only operation which got the timeout value.
• Fixed a bug introduced in v1.64 where the sample service was updated to run as a console app. What I forgot to do when making this change was put in the call to AfxWinInit.

v1.64 (9 June 2006)

• Made CNTService::Initialize non virtual. This change was made because it is called by the CNTService constructor and you cannot call virtual functions from a C++ class constructor (or destructor). For more info on this issue please see the online article at http://www.artima.com/cppsource/nevercall.html from the book "Effective C++" by Scott Meyers. Thanks to Frederic Metrich for spotting this issue. Because of this change you should examine your own code which uses CNTService::Initialize to make sure this change has no side effects on your code.

v1.63 (7 June 2006)

• Removed three unreferrenced variables from CNTService::ProcessShellCommand. Thanks to Frederic Metrich for reporting this issue.
• Minor update to the declaration of some functions in CNTService to using "WINAPI" in their function implementations. Thanks to Frederic Metrich for reporting this issue.
• Updated the code in CNTService::Debug to exclude the "/debug", "-app", "/app", "-application" and "/application" command line options in addition to the "-debug" value. Again thanks to Frederic Metrich for reporting this issue.
• Updated the sample service provided with the CNTService download to build as a console app instead of a Windows app. This allows you to check out the console handler support which CNTService includes.

v1.62 (3 June 2006)

• If CNTEventLogSource::Uninstall fails to remove the HKLM\System\CurrentControlSet\Services\EventLog\"Display Name" registry key, then it aborts before doing any other work. Thanks to Matthias Miller for reporting this issue.
• Fixed a minor typo in CNTService::SetServiceToStatus. Thanks to Matthias Miller for reporting this issue.

v1.61 (31 May 2006)

• Updated the code to work correctly in VC 6 without the Platform SDK being installed. I personally have the Feb 2003 Platform SDK installed with VC 6 and this is how most of my code is primarily tested. It seems some of my recent updates to CNTService have broken compatibility with VC 6 on its own. Also renamed the define "NTSERV_DO_NEW_WINSVC_DEFINES" which is required when you are compiling the class framework on Visual C++ 6 without the Platform SDK to be "CNTSERVICE_MISSING_PLATFORMSDK". Please note that I would advise all developers to install the Platform SDK (February 2003 was the latest version which was compatible with VC 6), as I will probably drop support for VC 6 without the Platform SDK for CNTService in the future. It is becoming too much work to support the older Header files which were shipped with VC 6 and most of my other open source code is moving towards requiring the Platform SDK. Thanks to Matthias Miller for reporting this issue. The "NTSERV_EXCLUDE_VC6_WINSVC_DEFINES" define is now defunct and no longer used by the CNTService code.

v1.60 (18 May 2006)

• Minor update to rename the local variable of type _NTSERV_SERVICCONTROLMANAGER_DATA which is used to hold function pointers. Thanks to Frederic Metrich for reporting this issue.
• Minor update to rename the local variable of type _NTSERV_SCMSERVICE_DATA which is used to hold function pointers. Thanks to Frederic Metrich for reporting this issue.

v1.59 (12 May 2006)

• Minor update to ntservEventLogRecord.cpp module to remove now unnecessary include of AfxPriv.h. Thanks to Martin Richter for reporting this issue.
• Also updated the usage instructions in this document to describe how you can use copy & paste to speed up the job. Again thanks to Martin Richter for reporting this issue.

v1.58 (27 April 2006)

• Code now uses SecureZeroMemory when wiping out the username and password strings. This should further improve the security of these values when they are manipulated by the class framework.

v1.57 (13 January 2006)

• Addition of a new /AUTO command line option which allows you to specify that the service should be started automatically.

v1.56 (11 January 2006)

• The command line options which the service uses to start with can now be specified via a new /SCL command line option e.g. TestSrv.exe /install "/SCL:/Param1 /SomeOtherParam:XYZ". This additional flexibility is controlled by BOOL CNTService::m_bAllowCommandLine which by default is FALSE.
• Updated copyright details for all modules
• The service display name string which the service uses for installing can now be specified via a new /SDN command line option. This is achieved by supporting a new command line option e.g. TestSrv.exe /install "/SDN:PJ's Second Test Service". This additional flexibility is controlled by BOOL CNTService::m_bAllowDisplayNameChange which by default is FALSE.
• The description string which the service uses for installing can now be specified via a new /SD command line option. This is achieved by supporting a new command line option e.g. TestSrv.exe /install "/SD:Some description". This additional flexibility is controlled by BOOL CNTService::m_bAllowDescriptionChange which by default is FALSE.
• The service name string which the service uses for installing can now be specified via a new /SN command line option. This is achieved by supporting a new command line option e.g. TestSrv.exe /install "/SN:PJSERVICE2". This additional flexibility is controlled by BOOL CNTService::m_bAllowNameChange which by default is FALSE.
• Removed code which writes an event log entry when the service is being uninstalling. There is not much sense in logging an entry that you have uninstalled the service, when you are also uninstalling the event log source.
• Removed the ANSI mc file. Instead now the mc file included in the zip file is the Unicode mc file as provided by Brodie Thiesfield (see the history list for v1.35).
• Updated the documentation to use the same style as the web site.
• When registering the service, the quoting of the path name to use for the service is now done in CNTService::ProcessShellCommand instead of CNTScmService::Create.
• Optimized code in CNTServiceCommandLineInfo::CNTServiceCommandLineInfo.
• Removed unnecessary CNTServiceCommandLineInfo destructor.
• Removal of CNTService::GetEventLogSourceName method. Instead now you can call m_EventLogSource.SetSourceName() to customize this value.
• Provision of CNTService::SetUseConsole and CNTService::GetUseConsole methods.
• The default setting for CNTService::m_bUseConsole is now set depending on whether the standard _CONSOLE preprocessor define is declared
• Removed the unnecessary critical section lock in the CNTService constructor
• Provision of CNTService::SetControlsAccepted and CNTService::GetControlsAccepted methods.
• Provision of a default CNTService constructor
• Addition of a default constructor for CNTEventLogSource
• Addition of CNTEventLogSource::SetServerName, CNTEventLogSource::GetServerName, CNTEventLogSource::SetSourceName and CNTEventLogSource::GetSourceName methods
• Provision of CNTService::SetServiceName, CNTService::SetInstanceServiceName, CNTService::SetMasterServiceName, CNTService::GetInstanceServiceName, CNTService::GetMasterServiceName, CNTService::SetDisplayName, CNTService::SetMasterDisplayName, CNTService::SetInstanceDisplayName, CNTService::GetMasterDisplayName, CNTService::GetInstanceDisplayName, CNTService::SetDescription, CNTService::SetMasterDescription, CNTService::SetInstanceDescription methods, CNTService::GetMasterDescription and CNTService::GetInstanceDescription. Most of the work for this release of the framework is to support a new concept of "instances" in CNTService. Prior to this version of the CNTService framework, you could only ever install a single copy of any one service on the one machine. Now with the introduction of the /SDN, /SD and /SN command line options which are used during install and uninstall you can register the service multiple times, using different service names, display names and descriptions. The original values you construct your CNTService instance are called the master values and are unmodified during the lifetime of all instances of your services. The "instance" values are modifiable (if you allow them to be so via CNTService::m_bAllowNameChange, CNTService::m_bAllowDisplayNameChange and CNTService::m_bAllowDescriptionChange) at runtime. When these values are provided on the command line during registration, the command line which the service is setup to use upon launch by the SCM is customized so that these same command line options are passed to it. This allows the same instance values to be available to the service when it is running as a service. Without this neat trick, there would be no easy way for the service to detect under which instance details it should run.
• Addition of 2 new command line options namely "/App" or "/Application". These behave the same way as the existing "/Debug" command line option.
• Addition of a DWORD* parameter to the CNTEventLogSource::GetStringArrayFromRegistry and CNTEventLogSource::SetStringArrayFromRegistry functions. This allow the details of the last error to be returned to client code.
• Addition of generic versions of CNTService::WriteProfileString, CNTService::WriteProfileInt, CNTService::WriteProfileStringArray, CNTService::WriteProfileBinary, CNTService::GetProfileString, CNTService::GetProfileInt, CNTService::GetProfileStringArray and CNTService::GetProfileBinary. These implementations allow the service name to be specified as well as the Flushing setting which is hidden by the other implementations. The existing implementations of these functions now simply call these new implementations. Providing these implementations now allows client code to read and write the settings for any service (including other instances of the same service) without the need to create a new CNTService instance.
• CNTServiceControlManager::EnumServices method now uses a void* parameter for its item data instead of a DWORD.
• Addition of a CNTService::EnumerateInstances method which allows you to enumerate all the instances of a service which have been installed using the new master / instance additions to the framework in this version. This could prove useful where you are writing configuration type applets which configure the settings for all the instances of your installed service.
• Addition of a new /U command line option which allows the user account which the service runs under to be configured.
• Addition of a new /P command line option which allows the password which the service is to run with to be configured.
• As a security precaution once the username and password strings have been used for installing, they are overwritten in memory.

v1.55 (14 August 2005)

• Fixed an issue where the SID and binary values was not being set correctly in the overloaded CEventLogRecord constructor which takes a EVENTLOGRECORD pointer. Thanks to Brian Lee for reporting this issue. Also the arrays which this information is copied into is now preallocated to improve performance.

v1.54 (31 July 2005)

• Provided an overridden version of CNTEventLogSource::Report which has 3 string parameters
• CNTEventLogSource::GetStringArrayFromRegistry and SetStringArrayIntoRegistry methods are now public as they are helpful to have available externally.

v1.53 (21 April 2005)

• CNTService::GetProfileInt and GetProfileString functions now includes an optional DWORD output parameter which when provided allows the value from GetLastError to be returned to client code. This allows code to distinguish between a default value which is returned because it is actually stored as opposed to returning a default value because some of the registry API's failed. Thanks to Tony Ronan for reporting this issue.

v1.52 (26 March 2005)

• Addition of a m_bProfileWriteFlush variable to the CNTService class which dictates if the registry settings should be committed immediately as opposed to relying on the lazy writer.

v1.51 (11 February 2005)

• Addition of a virtual GetEventLogSourceName method which allows the name of the event log source to be customized at runtime. Thanks to Bara Cek for requesting this addition.
• Updated the copyright details in all modules.
• Addition of true Visual Studio .NET 2003 files for the sample service (Testsrv.sln and Testsrv.vcproj)

v1.50 (11 November 2004)

• Fixed a futher 64 bit issue in CNTEventLogSource::SetStringArrayIntoRegistry when compiled in Visual Studio .Net.
• Addition of a CNTSERVICE_EXT_CLASS preprocessor macro which allows the classes to be easily added to an extension dll

v1.49 (18 October 2004)

• Fixed a number of level 4 warnings in the framework when "Detect 64 bit portability issues" is enabled in Visual Studio .Net

v1.48 (15 October 2004)

• Framework now automatically installs a console ctrl handler when run in debug mode. This means that the framework will automatically call your service's OnStop method when running in debug mode if your service is built as a console app and you hit Ctrl+C or Ctrl+Break or hit the close button in the console window. This helps you to verify the shutdown code of your service without having to run the code as a service. Because the console ctrl handler is executed in a separate thread to ServiceMain, this simulation mode calls your OnStop method in a separate thread just like the SCM does. This proves very helpful when you need to debug shutdown problems in your service which are thread related.
• Added a few checks to various header files to warn if various header files have not already been included e.g. Afxmt.h. This helps avoid simple compilation problems when the framework is added to a new project initially.
• Sample app now uses the InterlockedExchange functions instead of a critical section to serialize access to variables used across multiple threads. In addition the "m_bPaused" variable of the sample app is now also marked as volatile
• Fixed a double declaration of "dwTypesSupported" in CNTEventLogSource::Install. In the process this fixes a level 4 warning which the code generated.

v1.47 (24 June 2004)

• Reissue of the last update as I forgot to declare _ServiceMain virtual, Doh!
• Also made the class CNTServiceTerminateException visible in the global namespace. This is required if you implement your own _ServiceMain.

v1.46 (20 June 2004)

• Provided a new virtual implementation of CNTService::_ServiceMain. To achieve this the previous static _ServiceMain is now called "_SDKServiceMain". This allows your service code to completely customize the startup of your service. For example if you service does not require an active worker thread to do any work (e.g. it only ever responds to client requests thro the SCM using OnUserDefinedRequest), then you could implement your own version of _ServiceMain which does not call _ReportStatus(SERVICE_STOPPED... This would allow you to use RegisterWaitForSingleObject to implement your service clean up code. For more information on this type of service please consult the MSDN documentation on "RegisterWaitForSingleObject" and "ServiceMain". Thanks to Haug Leuschner for reporting this.

v1.45 (20 June 2004)

• Fixed a bug in CEventLogRecord::CEventLogRecord(const EVENTLOGRECORD*..) to do with the handling of inter string NULLs at the end of the record. Thanks to "yong" for reporting this problem.
• Optimized the code in CEventLogRecord::CEventLogRecord(const EVENTLOGRECORD*..).

v1.44 (5 May 2004)

• Fixed some warnings in CNTService::GetDependencies and CNTEventLogSource::SetStringArrayIntoRegistry when the code is compiled using the "Force conformance in For loop scope" VC compiler option (/Zc:forScope). Thanks to Alexey Kuznetsov for reporting this problem.

v1.43 (12 April 2004)

• Removed an unused variable in CNTScmService::WaitForServiceStatus. Thanks to Edward Livingston for reporting this issue.

v1.42 (9 April 2004)

• Further work to CNTScmService::WaitForServiceStatus. It now ignores pending states. In addition it ignores wait hints since we are calling QueryServiceStatus as opposed to calling the ControlService function with the SERVICE_CONTROL_INTERROGATE control code. It also allows the polling interval to be specified by a 3rd optional parameter. Thanks to Edward Livingston and "yong" for reporting this problem. Please note that since the third parameter to this function means something different that previously, you should review all of your calls to WaitForServiceStatus to ensure it continues to operate correctly.

v1.41 (18 March 2004)

• Fixed a bug in the CNTScmService::WaitForServiceStatus function which caused it to return TRUE even if the service failed to return the desired status (if pending status isn't the expected pending staus.
• Also ensured that CNTScmService::WaitForServiceStatus does not wait past the requested timeout period. Thanks to Brodie Thiesfield for these bug reports and the fixes.

21 February 2004

• The Unicode version of the mc file has now been updated to include Korean resources. Thanks to Brodie Thiesfield for this update.

v1.40 (22 January 2004)

• Fixed a bug in CNTScmService::EnumDependents and CNTServiceControlManager::EnumServices where enumeration would continue even when the callback functions return FALSE. Thanks to Edward Livingston for spotting this.

13 January 2004

• Updated the declaration of the sample service's "m_bWantStop" variable to now be a variable. There is no change to the actual CNTService modules (bar copyright updates for the new year 2004)

v1.39 (26 November 2003)

• Now supports a /silent command line option. Using this setting in combination with for example /install will ensure that the framework does not display any message boxes or console output when an error occurs. Thanks to Metrich Frederic for this addition.
• Changed the return value from ProcessShellCommand from a BOOL to a DWORD. This value is now use to return an error code from the service exe when it exits. In combination with the /silent command line option, this allows third party programs such as installers control over the service instance via the exit code of the service. Again thanks to Metrich Frederic for this addition.
• Updated the sample app provided with the framework to show how client services can return the Win32 error code as now returned by ProcessShellCommand.

v1.38 (23 November 2003)

• Fixed a memory leak in CNTService::Debug when the service uses TerminateService to shutdown the service prematurely.

v1.37 (19 November 2003)

• Reworked the function Win32ErrorToString to include the string resource ID. Thanks to Brodie Thiesfield for suggesting this.
• Fixed CNTS_MSG_SERVICE_FAIL_PAUSE, CNTS_MSG_SERVICE_FAIL_CONTINUE and CNTS_MSG_SERVICE_FAIL_STOP event log entries which were not using the new Win32ErrorToString method. Thanks to Brodie Thiesfield for reporting this.
• Win32ErrorToString now includes a "bEventLog" parameter. When this is TRUE the function is being called to obtain the error which gets displayed in the event log, when FALSE, it is being used to display to the end user or the TRACE window

v1.36 (14 November 2003)

• The location where the message dll for the service is located can now be tweaked at runtime by filling in the CNTService::m_sMessageDll variable. Thanks to Brodie Thiesfield for this update.
• Reviewed all TRACE statements which use a CNTServiceString parameter. Now explicitly casts the CNTServiceString to a LPCTSTR. Thanks to Brodie Thiesfield for this update.
• Added a new CNTService::m_LoggingDetail variable. This in combination with a new method called CNTService::Win32ErrorToString allows more flexible control over how errors are logging to the event log. Thanks to Brodie Thiesfield for suggesting this update.
• command line arguments other than the "-debug" argument are passed through to ServiceMain() when running in debug mode. Thanks to Brodie Thiesfield for suggesting this update.

v1.35 (12 November 2003)

• Now includes a unicode MC file thanks to Brodie Thiesfield. To use this file, simply copy ntserv_msgU.mc over the ntserv_msg.mc file in the TestSrvMsg and modify the custom build step for the mc file in the TestSrvMsg project to include a -u command line option. This file also includes a Japanese translation of the default service event log strings which the sample service uses.

v1.34 (5 October 2003)

• Updated the Visual Studio.Net workspace to remove the "Without Platform SDK" configurations as they are not applicable.

v1.33 (4 October 2003)

• Updated the custom build steps to compile the mc file. Now uses the VC macro "$(InputPath)" instead of "$(InputDir)\$(InputName).mc".
• Removed a number of unreferenced variables level 4 warnings when compiled with VC.Net 2003.
• Provision of a specific workspace (Testsrv for Visual Studio.Net.dsw) which allows the sample service to be compiled cleanly out of the box with Visual Studio.Net 2000 or Visual Studio.Net 2003. The issue is that the format of various build macros such as $(InputDir) has changed from VC 6. Just select File -> Open Project in VS.Net and select "Testsrv for Visual Studio.Net.dsw".

v1.32 (8 September 2003)

• Moved all the defines which the framework requires into a separate header file. Thanks to Dima Polyakov for pointing out a compilation problem which occurred when you did not have the platform SDK installed which necessitated this change.
• Changed the ordering of the command line used to compile the MC file. This avoids a problem as reported by Rodrigo Oliveira Fernandez when using the framework in VC 7
• Fixed a compilation error related to the use of the preprocessor define NTSERV_EXCLUDE_VC6_WINSVC_DEFINES

v1.31 (15 August 2003)

• Optimized the string copying in CEventLogRecord::CEventLogRecord(const EVENTLOGRECORD* pRecord). A bug was reported in this area by Jeroen Walter but it looks like this is a documentation bug in current versions of the MSDN. This structure was defined correctly in some early versions of the MSDN.

v1.30 (3 August 2003)

• Improved the error handling and reporting in CNTService::SetServiceToStatus. Thanks to Jon Pawley for reporting this issue.

v1.29 (22 May 2003)

• Updated the way the sample service's message dll projects integrates the creation of the mc file. For detailed information on how to integrate mc files into Visual Studio, please see the CodeProject article http://www.codeproject.com/useritems/MCTutorial.asp. Please note that I did not follow the suggested settings as exactly outlined in this article as the message file's header file needs to be included into the NT service exe at compile time.

v1.28 (17 May 2003)

• Further tweaks to _ReportStatus to avoid intermittent crashes. See item 1 on 20-09-2002 for detailed info about the issue.
• Removed some unnecessary calls to locking the critical section

v1.27 (8 May 2003)

• Update to the Install and Uninstall methods to return the value from GetLastError(). This is useful for client code as it can be reset before the functions return.
• Command line now supports a /T: param which allows you to specify a timeout to use when doing an uninstall. This timeout is used to specify how long the code will wait if the service needs to be stopped.
• Broke down all the classes into their own modules. This allows you to pull in only the classes you require, if you are not using the main class CNTService.
• Removed all unnecessary TRACE statements throughout the framework as they sometimes reset the value as returned from GetLastError.

v1.26 (12 March 2003)

• Fixed a problem since user code can't call ReportStatus(SERVICE_STOPPED) there is no way to report start-up or shutdown errors via dwWin32ExitCode or dwServiceSpecificExitCode. This has been resolved by adding a new protected function TerminateService to shut down the service in the event of a critical failure. This throws a private exception containing the exit codes which is caught by the framework in _ServiceMain (or the DebugService case of ProcessShellCommand). _ServiceMain then passes the codes on via _ReportStatus. Also since the dwWin32ExitCode and dwServiceSpecificExitCode arguments of ReportStatus can never be used these parameters have now been removed. Thanks to Jon Baggott for these 2 additions.
• Performed some minor tidy ups in the inclusion of header files by the framework

v1.25 (20 November 2002)

• Fixed 3 level 4 warnings when the code is compiled using VC.Net. Thanks to Ed Eichman for spotting this problem.

v1.24 (20 September 2002)

• Fixed an "issue" in calls to ReportStatusToSCM which your service should be calling in your ServiceMain. Specifically calling ReportStatusToSCM(SERVICE_STOPPED) looks like it elicits the behaviour that the SCM forcefully terminates your worker thread. This can cause issues when other code is executed after this call which uses something which is allocated on the worker threads stack. To fix this "issue" (I could not find any documentation on this behaviour) you should remove the single call to ReportStatusToSCM which uses the values "SERVICE_STOPPED" from the bottom of your service's ServiceMain function. To force you to do this, I have changed the name of the function "ReportStatusToSCM" to just "ReportStatus". This will mean that the compiler will force you to examine each call to this function and remove the one call as described above. The class framework now looks after reporting that your service has stopped to the SCM. Thanks to "Jim" for spotting this.

v1.23 (28 August 2002)

• Reviewed all TRACE statements in the code for correctness
• Added a parameter to CNTService::Install to allow the time to wait for the service to stop to be specified
• Added a CNTServiceString parameter to the CNTService::Install and Uninstall methods to return a descriptive errors to callers.
• Addition of a new boolean variable to the CNTService class  to allow service to decide whether it should use GUI or Console calls to display status messages
• CNTService::ProcessShellCommand now displays error messages to the console or via a Message box when errors occur in install, uninstalling, starting, stopping, resuming and pausing the service.

v1.22 (27 August 2002)

• Made more functions virtual to allow greater end user customisation.
• All useful attributes in call to CreateService in CNTService::Install can now be modified without having to derive a custom version of CNTService::Install in your derived class.
• A boolean value is now provided to enable / disable event log integration

v1.21 (27 November 2001)

• Fixed an issue where the class fails to read any key that is read-only. This is a problem since Win2000 defaults access to HKLM for "normal"  users to read-only. Thanks to Hans-Georg Ulrich for spotting this problem.

v1.20 (9 August 2001)

• Updated SetStringArrayIntoRegistry and GetStringArrayIntoRegistry to be consistent with my other class CHKLM v1.11.

v1.19 (18 July 2001)

• Minor update to the sample code demonstrating the class framework.
• Due to VC 6 shipping with a Winsvc.h (The main NT service header file) which includes some but not all of the defines which the class requires you need to define a few preprocessor define to get the code to compile cleanly for your particular setup. Set the top of "ntserv.cpp" for the details.

v1.18 (15 July 2001)

• Fixed a problem when calling CreateService with pathnames which contain embedded spaces.

v1.17 (27 May 2001)

• Added methods to framework to support the new command line options -start, -pause, -continue and -stop. Thanks to Stefan Niemeyer for this great addition.
• Fixed a small issue in the testing of the CEventLogSource class in app.cpp.

v1.16 (16 May 2001)

• Thread protected code to CNTEventLogSource::Report.

v1.15 (8 January 2001)

• Now includes copyright message in the source code and documentation.
• CNTEventLogSource::Report now allows you to specify whether error codes should be displayed in Hex or as decimal
• Sample service sometimes did not display the stop event. This has been remedied by reporting to the event log before we report to the SCM.
• Framework has now been made independent of the need for the latest Platform SDK header files. You can now compile the code in VC 5 without the Platform SDK having to be installed.

v1.14 (21 December 2000)

• Fixed a bug in CNTService::Uninstall() which was causing it to fail sometimes when the service was running.
• Made all the member variables of the CNTService class public but put them down below the "implementation" line ala the way standard MFC classes are declared.
• Added a new overridden version of CNTEventLogSource::Report.

v1.13 (28 July 2000)

• Fixed a project settings bug which was causing the following compiler error "fatal error C1083: Cannot open include file: 'ntserv_msg.h': No such file or directory".

v1.12 (21 June 2000)

• Minor change to a TRACE statement in RegisterCtrlHandler
• RegisterCtrlHandler is called automatically for you now, no need to call it in your derived version of ServiceMain
• Added a BOOL CNTEventLogSource::Report(WORD wType, LPCTSTR lspszString) method
• Fixed a bug where the sample service was not reporting its shutdown status to the SCM correctly.

v1.11 (19 June 2000)

• Added an ASSERT to ReportStatusToSCM for status handle == 0
• Fixed a number of other logic problems in ReportStatusToSCM
• Removed an unnecessary ASSERT in CNTEventLogSource::Report
• Sample service app now uses sound card default sound instead of PC speaker sound

v1.1 (21 May 2000)

• Added 2 new overridden versions of CNTEventLogSource::Report
• Tweaked and set default parameters in CNTService::ReportStatusToSCM following review of the book "Professional NT Services"
• Disallowed accepting any controls when the service is currently processing the same control in ReportStatusToSCM
• Change the ordering of parameters in ReportStatusToSCM. You should review your code to ensure it is correct if you have existing code
• Class framework now by default uses a DLL of the same name for the message file which the NT Event log will look to for mc string entries. This means that you should review your code to ensure it is correct if you have existing code
• CNTEventLogSource::Report now does not bother automatically creating a SID as this should be used for services which do impersonation for clients
• Changed the constructor of CNTEventLog which now takes the values it needs for calling Register
• CNTEventLog::Report methods are now no longer const because of change above.
• SCM database is now locked during installs and uninstalls of the service
• Now supports all the new functionality provided for services under Windows 2000 while preserving binary compatibility with NT 3.x and NT 4 services.
• Framework now requires the presence of the January 2000 platform SDK or later. This is because of point above.
• Changed the prototype of the existing CNTScmService::QueryStatus function.
• Made the typedefs for the enumeration functions private to their respective classes instead of polluting the global name space

v1.07 (10 April 2000)

• Fixed a bug with the calculation of buffer sizes when compiled for UNICODE in CNTEventLogSource::SetStringArrayIntoRegistry

v1.06 (24 January 2000)

• Modified the way the mc file is included into the TestSrv.exe sample service. The mc file is now compiled into an intermediate "ntserv_msg.rc" file which is "#included" into the final rc file "testsrv.rc". This is done so that the "testsrc.rc" file can be edited by the resource designer inside Visual C++. In previous versions of CNTService, if your tried to edit the rc file (which was generated by the MC command line compiler), you would end up corrupting the file. If you are developing your own service using CNTService, then I would suggest you take this approach. What you need to do is create a resource script inside VC++, adding whatever resources you want to be in your services resources (e.g. version info's, strings etc), then bring up the resource includes dialog and modify the "Compile-Time directives" to "#include "ntserv_msg.rc" or your version of rc file which was generated by MC by compiling your .mc file. You should also check out the project settings in the demo service provided with CNTService to see how it handles compilation of the .mc file via a batch file (right mouse click on "ntserv_msg.mc" and select settings).

v1.05 (10 October 1999)

• Added support for the description field which services can have on Windows 2000.
• Added accessor functions for the service name, friendly name and the description text.

v1.04 (5 October 1999)

• Fixed a problem compiling the mc file for release and Unicode build configurations.
• Fixed a level 4 warning when built using VC++ 6.

v1.03 (3 October 1999)

• Addition of GetProfileStringArray, WriteProfileStringArray, GetProfileBinary and WriteProfileBinary methods to the CNTService class.
• Renamed some module names.

v1.02 (5 September 1999)

• Addition of more ASSERT's statements to aid in debugging.

v1.01 (17 May 1999)

• Addition of a number of ASSERT's statements to aid in debugging.
• Fixed a bug in CNTEventLogSource::Report as reported by Marin Kunev
• Fixed a compiler warning when compiled with VC 6.

24 August 1998

• Minor update to the demo program (app.cpp) to get rid of a compiler error.

v1.0 (17 July 1998)

• Initial public release.

Class Framework Reference

The framework consists of the following classes:

CNTServiceCommandLineInfo
CNTEventLogSource
CNTService
CNTScmService
CNTServiceControlManager
CEventLogRecord
CNTEventLog

CNTServiceCommandLineInfo

The CNTServiceCommandLineInfo class aids in parsing the command line at application start-up. It is based almost exactly upon the way that the  CCommandLineInfo class in MFC works.

A service application will typically create a local instance of this class in your main/wmain or InitInstance function. This object is then passed to CNTService::ParseCommandLine, which fills the CNTServiceCommandLineInfo object. The CNTServiceCommandLineInfo object is then passed to CNTService::ProcessShellCommand to handle the command-line arguments and flags.

You can use this object to encapsulate the following command-line options and parameters:

Derive a new class from CCommandLineInfo to handle other flags and parameter values.

Please note that Install / Uninstall support via the CNTServiceCommandLineInfo class and the framework in general is considered self-registration. Installation best practices for Windows says that you should use the declarative approach provided by Windows Installer to install / uninstall your service. Please pick the MSI approach if you can.

CNTEventLogSource

CNTEventLogSource provides a wrapper class for writing events to the NT event log. You could consider this as the server side to the Event log APIs. Please note that CNTEventLogSource class uses the pre Vista API's for writing to the Windows Event Log. If you are targetting Windows Vista or later, then you should use the new APIs documented at https://msdn.microsoft.com/en-us/library/windows/desktop/aa385772%28v=vs.85%29.aspx. All that is required to support the new Vista API's is to generate an XML manifest file with your event log entries and then pass this file through the MC.exe SDK utility and a header file will be generated with inline code which you can call to write your event log entries without the need for any support classes.

Functions this class provides include:

CNTEventLogSource
~CNTEventLogSource
operator HANDLE
Attach
Detach
Register
Report
Deregister
Install
Uninstall

CNTEventLogSource::CNTEventLogSource

CNTEventLogSource();

CNTEventLogSource(LPCTSTR pUNCServerName, LPCTSTR pSourceName);

Remarks

This is the constructor which just initializes all internal variables to a safe state.

See Also ~CNTEventLogSource

CNTEventLogSource::~CNTEventLogSource

~CNTEventLogSource();

Remarks

This is the standard destructor for the class. Internally it will call Deregister to ensure that any handle that is opened by this instance is closed

See Also
CNTEventLogSource Deregister

CNTEventLogSource::operator HANDLE

operator HANDLE() const;

Return Value:

The underlying SDK handle representing this event log source.

Remarks

This function exposes the underlying handle which the CNTEventLogSource class wraps. This function is provided for integration with legacy code which uses the handle directly

CNTEventLogSource::Attach

void Attach(HANDLE hEventSource);

Parameters

hEventSource An SDK event log source handle returned from ::RegisterEventSource

Remarks

Use this member function to attach an existing SDK handle to a CNTEventLogSource.

See Also
Detach

CNTEvenLogSource::Detach

HANDLE Detach();

Return Value

The SDK event log source handle

Remarks

Call this function to detach m_hEventLogSource from the CNTEventLogSource object and  set m_hEventLogSource to nullptr.

See Also
Attach

CNTEventLogSource::Register

BOOL Register(LPCTSTR pUNCServerName, LPCTSTR pSourceName);

Return Value

TRUE if the function was successful, otherwise FALSE. To get extended error information, call GetLastError

Parameters

pUNCServerName Pointer to a null-terminated string that specifies the Universal Naming Convention (UNC) name of the server on which this operation is to be performed. If this parameter is nullptr, the operation is performed on the local computer.

pSourceName Pointer to a null-terminated string that specifies the name of the source referenced by the returned handle. The source name must be a sub key of a log file entry under the EventLog key in the registry. For example, "WinApp" is a valid source name if the registry has the following key:

HKEY_LOCAL_MACHINE
  System
    CurrentControlSet
      Services
        EventLog
          Application
            WinApp
          Security
          System
Remarks

Use this function to register a source of logging into the event log. Internally the CNTService class contains a member variable (m_EventLogSource) of type CNTEventLogSource which calls this function in its construction.

See Also
Deregister

CNTEventLogSource::Report

BOOL Report(WORD wType, WORD wCategory, DWORD dwEventID, PSID pUserSid, WORD wNumStrings, DWORD dwDataSize, LPCTSTR* pStrings, LPVOID pRawData) const;

BOOL Report(WORD wType, DWORD dwEventID);

BOOL Report(WORD wType, DWORD dwEventID, LPCTSTR pszString);

BOOL Report(WORD wType, DWORD dwEventID, LPCTSTR pszString1, LPCTSTR pszString2);

BOOL Report(WORD wType, DWORD dwEventID, LPCTSTR pszString1, LPCTSTR pszString2, DWORD dwCode, BOOL bReportAsHex = TRUE);

BOOL Report(WORD wType, DWORD dwEventID, LPCTSTR pszString, DWORD dwCode, BOOL bReportAsHex = TRUE);

BOOL Report(WORD wType, DWORD dwEventID, DWORD dwCode, BOOL bReportAsHex = TRUE);

Return Value

TRUE if the function was successful, otherwise FALSE. To get extended error information, call GetLastError

Parameters

wType Specifies the type of event being logged.

wCategory Specifies the event category. This is source-specific information; the category can have any value.

dwEventID Specifies the event. The event identifier specifies the message that goes with this event as an entry in the message file associated with the event source.

pUserSid Pointer to the current user's security identifier. This parameter can be nullptr if the security identifier is not required.

wNumStrings Specifies the number of strings in the array pointed to by the lpStrings parameter. A value of zero indicates that no strings are present.

dwDataSize Specifies the number of bytes of event-specific raw (binary) data to write to the log. If this parameter is zero, no event-specific data is present.

pStrings Pointer to a buffer containing an array of null-terminated strings that are merged into the message from the message file before Event Viewer displays the string to the user. This parameter must be a valid pointer (or nullptr), even if wNumStrings is zero.

pRawData Pointer to the buffer containing the binary data. This parameter must be a valid pointer (or nullptr), even if the dwDataSize parameter is zero.

pszString, pszString1, pszString2 Specifies a single string which will be merged into the message from the message file before Event Viewer displays the string to the user.

dwCode A DWORD value to be put into the event log. Internally the code will convert it to an appropriate string representation.

bReportAsHex Whether or not "dwCode" should be displayed as a hex representation or decimal.

Remarks

These 7 versions of Report, report a message to the event log. The versions are provided to allow the programmer to use the one most suitable for the particular situation at hand.

CNTEventLogSource::Deregister

BOOL Deregister();

Return Value

TRUE if the function was successful, otherwise FALSE. To get extended error information, call GetLastError

Remarks

Call this function to close the handle to the event log. This function will be called in the destructor in case you forget to close the handle yourself.

See Also
Register

CNTEventLogSource::Install

static bool Install(LPCTSTR pszLogName, LPCTSTR pSourceName, LPCTSTR pEventMessageFile, LPCTSTR pszEventCategoryMessageFile, LPCTSTR pszParameterMessageFile, DWORD dwTypesSupported, DWORD dwCategoryCount);

static bool Install(LPCTSTR pSourceName, LPCTSTR pEventMessageFile, LPCTSTR pszEventCategoryMessageFile, LPCTSTR pszParameterMessageFile, DWORD dwTypesSupported, DWORD dwCategoryCount);

Return Value

true if the function was successful, otherwise false. To get extended error information, call GetLastError

Parameters

pszLogName The name of the event log to install to. Normally you would use "Application".

pSourceName The name of the service which you want to install an event log source as.

pEventMessageFile The location of the binary where the Message table resource can be located. This can be a standard exe or dll.

pEventCategoryMessageFile Path to the category message file. A category message file contains language-dependent strings that describe the categories.

pEventParameterMessageFile Path to the parameter message file. A parameter message file contains language-independent strings that are to be inserted into the event description strings. This value can be of type REG_SZ or REG_EXPAND_SZ.

dwTypesSupported Specifies a bitmask of supported types.

dwCategoryCount Number of event categories supported

Remarks

Call this function to setup the necessary entries in the registry so that the Event Viewer can correctly locate the message file for messages displayed in the event log. This function is called as part of CNTService::Install using appropriate values.

See Also
Uninstall

CNTEventLogSource::Uninstall

static bool Uninstall(LPCTSTR pSourceName);

Return Value

true if the function was successful, otherwise false. To get extended error information, call GetLastError

Remarks

Call this function to remove the entries from the registry which were setup by the method Install.

See Also
Install

CNTService

CNTService is the class which provides a C++ framework upon which you can develop your own C++ based services. The class makes heavy use of virtual functions which your service class should override.

Functions this class provides include:

CNTService
~CNTService
WriteProfileString
WriteProfileInt
WriteProfileBinary
WriteProfileStringArray
GetProfileString
GetProfileInt
GetProfileBinary
GetProfileStringArray
ParseCommandLine
ProcessShellCommand
ReportStatus
RegisterCtrlHandler
ServiceCtrlHandler
ServiceMain
OnStop
OnPause
OnContinue
OnInterrogate
OnShutdown
OnUserDefinedRequest
OnParamChange
OnHardwareProfileChange
OnPowerEvent
OnNetBindAdd
OnNetBindRemove
OnNetBindEnable
OnNetBindDisable
OnDeviceEvent
Run
Install
Uninstall
Debug
ShowHelp
EnumerateInstances

CNTService::CNTService

CNTService();

CNTService(LPCTSTR pszServiceName, LPCTSTR pszDisplayName, DWORD dwControlsAccepted, LPCTSTR pszDescription = nullptr);

Parameters

pszServiceName Pointer to a null-terminated string that is the internal name of the service.

pszDisplayName Pointer to a null-terminated string that is to be used by user interface programs to identify this service.

dwControlsAccepted Specifies the control codes that the service will accept and process. Any of the standard NT service codes as specified in the Platform SDK can be specified.

pszDescription The textual description of the service. This appears in the new service's MMC snapin in Windows 2000 as the "Description" column. Using this value just means that administrators will see a comment associated with your service. The default value is nullptr which will not insert a description into the registry.

Remarks

This is the standard constructor which initializes a number of internal variables based on the parameters sent in.

See Also
~CNTService

CNTService::~CNTService

~CNTService();

Remarks

Standard destructor for the class

See Also
CNTService

CNTService::WriteProfileString

bool WriteProfileString(LPCTSTR pszSection, LPCTSTR pszEntry, LPCTSTR pszValue);

bool WriteServiceProfileString(LPCTSTR pszService, LPCTSTR pszSection, LPCTSTR pszEntry, LPCTSTR pszValue, BOOL bFlush, DWORD* pLastError);

Return Value

true if successful; otherwise false.

Parameters

pszService Points to a null-terminated string that specifies the service containing the entry.

bFlush Should the setting be flushed to the registry

pLastError If provided this parameter will contain the last error upon return

pszSection Points to a null-terminated string that specifies the section containing the entry. If the section does not exist, it is created. The name of the section is case independent; the string may be any combination of uppercase and lowercase letters.

pszEntry Points to a null-terminated string that contains the entry into which the value is to be written. If the entry does not exist in the specified section, it is created.

pszValue Points to the string to be written. If this parameter is nullptr, the entry specified by the pszEntry parameter is deleted.

Remarks

Call this member function to write the specified string into the registry where Services are meant to store their configuration setting i.e. HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ServiceName\Parameters.

CNTService::WriteProfileInt

bool WriteProfileInt(LPCTSTR pszSection, LPCTSTR pszEntry, int nValue);

bool WriteServiceProfileInt(LPCTSTR pszService, LPCTSTR pszSection, LPCTSTR pszEntry, int nValue, bool bFlush, DWORD* pLastError);

Return Value

TRUE if successful; otherwise FALSE.

Parameters

pszService Points to a null-terminated string that specifies the service containing the entry.

bFlush Should the setting be flushed to the registry

pLastError If provided this parameter will contain the last error upon return

pszSection Points to a null-terminated string that specifies the section containing the entry. If the section does not exist, it is created. The name of the section is case independent; the string may be any combination of uppercase and lowercase letters.

pszEntry Points to a null-terminated string that contains the entry into which the value is to be written. If the entry does not exist in the specified section, it is created.

nValue Contains the value to be written.

Remarks

Call this member function to write the specified value into the registry where Services are meant to store their configuration setting i.e. HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ServiceName\Parameters.

CNTService::WriteProfileBinary

bool WriteProfileBinary(LPCTSTR pszSection, LPCTSTR pszEntry, const BYTE* pData, UINT nBytes);

bool WriteServiceProfileBinary(LPCTSTR pszService, LPCTSTR pszSection, LPCTSTR pszEntry, const BYTE* pData, UINT nBytes, bool bFlush, DWORD* pLastError = nullptr);

Return Value

true if successful; otherwise false.

Parameters

pszService Points to a null-terminated string that specifies the service containing the entry.

bFlush Should the setting be flushed to the registry

pLastError If provided this parameter will contain the last error upon return

pszSection Points to a null-terminated string that specifies the section containing the entry. If the section does not exist, it is created. The name of the section is case independent; the string may be any combination of uppercase and lowercase letters.

pszEntry Points to a null-terminated string that contains the entry into which the value is to be written. If the entry does not exist in the specified section, it is created.

pData Points to the binary data to be written.

nBytes The size of "pData" in bytes.

Remarks

Call this member function to write the specified binary data into the registry where Services are meant to store their configuration setting i.e. HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ServiceName\Parameters.

CNTService::WriteProfileStringArray

bool WriteProfileStringArray(LPCTSTR pszSection, LPCTSTR pszEntry, const CNTServiceStringArray& array);

bool WriteServiceProfileStringArray(LPCTSTR pszService, LPCTSTR pszSection, LPCTSTR pszEntry, const CNTServiceStringArray& array, bool bFlush, DWORD* pLastError = nullptr);

Return Value

true if successful; otherwise false.

Parameters

pszService Points to a null-terminated string that specifies the service containing the entry.

bFlush Should the setting be flushed to the registry

pLastError If provided this parameter will contain the last error upon return

pszSection Points to a null-terminated string that specifies the section containing the entry. If the section does not exist, it is created. The name of the section is case independent; the string may be any combination of uppercase and lowercase letters.

pszEntry Points to a null-terminated string that contains the entry into which the value is to be written. If the entry does not exist in the specified section, it is created.

array The CNTServiceStringArray to be written.

Remarks

Call this member function to write the specified string array into the registry where Services are meant to store their configuration setting i.e. HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ServiceName\Parameters. The value will be stored as a MULTI_SZ string in the registry.

CNTService::GetProfileString

CNTServiceString GetProfileString(LPCTSTR pszSection, LPCTSTR pszEntry, LPCTSTR lpszDefault = nullptr, DWORD* pdwLastError = nullptr);

CNTServiceString GetServiceProfileString(LPCTSTR pszService, LPCTSTR pszSection, LPCTSTR pszEntry, LPCTSTR lpszDefault = nullptr, DWORD* pLastError = nullptr);

Return Value

The return value is the string from the registry or pszDefault if the string cannot be found. The maximum string length supported by the framework is _MAX_PATH. If pszDefault is nullptr, the return value is an empty string.

Parameters

pszService Points to a null-terminated string that specifies the service containing the entry.

bFlush Should the setting be flushed to the registry

pLastError If provided this parameter will contain the last error upon return

pszSection Points to a null-terminated string that specifies the section containing the entry.

pszEntry Points to a null-terminated string that contains the entry whose string is to be retrieved. This value must not be nullptr.

lpszDefault Points to the default string value for the given entry if the entry cannot be found in the registry.

pdwLastError If this value is non-null, then upon return it will contain the value from the function GetLastError. This allows code to distinguish between a default value which is returned because it is actually stored as opposed to returning a default value because some of the registry API's failed.

Remarks

Call this member function to retrieve the string associated with an entry within the specified section in the registry.

CNTService::GetProfileInt

UINT GetProfileInt(LPCTSTR pszSection, LPCTSTR pszEntry, int nDefault, DWORD* pdwLastError = nullptr);

UINT GetServiceProfileInt(LPCTSTR pszService, LPCTSTR pszSection, LPCTSTR pszEntry, int nDefault, DWORD* pLastError = nullptr);

Return Value

The integer value of the string that follows the specified entry if the function is successful. The return value is the value of the nDefault parameter if the function does not find the entry.

Parameters

pszService Points to a null-terminated string that specifies the service containing the entry.

bFlush Should the setting be flushed to the registry

pLastError If provided this parameter will contain the last error upon return

pszSection Points to a null-terminated string that specifies the section containing the entry.

pszEntry Points to a null-terminated string that contains the entry whose value is to be retrieved.

nDefault Specifies the default value to return if the framework cannot find the entry.

pdwLastError If this value is non-null, then upon return it will contain the value from the function GetLastError. This allows code to distinguish between a default value which is returned because it is actually stored as opposed to returning a default value because some of the registry API's failed.

Remarks

Call this member function to retrieve the value of an integer from an entry within a specified section in the registry.

This member function is not case sensitive, so the strings in the pszSection and pszEntry parameters may differ in case.

CNTService::GetProfileBinary

bool GetProfileBinary(LPCTSTR pszSection, LPCTSTR pszEntry, std::vector<BYTE>& data);

bool GetServiceProfileBinary(LPCTSTR pszService, LPCTSTR pszSection, LPCTSTR pszEntry, std::vector<BYTE>& data, DWORD* pLastError = nullptr);

Return Value

true if successful; otherwise false.

Parameters

pszService Points to a null-terminated string that specifies the service containing the entry.

bFlush Should the setting be flushed to the registry

pLastError If provided this parameter will contain the last error upon return

pszSection Points to a null-terminated string that specifies the section containing the entry.

pszEntry Points to a null-terminated string that contains the entry whose binary data is to be retrieved. This value must not be nullptr.

data Upon successful return, this pointer will contain the binary data read from the registry.

Remarks

Call this member function to set a binary value associated with an entry within the specified section in the registry. Internally the data is stored in the registry as a REG_BINARY value. Note that the caller of the function is responsible for freeing the memory associated with the data in "ppData". This can be achieved using: "delete [] *ppData".

CNTService::GetProfileStringArray

bool GetProfileStringArray(LPCTSTR pszSection, LPCTSTR pszEntry, CNTServiceStringArray& array);

bool GetServiceProfileStringArray(LPCTSTR pszService, LPCTSTR pszSection, LPCTSTR pszEntry, CNTServiceStringArray& array, DWORD* pLastError = nullptr);

Return Value

true if successful; otherwise false.

Parameters

pszService Points to a null-terminated string that specifies the service containing the entry.

bFlush Should the setting be flushed to the registry

pLastError If provided this parameter will contain the last error upon return

pszSection Points to a null-terminated string that specifies the section containing the entry.

pszEntry Points to a null-terminated string that contains the entry whose string array is to be retrieved. This value must not be nullptr.

array Upon successful return this will contain the CNTServiceStringArray.

Remarks

Call this member function to retrieve a string array associated with an entry within the specified section in the registry. The value is stored as a MULTI_SZ string in the registry.

CNTService::ParseCommandLine

void ParseCommandLine(CNTServiceCommandLineInfo& rCmdInfo);

Parameters

rCmdInfo A reference to a CNTServiceCommandLineInfo object.

Remarks

Call this member function to parse the command line and send the parameters, one at a time, to CNTServiceCommandLineInfo::ParseParam.

CNTService::ProcessShellCommand

DWORD ProcessShellCommand(CNTServiceCommandLineInfo& rCmdInfo);

Return Value

The Win32 error code if the shell command fails, otherwise ERROR_SUCCESS (0) if successful.

Parameters

rCmdInfo A reference to a CNTServiceCommandLineInfo object.

Remarks

This member function is called by your InitInstance, main or wmain to accept the parameters passed from the CNTServiceCommandLineInfo object identified by rCmdInfo, and perform the indicated action.

The "m_nShellCommand" data member of the CNTServiceCommandLineInfo object is of the following enumerated type, which is defined within the CNTServiceCommandLineInfo class.

enum class ShellCommand 
{
    RunAsService,
    StartTheService,
    PauseService,
    ContinueService,
    StopService,
    InstallService,
    UninstallService,
    DebugService,
    ShowServiceHelp
};

Please note that prior to v1.39, the return value from this function was a BOOL. Please ensure you review your code to make sure it correctly handles this change.

CNTService::ReportStatus

BOOL ReportStatus(DWORD dwCurrentState, std::optional<DWORD> dwCheckPoint = std::optional<DWORD>{}, std::optional<DWORD> dwWaitHint = std::optional<DWORD>{}, std::optional<DWORD> dwControlsAccepted = std::optional<DWORD>{});

BOOL ReportStatus();

Return Value

TRUE if the SCM was notified successfully of this services state otherwise FALSE. To get extended error information, call GetLastError

Parameters

dwCurrentState Indicates the current state of the service.

dwWin32ExitCode Specifies an Win32 error code that the service uses to report an error that occurs when it is starting or stopping. To return an error code specific to the service, the service must set this value to ERROR_SERVICE_SPECIFIC_ERROR to indicate that the dwServiceSpecificExitCode member contains the error code. The service should set this value to NO_ERROR when it is running and on normal termination.

dwServiceSpecificExitCode Specifies a service specific error code that the service returns when an error occurs while the service is starting or stopping. This value is ignored unless the dwWin32ExitCode member is set to ERROR_SERVICE_SPECIFIC_ERROR.

dwCheckPoint Specifies a value that the service increments periodically to report its progress during a lengthy start, stop, pause, or continue operation. For example, the service should increment this value as it completes each step of its initialization when it is starting up. The user interface program that invoked the operation on the service uses this value to track the progress of the service during a lengthy operation. This value is not valid and should be empty when the service does not have a start, stop, pause, or continue operation pending.

dwWaitHint Specifies an estimate of the amount of time, in milliseconds, that the service expects a pending start, stop, pause, or continue operation to take before the service makes its next call to the SetServiceStatus function with either an incremented dwCheckPoint value or a change in dwCurrentState. If the amount of time specified by dwWaitHint passes, and dwCheckPoint has not been incremented, or dwCurrentState has not changed, the service control manager or service control program can assume that an error has occurred.

dwControlsAccepted Specifies the control codes that the service will accept and process. Any of the standard NT service codes as specified in the Platform SDK can be specified. These are the same codes as specified in the CNTService constructor.

Remarks

These two functions report the current state of the service back to the service control manager. The first version uses the parameters specified to report to the SCM. The second version uses the existing state of the service when reporting to the SCM.

CNTService::RegisterCtrlHandler

BOOL RegisterCtrlHandler();

Return Value

TRUE if the Control handler for this service was successfully registered otherwise FALSE. To get extended error information, call GetLastErrorr

Remarks

This function is called automatically for you prior to the framework calling your ServiceMain code, so there is normally no need to call this function yourself. This function setups up the function on which the SCM will callback on when making requests to the service. Internally when a request is made it will be routed to the appropriate virtual function.

See Also
ServiceCtrlHandler

CNTService::ServiceCtrlHandler

DWORD ServiceCtrlHandler(DWORD dwControl, DWORD dwEventType, LPVOID pEventData)

Parameters

dwControl Specifies the requested control code.

dwEventType The type of event that has occurred. pEventData Additional device information, if required

Remarks

This function is called into by the SCM and internally it delegates to the appropriate virtual function. For example if a  SERVICE_CONTROL_STOP request arrives then this function will call the virtual OnStop function. This function will not normally have to be overridden in your derived class. Please bear in mind that this function will be called in the context on the main thread on your service and not the thread in which your service does it main work (its ServiceMain handler).

CNTService::ServiceMain

virtual void WINAPI ServiceMain(DWORD dwArgc, LPTSTR* pszArgv);

Parameters

dwArgc Specifies the number of arguments in the lpszArgv array.

pszArgv Pointer to an array of pointers that point to null-terminated argument strings. The first argument in the array is the name of the service, and subsequent arguments are any strings passed to the service by the process that called the CScmService::Start function to start the service.

Remarks

In your derived class you are responsible for writing your own ServiceMain function for your service

When a service control program requests that a new service run, the SCM starts the service and sends a start request to the control dispatcher. The control dispatcher creates a new thread to execute the ServiceMain function for the service.

The ServiceMain function should perform the following tasks:

1. Perform initialisation. If the execution time of the initialisation code is expected to be very short (less than one second), initialisation can be performed directly in ServiceMain, if not you should report back to the SCM using the state START_PENDING. Check the sample service for the details on how this is done.
2. When initialisation is complete, call SetServiceStatus, specifying the SERVICE_RUNNING state in the SERVICE_STATUS structure.
3. Perform the service tasks, or, if there are no pending tasks, return. Any change in the state of the service warrants a call to ReportStatusToSCM to report new status information.
4. If an error occurs while the service is initializing or running, the service should call ReportStatusToSCM specifying the SERVICE_STOP_PENDING state, if cleanup will be lengthy. Once cleanup is complete, call ReportStatusToSCM from the last thread to terminate, specifying SERVICE_STOPPED in the SERVICE_STATUS structure. Be sure to set the dwServiceSpecificExitCode and dwWin32ExitCode members of the SERVICE_STATUS structure to identify the error.

CNTService::OnStop

virtual void OnStop();

Remarks

This function will be called whenever a SERVICE_CONTROL_STOP request comes in from the SCM. Your derived class should do whatever is necessary to cause your service to stop.

CNTService::OnPause

virtual void OnPause();

Remarks

This function will be called whenever a SERVICE_CONTROL_PAUSE request comes in from the SCM. Your derived class should do whatever is necessary to cause your service to pause.

CNTService::OnContinue

virtual void OnContinue();

Remarks

This function will be called whenever a SERVICE_CONTROL_CONTINUE request comes in from the SCM. Your derived class should do whatever is necessary to cause your service to continue.

CNTService::OnInterrogate

virtual void OnInterrogate();

Remarks

This function will be called whenever a SERVICE_CONTROL_INTERROGATE request comes in from the SCM. The default implementation just calls ReportStatusToSCM to inform the SCM.

CNTService::OnShutdown

virtual void OnShutdown();

Remarks

This function will be called whenever a SERVICE_CONTROL_SHUTDOWN comes in from the SCM.  Your derived class should do whatever is necessary to cause your service to shutdown.

CNTService::OnUserDefinedRequest

virtual void OnUserDefinedRequest(DWORD dwControl);

Remarks

This function will be called whenever a user defined request comes in from the SCM.  Your derived class should do whatever is appropriate for its service. In the example service provided, it simply changes the frequency of beeps emitted by the service.

CNTService::OnParamChange

virtual void OnParamChange();

Remarks

Notifies the service that service-specific startup parameters have changed. The service should reread its startup parameters. This is only called when the service is running on Windows 2000 or later.

CNTService::OnHardwareProfileChange

virtual DWORD OnHardwareProfileChange(DWORD dwEventType, LPVOID pEventData);

Return Value

Parameters

dwEventType this parameter can be one of the following values: DBT_CONFIGCHANGED, DBT_QUERYCHANGECONFIG, or DBT_CONFIGCHANGECANCELED.

pEventData Additional device information, if required. The format of this data depends on the value of dwEventType parameter.

Remarks

Notifies the service that the computer's hardware profile has changed. This is only called when the service is running on Windows 2000 or later.

CNTService::OnPowerEvent

virtual DWORD OnPowerEvent(DWORD dwEventType, LPVOID pEventData);

Return Value

Parameters

dwEventType this parameter can be one of the values specified in the wParam value of the WM_POWERBROADCAST message.

pEventData This data corresponds to the lParam value that applications receive as part of a WM_POWERBROADCAST message.

Remarks

Notifies the service of system power events. This is only called when the service is running on Windows 2000 or later.

CNTService::OnNetBindAdd

virtual void OnNetBindAdd();

Remarks

Notifies a network service that there is a new component for binding. The service should bind to the new component. This is only called when the service is running on Windows 2000 or later.

CNTService::OnNetBindRemove

virtual void OnNetBindRemove();

Remarks

Notifies a network service that a component for binding has been removed. The service should reread its binding information and unbind from the removed component. This is only called when the service is running on Windows 2000 or later.

CNTService::OnNetBindEnable

virtual void OnNetBindEnable();

Remarks

Notifies a network service that a disabled binding has been enabled. The service should reread its binding information and add the new binding. This is only called when the service is running on Windows 2000 or later.

CNTService::OnNetBindDisable

virtual void OnNetBindDisable();

Remarks

Notifies a network service that one of its bindings has been disabled. The service should reread its binding information and remove the binding. This is only called when the service is running on Windows 2000 or later.

CNTService::OnDeviceEvent

virtual DWORD OnDeviceEvent(DWORD dwEventType, LPVOID pEventData);

Return Value

Parameters

dwEventType this parameter can be one of the following values: DBT_DEVICEARRIVAL, DBT_DEVICEREMOVECOMPLETE, DBT_DEVICEQUERYREMOVE, DBT_DEVICEQUERYREMOVEFAILED, DBT_DEVICEREMOVEPENDING, or DBT_CUSTOMEVENT

pEventData This data corresponds to the lParam value that applications receive as part of a WM_DEVICECHANGE message.

Remarks

Notifies the service of device events. The service must register to receive these notifications by using the RegisterDeviceNotification function. This is only called when the service is running on Windows 2000 or later.

CNTService::Run

virtual bool Run();

Remarks

Calling this function will cause a service to start running. Internally it will set up an appropriate SERVICE_TABLE_ENTRY array and call StartServiceCtrlDispatcher to kick of the service. You would normally call this in your main, wmain or InitInstance. If you are using the CNTServiceCommandLineInfo class and ParseCommandLine and ProcessShellCommand member functions of CNTService then there is no need to call this function.

CNTService::Install

virtual bool Install(CNTServiceString& sErrorMsg, DWORD& dwError);

Remarks

This will install a service. Internally it will call into the SCM API to set this service up as an On demand service with no dependencies. It will also install the service so that it can report events to the event log as well as letting Event Viewer filter using the friendly name of the service. This function will be called internally by the CNTServiceCommandLineInfo if "/install" is specified on the command line.

CNTService::Uninstall

virtual bool Uninstall(CNTServiceString& sErrorMsg, DWORD& dwError, DWORD dwTimeToWaitForStop);

Remarks

The is the corollary function of Install and will remove the service from the SCM database and unregister its' event log registry entries. Please bear in mind that once this is done, event viewer will no longer be able to correctly display any messages the service generated while it was installed. the CNTServiceCommandLineInfo if "-uninstall" or "-remove" is specified on the command line.

CNTService::Debug

virtual void Debug();

Remarks

This will run a service without interacting with the SCM, in effect a "debug" or "Application" mode. This helps when testing your application as it will stop the SCM from timing out your service as it is being debugged. Internally this function will just call the ServiceMain function of your class. Remember that in this case your service code will be running in the same thread as the main thread so it may mask problems which only arise when the code is executed as a real service. This function will be called internally by CNTServiceCommandLineInfo if "/debug", /Application or /App is specified on the command line.

CNTService::ShowHelp

virtual void ShowHelp();

Remarks

This function will be called internally by CNTServiceCommandLineInfo if "-help" or "-?" is specified on the command line. It is up to you to either print some message to the console if you are developing a console mode service or display some helpful window if its a GUI app. The sample service simply displays a message using AfxMessageBox as it was developed using the GUI subsystem.

CNTService::EnumerateInstances

virtual bool EnumerateInstances(CNTServiceStringArray& ServiceNames, DWORD& dwError);

Return Value

true if successful; otherwise false.

Parameters

ServiceNames Upon return will contain all the service name instances for this service.

dwError Will contain the last error code upon return.

Remarks

Call this member function to enumerate all instances of the service. This could prove useful where you are writing configuration type applets which configure the settings for all the instances of your installed service.

CNTScmService

CNTScmService is a class which encapsulates a service as returned from the Service Control Manager, in effect a SC_HANDLE. An instance of a CNTScmService is usually acquired by a call to CNTServiceControlManager::Open. Once retrieved the class allows you to control the service, change its configuration and query a service's state.

Functions this class provides include:

CNTScmService
~CNTScmService
Close
operator SC_HANDLE
Attach
Detach
ChangeConfig
Control
Stop
Pause
Continue
Interrogate
Start
QueryStatus
QueryConfig
Create
Delete
EnumDependents
QueryObjectSecurity
SetObjectSecurity
ChangeDescription
QueryDescription
QueryFailureActions
ChangeFailureActions
ChangeDelayAutoStart
QueryDelayAutoStart
ChangeFailureActionsFlag
QueryFailureActionsFlag
ChangeSidType
QuerySidType
ChangeRequiredPrivileges
QueryRequiredPrivileges
ChangePreShutdown
QueryPreShutdown
ChangeTrigger
QueryTrigger
ChangePreferredNode
QueryPreferredNode
NotifyStatusChange
SubscribeChangeNotifications
UnsubscribeChangeNotifications
WaitState

CNTScmService::CNTScmService

CNTScmService();

Remarks

This is the default constructor which just initializes all internal variables to a safe state.

See Also
~CNTScmService

CNTScmService::~CNTScmService

~CNTScmService();

Remarks

This is the standard destructor for the class. Internally it will call Close to ensure that any handle that is opened by this instance is closed

See Also
CNTScmService Close

CNTScmService::Close

void Close();

Remarks

This frees the SC_HANDLE by internally calling CloseServiceHandle which this class encapsulates.

CNTScmService::operator SC_HANDLE

operator SC_HANDLE() const;

Return Value:

The underlying SDK service handle representing this class.

Remarks

This function exposes the underlying handle which the CNTScmService class wraps. This function is provided for integration with legacy code which uses the handle directly.

CNTScmService::Attach

void Attach(SC_HANDLE hService);

Parameters

hService An SDK service handle returned from SDK calls to the SCM APIs

Remarks

Use this member function to attach an existing SDK handle to a CNTScmService.

See Also
Detach

CNTScmService::Detach

SC_HANDLE Detach();

Return Value

The SDK service handle

Remarks

Call this function to detach m_hService from the CNTScmService object and  set m_hService to nullptr.

See Also
Attach

CNTScmService::ChangeConfig

BOOL ChangeConfig(DWORD dwServiceType, DWORD dwStartType, DWORD dwErrorControl, LPCTSTR pBinaryPathName, LPCTSTR pLoadOrderGroup, LPDWORD pdwTagId, LPCTSTR pDependencies, LPCTSTR pServiceStartName, LPCTSTR pPassword, LPCTSTR pDisplayName) const;

Remarks

This is a simple wrapper for the SDK call ChangeServiceConfig. See the SDK for full details on this function.

CNTScmService::Control

BOOL Control(DWORD dwControl);
DWORD Control(DWORD dwControl, DWORD dwInfoLevel, PVOID pControlParams)

Parameters

dwControl Specifies the control code to send to this service.

Remarks

This is a simple wrapper for the SDK call ControlService. The version which has three parameters is a simple wrapper for the SDK call COntrolServiceEX.

CNTScmService::Stop

BOOL Stop() const;

Remarks

This is a simple wrapper for calling Control with the parameter SERVICE_CONTROL_STOP

CNTScmService::Pause

BOOL Pause() const;

Remarks

This is a simple wrapper for calling Control with the parameter SERVICE_CONTROL_PAUSE

CNTScmService::Continue

BOOL Continue() const;

Remarks

This is a simple wrapper for calling Control with the parameter SERVICE_CONTROL_CONTINUE

CNTScmService::Interrogate

BOOL Interrogate() const;

Remarks

This is a simple wrapper for calling Control with the parameter SERVICE_CONTROL_INTERROGATE

CNTScmService::Start

BOOL Start(DWORD dwNumServiceArgs, LPCTSTR* pServiceArgVectors) const;

Parameters

dwNumServiceArgs Specifies the number of argument strings in the lpServiceArgVectors array. If lpServiceArgVectors is nullptr, this parameter can be zero.

pServiceArgVectors Pointer to an array of pointers that point to null-terminated argument strings passed to a service. Driver services do not receive these arguments. If no arguments are passed to the service being started, this parameter can be nullptr.

Return Values

TRUE If the function succeeds otherwise FALSE. To get extended error information, call GetLastError.

Remarks

Starts this service with the specified parameters.

CNTScmService::QueryStatus

BOOL QueryStatus(SERVICE_STATUS& ServiceStatus) const;

BOOL QueryStatus(SERVICE_STATUS_PROCESS& ssp) const;

Parameters

ServiceStatus Upon a successful return from this function, ServiceStatus will contain the current status of this service.

ssp Upon a successful return from this function, ssp will contain detailed info about the current status of this service.

Return Values

TRUE If the function succeeds otherwise FALSE. To get extended error information, call GetLastError.

Remarks

Queries this service for its current status. The overridden version which takes a SERVICE_STATUS_PROCESS structure is only available on Windows 2000.

CNTScmService::QueryConfig

BOOL QueryConfig(CNTServiceConfig& config) const;

Parameters

config Upon a successful return from this function, this will contain the current configuration of this service accessible via an operator LPQUERY_SERVICE_CONFIG() method.

Return Values

TRUE If the function succeeds otherwise FALSE. To get extended error information, call GetLastError.

Remarks

Queries this service for its current configuration.

CNTScmService::Create

BOOL Create(CNTServiceControlManager& Manager, LPCTSTR pServiceName, LPCTSTR pDisplayName, DWORD dwDesiredAccess, DWORD dwServiceType, DWORD dwStartType, DWORD dwErrorControl, LPCTSTR pBinaryPathName, LPCTSTR pLoadOrderGroup, LPDWORD pdwTagId, LPCTSTR pDependencies, LPCTSTR pServiceStartName, LPCTSTR pPassword);

Remarks

This is a simple wrapper for the SDK call CreateService. See the SDK for full details on this function.

CNTScmService::Delete

BOOL Delete() const;

Remarks

This is a simple wrapper for the SDK call DeleteService. See the SDK for full details on this function.

CNTScmService::EnumDependents

BOOL EnumDependents(DWORD dwServiceState, DWORD dwUserData, ENUM_SERVICES_PROC pEnumServicesFunc) const;

Parameters

dwServiceState Specifies the services to enumerate based on their running state.

dwUserData Any user defined DWORD which you want to send to the callback function.

pEnumServicesFunc pointer to a callback function to use to enumerate the dependent services

Remarks

This function allows you to enumerate the services upon which this service is dependent. Internally this calls EnumDependentServices and calls the callback function for each service. The format of the callback function is:

BOOL CALLBACK ENUM_SERVICES_PROC(DWORD dwData, ENUM_SERVICE_STATUS& ServiceStatus);

dwData This is the value as send into the Enumeration function

ServiceStatus Contains the information related to the enumerated service. See the SDK documentation for further details.

Return TRUE from the function to continue enumeration and FALSE to stop enumeration

CNTScmService::QueryObjectSecurity

BOOL QueryObjectSecurity(SECURITY_INFORMATION dwSecurityInformation, CNTServiceSecurityDescriptor& securityDescriptor) const;

Remarks

This is a simple wrapper for the SDK call QueryServiceObjectSecurity. See the SDK for full details on this function.

CNTScmService::SetObjectSecurity

BOOL SetObjectSecurity(SECURITY_INFORMATION dwSecurityInformation, PSECURITY_DESCRIPTOR& pSecurityDescriptor) const;

Remarks

This is a simple wrapper for the SDK call SetServiceObjectSecurity. See the SDK for full details on this function. Bear in mind that since the PSECURITY_DESCRIPTOR is a variable sized structure, internally this function will allocate the required memory for pSecurityDescriptor, It is the responsibility of the client to delete this structure. This can be done as follows:

PSECURITY_DESCRIPTOR pDescriptor = nullptr;
service.QueryObjectSecurity(whatever, pDescriptor);
delete [] reinterpret_cast<BYTE*>(pDescriptor);

CNTScmService::ChangeDescription

BOOL ChangeDescription(const CNTServiceString& sDescription);

Remarks

This is a simple wrapper for the SDK call ChangeServiceConfig2 using the info level SERVICE_CONFIG_DESCRIPTION. See the SDK for full details on this function.

CNTScmService::QueryDescription

BOOL QueryDescription(CNTServiceString& sDescription) const;

Remarks

This is a simple wrapper for the SDK call QueryServiceConfig2 using the info level SERVICE_CONFIG_DESCRIPTION. See the SDK for full details on this function.

CNTScmService::ChangeFailureActions

BOOL ChangeFailureActions(LPSERVICE_FAILURE_ACTIONS* pFailureActions);

Remarks

This is a simple wrapper for the SDK call ChangeServiceConfig2 using the info level SERVICE_CONFIG_FAILURE_ACTIONS. See the SDK for full details on this function.

CNTScmService::QueryFailureActions

BOOL QueryFailureActions(CNTServiceFailureActions& actions) const;

Remarks

This is a simple wrapper for the SDK call QueryServiceConfig2 using the info level SERVICE_CONFIG_FAILURE_ACTIONS. See the SDK for full details on this function.

CNTScmService::ChangeDelayAutoStart

BOOL ChangeDelayAutoStart(BOOL bDelayedAutoStart) const;

Remarks

This is a simple wrapper for the SDK call ChangeServiceConfig2 using the info level SERVICE_CONFIG_DELAYED_AUTO_START_INFO. See the SDK for full details on this function.

CNTScmService::QueryDelayAutoStart

BOOL QueryDelayAutoStart(BOOL& bDelayedAutoStart) const;

Remarks

This is a simple wrapper for the SDK call QueryServiceConfig2 using the info level SERVICE_CONFIG_DELAYED_AUTO_START_INFO. See the SDK for full details on this function.

CNTScmService::ChangeFailureActionsFlag

BOOL ChangeFailureActionsFlag(BOOL bFailureActionsOnNonCrashFailure) const;

Remarks

This is a simple wrapper for the SDK call ChangeServiceConfig2 using the info level SERVICE_CONFIG_FAILURE_ACTIONS_FLAG. See the SDK for full details on this function.

CNTScmService::QueryFailureActionsFlag

BOOL QueryFailureActionsFlag(BOOL& bFailureActionsOnNonCrashFailure) const;

Remarks

This is a simple wrapper for the SDK call QueryServiceConfig2 using the info level SERVICE_CONFIG_FAILURE_ACTIONS_FLAG . See the SDK for full details on this function.

CNTScmService::ChangeSidType

BOOL ChangeSidType(DWORD dwServiceSidType) const;

Remarks

This is a simple wrapper for the SDK call ChangeServiceConfig2 using the info level SERVICE_CONFIG_SERVICE_SID_INFO. See the SDK for full details on this function.

CNTScmService::QuerySidType

BOOL QuerySidType(DWORD& dwServiceSidtype) const;

Remarks

This is a simple wrapper for the SDK call QueryServiceConfig2 using the info level SERVICE_CONFIG_SERVICE_SID_INFO. See the SDK for full details on this function.

CNTScmService::ChangeRequiredPrivileges

BOOL ChangeRequiredPrivileges(const CNTServiceStringArray& privileges) const;

Remarks

This is a simple wrapper for the SDK call ChangeServiceConfig2 using the info level SERVICE_CONFIG_REQUIRED_PRIVILEGES_INFO. See the SDK for full details on this function.

CNTScmService::QueryRequiredPrivileges

BOOL QueryRequiredPrivileges(CNTServiceStringArray& dwServiceSidtype) const;

Remarks

This is a simple wrapper for the SDK call QueryServiceConfig2 using the info level SERVICE_CONFIG_REQUIRED_PRIVILEGES_INFO. See the SDK for full details on this function.

CNTScmService::ChangePreShutdown

BOOL ChangePreShutdown(DWORD dwPreShutdownTimeout) const;

Remarks

This is a simple wrapper for the SDK call ChangeServiceConfig2 using the info level SERVICE_CONFIG_PRESHUTDOWN_INFO. See the SDK for full details on this function.

CNTScmService::QueryPreShutdown

BOOL QueryPreShutdown(DWORD& dwPreShutdownTimeout) const;

Remarks

This is a simple wrapper for the SDK call QueryServiceConfig2 using the info level SERVICE_CONFIG_PRESHUTDOWN_INFO. See the SDK for full details on this function.

CNTScmService::ChangeTrigger

BOOL ChangeTrigger(PSERVICE_TRIGGER_INFO* pTriggerInfo);

Remarks

This is a simple wrapper for the SDK call ChangeServiceConfig2 using the info level SERVICE_CONFIG_TRIGGER_INFO. See the SDK for full details on this function.

CNTScmService::QueryTrigger

BOOL QueryTrigger(CNTServiceTriggerInfo& triggerInfo) const;

Remarks

This is a simple wrapper for the SDK call QueryServiceConfig2 using the info level SERVICE_CONFIG_TRIGGER_INFO. See the SDK for full details on this function.

CNTScmService::ChangePreferredNode

BOOL ChangePreferredNode(USHORT usPreferredNode, BOOL bDelete) const;

Remarks

This is a simple wrapper for the SDK call ChangeServiceConfig2 using the info level SERVICE_CONFIG_PREFERRED_NODE. See the SDK for full details on this function.

CNTScmService::QueryPreferredNode

BOOL QueryPreShutdown(USHORT& usPrefrredNode, BOOL& bDelete) const;

Remarks

This is a simple wrapper for the SDK call QueryServiceConfig2 using the info level SERVICE_CONFIG_PREFERRED_NODE. See the SDK for full details on this function.

CNTScmService::NotifyStatusChange

BOOL NotifyStatusChange(DWORD udwNotifyMask, BPSERVICE_NOTIFY pNotifyBuffer) const;

Remarks

This is a simple wrapper for the SDK call NotifyServiceStatusChange. See the SDK for full details on this function.

CNTScmService::SubscribeChangeNotifications

DWORD SubscribeServiceChangeNotifications(SC_EVENT_TYPE eEventType, PSC_NOTIFICATION_CALLBACK pCallback, PVOID pCallbackContext, PSC_NOTIFICATION_REGISTRATION* pSubscription) const;

Remarks

This is a simple wrapper for the SDK call SubscribeServiceChangeNotifications. See the SDK for full details on this function.

CNTScmService::UnsubscribeChangeNotifications

BOOL UnsubscribeChangeNotifications(PSC_NOTIFICATION_REGISTRATION pSubscription) const;

Remarks

This is a simple wrapper for the SDK call UnsubscribeServiceChangeNotifications. See the SDK for full details on this function.

CNTScmService::WaitStatus

BOOL WaitStatus(DWORD dwNotify, DWORD dwTimeout, HANDLE hCancelEvent) const;

Remarks

This is a simple wrapper for the SDK call WaitServiceStatus. See the SDK for full details on this function.

CNTServiceControlManager

CNTServiceControlManager is a class which encapsulates a connection to a Service Control Manager (SCM) on some machine. Functionality provided includes enumeration, database locking and service access.

Functions this class provides include:

CNTServiceControlManager
~CNTServiceControlManager
operator HANDLE
Attach
Detach
Open
Close
QueryLockStatus
EnumServices
OpenService
Lock
Unlock

CNTServiceControlManager::CNTServiceControlManager

CNTServiceControlManager();

Remarks

This is the default constructor which just initializes all internal variables to a safe state.

See Also
~CNTServiceControlManager

CNTServiceControlManager::~CNTServiceControlManager

~CNTServiceControlManager();

Remarks

This is the standard destructor for the class. Internally it will call Close to ensure that any handle that is opened by this instance is closed

See Also
Close

CNTServiceControlManager::operator HANDLE

operator SC_HANDLE() const;

Return Value:

The underlying SDK service handle representing this class.

Remarks

This function exposes the underlying handle which the CNTServiceControlManager class wraps. This function is provided for integration with legacy code which uses the handle directly.

CNTServiceControlManager::Attach

void Attach(SC_HANDLE hSCM);

Parameters

hSCM An SDK service control manager handle returned from SDK calls to the SCM APIs

Remarks

Use this member function to attach an existing SDK handle to a CNTServiceControlManager.

See Also
Detach

CNTServiceControlManager::Detach

SC_HANDLE Detach();

Return Value

The SDK service control manager handle

Remarks

Call this function to detach m_hSCM from the CNTServiceControlManager object and  set m_hSCM to nullptr.

See Also
Attach

CNTServiceControlManager::Open

BOOL Open(LPCTSTR pszMachineName, DWORD dwDesiredAccess);

Remarks

This is a simple wrapper for the SDK call OpenSCManager. See the SDK for full details on this function.

CNTServiceControlManager::Close

void Close();

Remarks

This frees the SC_HANDLE by internally calling CloseServiceHandle which this class encapsulates.

CNTServiceControlManager::QueryLockStatus

BOOL QueryLockStatus(CNTServiceControlManagerLockStatus& lockStatus) const;

Remarks

This is a simple wrapper for the SDK call QueryServiceLockStatus. See the SDK for full details on this function.

CNTServiceControlManager::EnumServices

BOOL EnumServices(DWORD dwServiceType, DWORD dwServiceState, void* pUserData, ENUM_SERVICES_PROC pEnumServicesFunc) const;

BOOL EnumServices(DWORD dwServiceType, DWORD dwServiceState, LPCTSTR pszGroupName, void* pUserData, ENUM_SERVICES_PROC2 pEnumServicesFunc) const;

Parameters

dwServiceType Specifies the type of services to enumerate.

dwServiceState Specifies the services to enumerate based on their running state.

pUserData Any user defined void* which you want to send to the callback function.

pszGroupName Specifies a load-order group name. If this parameter is a string, the only services enumerated are those that belong to the group that has the name specified by the string. If this parameter is an empty string, only services that do not belong to any group are enumerated. If this parameter is nullptr, group membership is ignored and all services are enumerated.

pEnumServicesFunc pointer to a callback function to use to enumerate the dependent services

Remarks

This function allows you to enumerate the services which in the SCM. Internally this calls EnumServicesStatus or (EnumServicesStatusEx) and calls the callback function for each service. The format of the callback functions are:

typedef BOOL CALLBACK ENUM_SERVICES_PROC(void* pData, const ENUM_SERVICE_STATUS& ServiceStatus);

typedef BOOL CALLBACK ENUM_SERVICES_PROC2(void* pData, const ENUM_SERVICE_STATUS_PROCESS& ssp);

pData This is the value as send into the enumeration function

ServiceStatus Contains the information related to the enumerated service. See the SDK documentation for further details.

ssp Contains the information related to the enumerated service. See the SDK documentation for further details.

Return TRUE from the function to continue enumeration and FALSE to stop enumeration

CNTServiceControlManager::OpenService

BOOL OpenService(LPCTSTR pServiceName, DWORD dwDesiredAccess, CNTScmService& service) const;

Remarks

This is a simple wrapper for the SDK call of the same name. See the SDK for full details on this function.

CNTServiceControlManager::Lock

BOOL Lock();

Remarks

This is a simple wrapper for the SDK call LockServiceDatabase. See the SDK for full details on this function.

CNTServiceControlManager::Unlock

BOOL Unlock();

Remarks

This is a simple wrapper for the SDK call UnlockServiceDatabase. See the SDK for full details on this function.

CEventLogRecord

CEventLogRecord is a C++ wrapper class for the EVENTLOGRECORD structure as provided in the SDK. For anyone who has had to use this class using raw SDK calls, you will appreciate the easier access which the class provides.

Functions and members this class provides include:

CEventLogRecord
operator=
m_dwRecordNumber
m_dwTimeGenerated
m_dwTimeWritten
m_dwEventID
m_wEventTypes
m_wEventCategory
m_UserSID
m_Strings
m_Data
m_sSourceName
m_sComputerName

CEventLogRecord::CEventLogRecord

CEventLogRecord();

CEventLogRecord(const CEventLogRecord& record);

CEventLogRecord(const EVENTLOGRECORD* pRecord);

Parameters

record An existing CEventLogRecord

pRecord An existing SDK EVENTLOGRECORD structure

CEventLogRecord::operator=

CEventLogRecord& operator=(const CEventLogRecord& record);

Remarks

The standard copy constructor

CEventLogRecord::m_dwRecordNumber

DWORD m_dwRecordNumber;

Remarks

Contains the record number for this event log entry

CEventLogRecord::m_dwTimeGenerated

DWORD m_dwTimeGenerated;

Remarks

The number of seconds since 1/1/1970 UCT since this entry was submitted.

CEventLogRecord::m_dwTimeWritten

DWORD m_TimeWritten;

Remarks

The number of seconds since 1/1/1970 UCT since this entry was written to the event log.

CEventLogRecord::m_dwEventID

DWORD m_dwEventID;

Remarks

Specifies the event. This is specific to the source that generated the event log entry, and is used, together with SourceName, to identify a message in a message file that is presented to the user while viewing the log.

CEventLogRecord::m_wEventTypes

WORD m_wEventType;

Remarks

Specifies the type of event.

CEventLogRecord::m_wEventCategory

WORD m_wEventCategory;

Remarks

Specifies a subcategory for this event. This subcategory is source specific.

CEventLogRecord::m_UserSID

std::vector<BYTE> m_UserSID;

Remarks

A byte array representation of the security identifier of the active user at the time this event was logged.

CEventLogRecord::m_Strings

CNTServiceStringArray m_Strings;

Remarks

A CNTServiceStringArray representation of the strings which are merged into the message before it is displayed to the user.

CEventLogRecord::m_Data

std::vector<BYTE> m_Data;

Remarks

A byte array representation of the event-specific information within this event record.

CEventLogRecord::m_sSourceName

CNTServiceString m_sSourceName;

Remarks

Contains the string specifying the name of the source (application, service, driver, subsystem) that generated the entry.

CEventLogRecord::m_sComputerName

CNTServiceString m_sComputerName;

Remarks

Contains the string specifying the name of the computer that generated this event.

CNTEventLog

CNTEventLog is a C++ wrapper class for accessing the NT Event Logs. You can consider this as the client side to the Event Log APIs.

Functions this class provides include:

CNTEventLog
~CNTEventLog
operator HANDLE
Attach
Detach
Open
OpenBackup
OpenApplication
OpenSystem
OpenSecurity
Close
Backup
Clear
GetNumberOfRecords
GetOldestRecord
NotifyChange
ReadNext
ReadPrev
GetFullInformation

CNTEventLog::CNTEventLog

CNTEventLog();

Remarks

This is the default constructor which just initializes all internal variables to a safe state.

See Also
~CNTEventLog

CNTEventLog::~CEventLog

~CNTEventLog();

Remarks

This is the standard destructor for the class. Internally it will call Close to ensure that any handle that is opened by this instance is closed

See Also
Close

CNTEventLog::operator HANDLE

operator HANDLE() const;

Return Value:

The underlying SDK event log handle representing this class.

Remarks

This function exposes the underlying handle which CNTEventLog class wraps. This function is provided for integration with legacy code which uses the handle directly.

CNTEventLog::Attach

void Attach(HANDLE hEventLog);

Parameters

hEventLog An SDK event log handle returned from SDK calls to the Event log APIs

Remarks

Use this member function to attach an existing SDK handle to a CNTEventLog.

See Also
Detach

CNTEventLog::Detach

HANDLE Detach();

Return Value

The SDK event log handle

Remarks

Call this function to detach m_hEventLog from the CNTEventLog object and  set m_hEventLog to nullptr.

See Also
Attach

CNTEventLog::Open

BOOL Open(LPCTSTR pUNCServerName, LPCTSTR pSourceName);

Remarks

This is a simple wrapper for the SDK call OpenEventLog. See the SDK for full details on this function.

CNTEventLog::OpenBackup

BOOL OpenBackup(LPCTSTR pUNCServerName, LPCTSTR pFileName);

Remarks

This is a simple wrapper for the SDK call OpenBackupEventLog. See the SDK for full details on this function.

CNTEventLog::OpenApplication

BOOL OpenApplication(LPCTSTR pUNCServerName);

Remarks

This is a sample wrapper for opening the "Application" event log on the specified computer, Internally it just calls Open with the appropriate string "Application".

CNTEventLog::OpenSystem

BOOL OpenSystem(LPCTSTR pUNCServerName);

Remarks

This is a sample wrapper for opening the "system" event log on the specified computer, Internally it just calls Open with the appropriate string "System".

CNTEventLog::OpenSecurity

BOOL OpenSecurity(LPCTSTR pUNCServerName);

Remarks

This is a sample wrapper for opening the "Security" event log on the specified computer, Internally it just calls Open with the appropriate string "Security".

CNTEventLog::Close

BOOL Close();

Remarks

This frees the HANDLE by internally calling CloseEventLog which this class encapsulates.

CNTEventLog::Backup

BOOL Backup(LPCTSTR pBackupFileName) const;

Remarks

This is a simple wrapper for the SDK call BackupeventLog. See the SDK for full details on this function.

CNTEventLog::Clear

BOOL Clear(LPCTSTR pBackupFileName) const;

Remarks

This is a simple wrapper for the SDK call ClearEventLog. See the SDK for full details on this function.

CNTEventLog::GetNumberOfRecords

BOOL GetNumberOfRecords(DWORD& dwNumberOfRecords) const;

Return Value

TRUE if the function was successful, otherwise FALSE. To get extended error information, call GetLastError

Parameters

dwNumberOfRecords Upon successful return this will contain the number of records in the event log.

Remarks

This is a simple wrapper for the SDK call GetNumberOfEventLogRecords. See the SDK for full details on this function.

CNTEventLog::GetOldestRecord

BOOL GetOldestRecord(DWORD& dwOldestRecord) const;

Return Value

TRUE if the function was successful, otherwise FALSE. To get extended error information, call GetLastError

Parameters

dwOldestRecord Upon successful return this will contain the record number of the oldest record in the event log.

Remarks

This is a simple wrapper for the SDK call GetOldestEventLogRecord. See the SDK for full details on this function.

CNTEventLog::NotifyChange

BOOL NotifyChange(HANDLE hEvent) const;

Remarks

This is a simple wrapper for the SDK call NotifyChangeEventLog. See the SDK for full details on this function.

CNTEventLog::ReadNext

BOOL ReadNext(CEventLogRecord& record) const;

Return Value

TRUE if the function was successful, otherwise FALSE. To get extended error information, call GetLastError

Parameters

record Upon successful return this will contain the next record in the event log

Remarks

Reads the next record in forward chronological order from the event log. When this function returns successfully, the read position is incremented by one ready for the next read to occur.

CNTEventLog::ReadPrev

BOOL ReadPrev(CEventLogRecord& record) const;

Return Value

TRUE if the function was successful, otherwise FALSE. To get extended error information, call GetLastError

Parameters

record Upon successful return this will contain the previous record in the event log

Remarks

Reads the next record in reverse chronological order from the event log. When this function returns successfully, the read position is decremented by one ready for the next read to occur.

CNTEventLog::GetFullInformation

BOOL GetFullInformation(DWORD& dwFull) const;

Return Value

TRUE if the function was successful, otherwise FALSE. To get extended error information, call GetLastError

Parameters

dwFull Indicates whether the event log is full. If the log is full, this member is TRUE. Otherwise, it is FALSE.

Remarks

This is a simple wrapper for the SDK call GetEventLogInformation using the InfoLevel of EVENTLOG_FULL_INFO. See the SDK for full details on this function.

References

• "Creating a Simple Windows NT Service in C++" by Nigel Thompson on the MSDN.
• The book "Professional NT Services" by Kevin Miller.
• There are numerous articles in the Windows SDK documentation which anyone contemplating writing a service should read. Areas covered include: Writing to the NT Event Log, Reading from the Event Log, How a simple C/SDK style service is structured, the Service Control Manager (SCM), reporting your status back to the SCM, using the message compiler (MC), debugging NT Services etc etc.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
28 March 2024