Download source files - 41 Kb
Introduction
Welcome to
CNTService
, a collection of freeware MFC classes which provide a class framework
for developing NT services in MFC.
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 Platform
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 build in MFC
registry / ini functions.
- A simple test service has been provided to help you get started developing your own
NT services.
- Comprehensive documentation is provided for all the classes.
Usage
- Bear in mind that these classes are very NT specific and none of this code will work correctly
on 95/98. Both of these operating systems do provide some support for services but in a
completely incompatible manner with NT services.
- 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 will also need to include the compiled form of ntserv_msg.mc into your service
executable's resource file. For further information on this check on the history details for
v1.06 below.
- To see the class in action, have a look at the code in
InitInstance()
in the module
"app.cpp".
- Your code will need to include MFC either statically or dynamically.
History
V1.0 (17 July 1998)
24 August 1998
- Minor update to the demo program (app.cpp) to get rid of a compiler error.
V1.01 (17 May 1999)
- Addition of a number of ASSERTs 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.
V1.02 (5 September 1999)
- Addition of more ASSERT's statements to aid in debugging.
V1.03 (3 October 1999)
- Addition of
GetProfileStringArray()
,
WriteProfileStringArray()
, GetProfileBinary()
and
WriteProfileBinary()
methods to the CNTService
class.
- Renamed some module names.
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.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.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
#includ
ed 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, 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).
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
startup. 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:
Command-line argument |
Command executed |
app /install |
Installs the service. |
app /remove | /uninstall |
Uninstalls the service. |
app /help |
Calls the virtual CNTService::OnHelp() function. |
Derive a new class from CCommandLineInfo
to handle other flags and parameter values.
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.
Functions this class provides include:
CNTEventLogSource
~CNTEventLogSource
operator HANDLE
Attach
Detach
Register
Report
Deregister
Install
Uninstall
- CNTEventLogSource::CNTEventLogSource
- CNTEventLogSource();
Remarks:
This is the default constructor which just initialises 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
- BOOL Attach(HANDLE hEventSource);
Return Value:
TRUE if the function was successful, otherwise FALSE. To get extended error information, call
GetLastError()
.
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
- CNTEventLogSource::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 NULL.
See Also:
Attach
- CNTEventLogSource::Register
- BOOL Register(LPCTSTR lpUNCServerName, LPCTSTR lpSourceName);
Return Value:
TRUE if the function was successful, otherwise FALSE. To get extended error information, call
GetLastError()
.
Parameters:
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 lpUserSid, WORD wNumStrings, DWORD dwDataSize, LPCTSTR* lpStrings, LPVOID lpRawData) const;
BOOL Report(WORD wType, DWORD dwEventID, LPCTSTR lpszString) const;
BOOL Report(WORD wType, DWORD dwEventID, LPCTSTR lpszString1, LPCTSTR lpszString2) const;
BOOL Report(WORD wType, DWORD dwEventID, DWORD dwCode) const;
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. This parameter can be one of the
following values:
Value |
Meaning |
EVENTLOG_ERROR_TYPE |
Error event |
EVENTLOG_WARNING_TYPE |
Warning event |
EVENTLOG_INFORMATION_TYPE |
Information event |
EVENTLOG_AUDIT_SUCCESS |
Success Audit event |
EVENTLOG_AUDIT_FAILURE |
Failure Audit event |
- 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.
- lpUserSid -- Pointer to the current user's security identifier. This parameter can be NULL
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.
- lpStrings -- 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 NULL), even if wNumStrings is
zero.
- lpRawData -- Pointer to the buffer containing the binary data. This parameter must be a
valid pointer (or NULL), even if the dwDataSize parameter is zero.
- lpszString, lpszString1, lpszString2 -- Specifies a single string which will be merged into
the message from the message file before Event Viewer displays the string to the user.
Remarks:
These 4 versions of Report report a message to the event log. The 4 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 lpSourceName, LPCTSTR lpEventMessageFile, DWORD dwTypesSupported);
Return Value:
TRUE if the function was successful, otherwise FALSE. To get extended error information, call
GetLastError()
.
Parameters:
- lpSourceName -- The name of the service which you want to install an event log source as.
- lpEventMessageFile -- The location of the binary where the Message table resource can be
located. This can be a standard exe or dll.
- dwTypesSupported -- Specifies a bitmask of supported types. It can be one or more of the
following values:
- EVENTLOG_ERROR_TYPE
- EVENTLOG_WARNING_TYPE
- EVENTLOG_INFORMATION_TYPE
- EVENTLOG_AUDIT_SUCCESS
- EVENTLOG_AUDIT_FAILURE
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 lpSourceName);
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
MFC 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
ReportStatustoSCM
RegisterCtrlHandler
ServiceCtrlHandler
ServiceMain
OnStop
OnPause
OnContinue
OnInterrogate
OnShutdown
OnUserDefinedRequest
Run
Install
Uninstall
Debug
ShowHelp
- CNTService::CNTService
- CNTService(LPCTSTR lpszServiceName, LPCTSTR lpszDisplayName, DWORD dwControlsAccepted, LPCTSTR lpszDescription = NULL);
Parameters:
- lpszServiceName -- Pointer to a null-terminated string that is the internal name of the
service.
- lpszDisplayName -- 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 or all of the following flags can be specified to enable the other control codes.
- lpszDescription -- 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 NULL which will not insert a description into the registry.
Value |
Meaning |
SERVICE_ACCEPT_STOP |
The service can be stopped. This enables the SERVICE_CONTROL_STOP value. |
SERVICE_ACCEPT_PAUSE_CONTINUE |
The service can be paused and continued. This enables the SERVICE_CONTROL_PAUSE
and SERVICE_CONTROL_CONTINUE values. |
SERVICE_ACCEPT_SHUTDOWN |
The service is notified when system shutdown occurs. This enables the system to
send a SERVICE_CONTROL_SHUTDOWN value to the service. The ControlService
function cannot send this control code. |
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 lpszSection, LPCTSTR lpszEntry, LPCTSTR lpszValue);
Return Value:
TRUE if successful; otherwise FALSE.
Parameters:
- lpszSection -- 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.
- lpszEntry -- 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.
- lpszValue -- Points to the string to be written. If this parameter is NULL, the entry
specified by the lpszEntry 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 lpszSection, LPCTSTR lpszEntry, int nValue);
Return Value:
TRUE if successful; otherwise FALSE.
Parameters:
- lpszSection -- 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.
- lpszEntry -- 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 lpszSection, LPCTSTR lpszEntry, LPBYTE pData, UINT nBytes);
Return Value:
TRUE if successful; otherwise FALSE.
Parameters:
- lpszSection -- 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.
- lpszEntry -- 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 binart data into the registry where Services are
meant to store their configuration setting i.e.
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ServiceName\Parameters
.
- CNTService::GetProfileString
- CString GetProfileString(LPCTSTR lpszSection, LPCTSTR lpszEntry, LPCTSTR lpszDefault = NULL);
Return Value:
The return value is the string from the registry or lpszDefault if the string cannot be
found. The maximum string length supported by the framework is _MAX_PATH
. If
lpszDefault is NULL, the return value is an empty string.
Parameters:
- lpszSection -- Points to a null-terminated string that specifies the section containing
the entry.
- lpszEntry -- Points to a null-terminated string that contains the entry into which the
value is to be written. This value must not be NULL.
- lpszDefault -- Points to the default string value for the given entry if the entry cannot
be found in the registry.
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 lpszSection, LPCTSTR lpszEntry, int nDefault);
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. The return value is 0 if the value that corresponds to the specified entry is not an
integer.
Parameters:
- lpszSection -- Points to a null-terminated string that specifies the section containing
the entry.
- lpszEntry -- 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.
This value can be an unsigned value in the range 0 through 65,535 or a signed value in the
range -32,768 through 32,767.
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 lpszSection and
lpszEntry parameters may differ in case.
- CNTService::GetProfileBinary
- BOOL GetProfileBinary(LPCTSTR lpszSection, LPCTSTR lpszEntry, LPBYTE* ppData, UINT* pBytes);
Return Value:
TRUE if successful; otherwise FALSE.
Parameters:
- lpszSection -- Points to a null-terminated string that specifies the section containing
the entry.
- lpszEntry -- Points to a null-terminated string that contains the entry whose binary data is
to be retrieved. This value must not be NULL.
- ppData -- Upon successful return, this pointer will contain the binary data read from the
registry.
- nBytes -- Upon successful return, this pointer will contain the size of 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 lpszSection, LPCTSTR lpszEntry, CStringArray& array);
Return Value:
TRUE if successful; otherwise FALSE.
Parameters:
- lpszSection -- Points to a null-terminated string that specifies the section containing
the entry.
- lpszEntry -- Points to a null-terminated string that contains the entry whose binary data is
to be retrieved. This value must not be NULL.
- array -- Upon successful return this will contain the CStringArray.
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:
Remarks:
Call this member function to parse the command line and send the parameters, one at a time, to
CNTServiceCommandLineInfo::ParseParam()
.
- CNTService::ProcessShellCommand
- BOOL ProcessShellCommand(CNTServiceCommandLineInfo& rCmdInfo);
Return Value:
TRUE if the shell command is processed successfully otherwise FALSE.
Parameters:
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 data members of the CNTServiceCommandLineInfo
object, identified by
CNTServiceCommandLineInfo::m_nShellCommand
, are of the following enumerated type, which
is defined within the CNTServiceCommandLineInfo
class.
enum {
RunAsService,
InstallService,
UninstallService,
DebugService,
ShowServiceHelp,
};
- CNTService::ReportStatusToSCM
- BOOL ReportStatusToSCM();
BOOL ReportStatusToSCM(DWORD dwCurrentState, DWORD dwWin32ExitCode, DWORD dwServiceSpecificExitCode, DWORD dwCheckPoint, DWORD dwWaitHint);
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. One of the following values
is specified:
Value |
Meaning |
SERVICE_STOPPED |
The service is not running. |
SERVICE_START_PENDING |
The service is starting. |
SERVICE_STOP_PENDING |
The service is stopping. |
SERVICE_RUNNING |
The service is running. |
SERVICE_CONTINUE_PENDING |
The service continue is pending. |
SERVICE_PAUSE_PENDING |
The service pause is pending. |
SERVICE_PAUSED |
The service is paused. |
- 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 initialisation 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 zero 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.
Remarks:
These two functions report the current state of the service back to the service control manager.
The first versions uses the parameters specified and as well as updated the services own internal
state will report it 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 GetLastError()
.
Remarks:
You would call this at the beginning of your derived classes ServiceMain to report to the SCM which
function to 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
- virtual void WINAPI ServiceCtrlHandler(DWORD dwControl);
Return Value:
TRUE if successful; otherwise FALSE.
Parameters:
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* lpszArgv);
Return Value:
TRUE if successful; otherwise FALSE.
Parameters:
- dwArgc -- Specifies the number of arguments in the lpszArgv array.
- lpszArgv -- 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:
- Call the RegisterServiceCtrlHandler() function
immediately to register a handler function to handle control requests for the service.
- Perform initialization. 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()
.
- When initialization is complete, call
SetServiceStatus()
, specifying the
SERVICE_RUNNING state in the SERVICE_STATUS
structure.
- 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.
- If an error occurs while the service is initializing or running, the service should call,
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::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();
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. In future versions of CNTService
, virtual
functions will be provided to allow more customisation in this area. 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();
Remarks:
The is the corollary function of Install and will remove the service from the SCM database and
remove it 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" 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" 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.
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
AcceptStop
AcceptPauseContinue
AcceptShutdown
QueryStatus
QueryConfig
Create
Delete
EnumDependents
QueryObjectSecurity
SetObjectSecurity
- CNTScmService::CNTScmService
- CNTScmService();
Remarks:
This is the default constructor which just initialises 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
- BOOL Attach(SC_HANDLE hService);
Return Value:
TRUE if the function was successful, otherwise FALSE. To get extended error information, call
GetLastError()
.
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 NULL.
See Also:
Attach.
- CNTScmService::ChangeConfig
- BOOL ChangeConfig(DWORD dwServiceType, DWORD dwStartType, DWORD dwErrorControl, LPCTSTR lpBinaryPathName, LPCTSTR lpLoadOrderGroup, LPDWORD lpdwTagId, LPCTSTR lpDependencies, LPCTSTR lpServiceStartName, LPCTSTR lpPassword, LPCTSTR lpDisplayName) 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);
Parameters:
Remarks:
This is a simple wrapper for the SDK call ControlService()
SDK Call.
- 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* lpServiceArgVectors) const;
Return Value:
TRUE If the function succeeds otherwise FALSE. To get extended error information, call
GetLastError()
.
Parameters:
- dwNumServiceArgs -- Specifies the number of argument strings in the
lpServiceArgVectors array. If lpServiceArgVectors is NULL, this
parameter can be zero.
- lpServiceArgVectors -- 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 NULL.
Remarks:
Starts this service with the specified parameters.
- CNTScmService::AcceptStop
- BOOL AcceptStop(BOOL& bStop);
Return Value:
TRUE If the function succeeds otherwise FALSE. To get extended error information, call
GetLastError()
.
Parameters:
- bStop -- Upon a successful return from this function, bStop will indicate whether this
service can be stopped.
Remarks:
Queries this service to determine if this service can currently be stopped.
- CNTScmService::AcceptPauseContinue
- BOOL AcceptPauseContinue(BOOL& bPauseContinue);
Return Value:
TRUE If the function succeeds otherwise FALSE. To get extended error information, call
GetLastError()
.
Parameters:
- bPauseContinue -- Upon a successful return from this function, bPauseContinue will
indicate whether this service can be paused and continued.
Remarks:
Queries this service to determine if this service can currently be paused / continued.
- CNTScmService::AcceptShutdown
- BOOL AcceptShutdown(BOOL& bShutdown);
Return Value:
TRUE If the function succeeds otherwise FALSE. To get extended error information, call
GetLastError()
.
Parameters:
- bShutdown -- Upon a successful return from this function, bShutdown will indicate
whether this service handles the shutdown request.
Remarks:
Queries this service to determine if this service handles the shutdown request.
- CNTScmService::QueryStatus
- BOOL QueryStatus(LPSERVICE_STATUS lpServiceStatus) const;
Return Value:
TRUE If the function succeeds otherwise FALSE. To get extended error information, call
GetLastError()
.
Parameters:
- lpServiceStatus -- Upon a successful return from this function, lpServiceStatus
will contain the current status of this service.
Remarks:
Queries this service for its current status.
- CNTScmService::QueryConfig
- BOOL QueryConfig(LPQUERY_SERVICE_CONFIG& lpServiceConfig) const;
Return Value:
TRUE If the function succeeds otherwise FALSE. To get extended error information, call
GetLastError()
.
Parameters:
- lpServiceConfig -- Upon a successful return from this function, lpServiceConfig
will contain the current configuration of this service.
Remarks:
Queries this service for its current configuration. Bear in mind that since the QUERY_SERVICE_CONFIG
is a variable sized structure, internally this function will allocate the required memory for
lpServiceConfig, it is the responsibility of the client to delete this structure. This can
be done as follows:
LPQUERY_SERVICE_CONFIG lpConfig = NULL;
service.QueryConfig(lpConfig);
delete [] (BYTE*) lpConfig;
- CNTScmService::Create
- BOOL Create(CNTServiceControlManager& Manager, LPCTSTR lpServiceName, LPCTSTR lpDisplayName, DWORD dwDesiredAccess, DWORD dwServiceType, DWORD dwStartType, DWORD dwErrorControl, LPCTSTR lpBinaryPathName, LPCTSTR lpLoadOrderGroup, LPDWORD lpdwTagId, LPCTSTR lpDependencies, LPCTSTR lpServiceStartName, LPCTSTR lpPassword);
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 lpEnumServicesFunc) const;
Parameters:
- dwServiceState -- Specifies the services to enumerate based on their running state. It must
be one or both of the following values:
Value |
Meaning |
SERVICE_ACTIVE |
Enumerates services that are in the following states:
SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING,
SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING, and SERVICE_PAUSED. |
SERVICE_INACTIVE |
Enumerates services that are in the SERVICE_STOPPED state. |
SERVICE_STATE_ALL |
Combines the following states: SERVICE_ACTIVE and SERVICE_INACTIVE. |
- dwUserData -- Any user defined DWORD which you want to send to the callback function.
- lpEnumServicesFunc -- 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, PSECURITY_DESCRIPTOR& lpSecurityDescriptor) 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& lpSecurityDescriptor) 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 lpSecurityDescriptor,
it is the responsibility of the client to delete this structure. This can be done as follows:
PSECURITY_DESCRIPTOR lpDescriptor = NULL;
service.QueryObjectSecurity(whatever, lpDescriptor);
delete [] (BYTE*) lpDescriptor;
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 initialises 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:
CNTServiceControlManager(), 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
- BOOL Attach(SC_HANDLE hSCM);
Return Value:
TRUE if the function was successful, otherwise FALSE. To get extended error information, call
GetLastError()
.
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 NULL.
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::Close
- void Close();
Remarks:
This frees the SC_HANDLE by internally calling CloseServiceHandle()
which this class
encapsulates.
- CNTServiceControlManager::QueryLockStatus
- BOOL QueryLockStatus(LPQUERY_SERVICE_LOCK_STATUS& lpLockStatus) const;
Remarks:
This is a simple wrapper for the SDK call QueryServiceLockStatus()
. See the SDK for
full details on this function. Bear in mind that since the LPQUERY_SERVICE_LOCK_STATUS is a variable
sized structure, internally this function will allocate the required memory for lpLockStatus,
it is the responsibility of the client to delete this structure. This can be done as follows:
LPQUERY_SERVICE_LOCK_STATUS lpLockStatus = NULL;
scm.QueryLockStatus(lpLockStatus);
delete [] (BYTE*) lpLockStatus;
- CNTServiceControlManager::EnumServices
- BOOL EnumServices(DWORD dwServiceType, DWORD dwServiceState, DWORD dwUserData, ENUM_SERVICES_PROC lpEnumServicesFunc) const;
Parameters:
- dwServiceType -- Specifies the type of services to enumerate. It must be one or both of the
following values:
Value |
Meaning |
SERVICE_WIN32 |
Enumerates services of type SERVICE_WIN32_OWN_PROCESS and
SERVICE_WIN32_SHARE_PROCESS. |
SERVICE_DRIVER |
Enumerates services of type SERVICE_KERNEL_DRIVER and
SERVICE_FILE_SYSTEM_DRIVER. |
- dwServiceState -- Specifies the services to enumerate based on their running state. It must be
one or both of the following values:
Value |
Meaning |
SERVICE_ACTIVE |
Enumerates services that are in the following states: SERVICE_START_PENDING,
SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING,
SERVICE_PAUSE_PENDING, and SERVICE_PAUSED. |
SERVICE_INACTIVE |
Enumerates services that are in the SERVICE_STOPPED state. |
SERVICE_STATE_ALL |
Combines the following states: SERVICE_ACTIVE and SERVICE_INACTIVE. |
- dwUserData -- Any user defined DWORD which you want to send to the callback function.
- lpEnumServicesFunc -- 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()
and calls the callback function for each service. The format of
the callback function is:
typedef 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.
- CNTServiceControlManager::OpenService
- BOOL OpenService(LPCTSTR lpServiceName, 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_TimeGenerated
m_TimeWritten
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_TimeGenerated
- CTime m_TimeGenerated;
Remarks:
The CTime representation of when this entry was submitted.
- CEventLogRecord::m_TimeWritten
- CTime m_TimeWritten;
Remarks:
The CTime representation of when 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. This member can be one of the following values:
Value |
Meaning |
EVENTLOG_ERROR_TYPE |
Error event |
EVENTLOG_WARNING_TYPE |
Warning event |
EVENTLOG_INFORMATION_TYPE |
Information event |
EVENTLOG_AUDIT_SUCCESS |
Success Audit event |
EVENTLOG_AUDIT_FAILURE |
Failure Audit event |
- CEventLogRecord::m_UserSID
- CByteArray m_UserSID;
Remarks:
A CByteArray representation of the security identifier of the active user at the time this event was
logged.
- CEventLogRecord::m_Strings
- CStringArray m_Strings;
Remarks:
A CStringArray representation of the strings which are merged into the message before it is
displayed to the user.
- CEventLogRecord::m_Data
- CByteArray m_Data;
Remarks:
A CByteArray representation of the event-specific information within this event record.
- CEventLogRecord::m_sSourceName
- CString m_sSourceName;
Remarks:
Contains the string specifying the name of the source (application, service, driver, subsystem) that
generated the entry.
- CEventLogRecord::m_sComputerName
- CString 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
- CNTEventLog::CNTEventLog
- CNTEventLog();
Remarks:
This is the default constructor which just initialises all internal variables to a safe state.
See Also:
~CNTEventLog().
- CNTEventLog::~CNTEventLog
- ~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:
CNTEventLog(), 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
- BOOL Attach(HANDLE hEventLog);
Return Value:
TRUE if the function was successful, otherwise FALSE. To get extended error information, call
GetLastError()
.
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 NULL.
See Also:
Attach
- CNTEventLog::Open
- BOOL Open(LPCTSTR lpUNCServerName, LPCTSTR lpSourceName);
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 lpUNCServerName, LPCTSTR lpFileName);
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 lpUNCServerName);
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 lpUNCServerName);
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 lpUNCServerName);
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 lpBackupFileName) 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 lpBackupFileName) 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.
Planned Enhancements
- Review all classes to determine which parameters each member function requires can have default values.
- If you have any suggested improvements, please let me know so that I can incorporate them into the
next release.
References
- "Creating a Simple Windows NT Service in C++" by Nigel Thompson on the MSDN.
- Win32 Foundation
Classes developed by Sam Blackburn.
- There are numerous articles in the Platform SDK 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), etc, etc.
Contacting the Author
PJ Naughter
Email: pjn@indigo.ie
Web: http://www.naughter.com
24 January 2000