CNTService
v1.06
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 |
Usage |
History |
Class Framework Reference |
Planned Enhancements |
References |
Contacting the Author |
V1.0 (17 July 1998)
24 August 1998
V1.01 (17 May 1999)
V1.02 (5 September 1999)
V1.03 (3 October 1999)
V1.04 (5 October 1999)
V1.05 (10 October 1999)
V1.06 (24 January 2000)
The framework consists of the following classes:
CNTServiceCommandLineInfo
CNTEventLogSource
CNTService
CNTScmService
CNTServiceControlManager
CEventLogRecord
CNTEventLog
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 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
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
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
BOOL Register(LPCTSTR lpUNCServerName, LPCTSTR lpSourceName);
Return Value
TRUE if the function was successful, otherwise FALSE. To get extended error information, call GetLastError
Parameters
lpUNCServerName 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 NULL, the operation is performed on the local computer.
lpSourceName Pointer to a null-terminated string that specifies the name of the source referenced by the returned handle. The source name must be a subkey of a logfile 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
Remarks
System
CurrentControlSet
Services
EventLog
Application
WinApp
Security
System
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
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.
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
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
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 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(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();
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.
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 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 lpszSection, LPCTSTR lpszEntry, const CStringArray& array);
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.
array The CStringArray 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.
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 whose string is to be retrieved. 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.
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.
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 string array 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.
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
BOOL ProcessShellCommand(CNTServiceCommandLineInfo& rCmdInfo);
Return Value
TRUE if the shell command is processed successfully otherwise FALSE.
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 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, };
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 GetLastErrorr
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);
Parameters
dwControl Specifies the requested control code. This value can be one of the standard control codes in the following table:
Value | Meaning |
---|---|
SERVICE_CONTROL_STOP | Requests the service to stop. |
SERVICE_CONTROL_PAUSE | Requests the service to pause. |
SERVICE_CONTROL_ CONTINUE |
Requests the paused service to resume. |
SERVICE_CONTROL_ INTERROGATE |
Requests the service to update immediately its current status information to the service control manager. |
SERVICE_CONTROL_ SHUTDOWN |
Requests the service to perform cleanup tasks, because the system is shutting down. |
This value can also be a user-defined control code, as described in the following table:
Value | Meaning |
---|---|
Range 128 to 255. | The service defines the action associated with the control code. The hService handle must have SERVICE_USER_DEFINED_CONTROL access. |
.
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).
virtual void WINAPI ServiceMain(DWORD dwArgc, LPTSTR* lpszArgv);
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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();
Remarks
This is the default constructor which just initialises all internal variables to a safe state.
See Also ~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
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.
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
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
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.
BOOL Control(DWORD dwControl);
Parameters
dwControl Specifies the control code to send to this service. This value can be one of the standard control codes in the following table:
Value | Meaning |
---|---|
SERVICE_CONTROL_STOP | Requests the service to stop. |
SERVICE_CONTROL_PAUSE | Requests the service to pause. |
SERVICE_CONTROL_ CONTINUE |
Requests the paused service to resume. |
SERVICE_CONTROL_ INTERROGATE |
Requests the service to update immediately its current status information to the service control manager. |
SERVICE_CONTROL_ SHUTDOWN |
Requests the service to perform cleanup tasks, because the system is shutting down. |
This value can also be a user-defined control code, as described in the following table:
Value | Meaning |
---|---|
Range 128 to 255. | The service defines the action associated with the control code. The hService handle must have SERVICE_USER_DEFINED_CONTROL access. |
Remarks
This is a simple wrapper for the SDK call ControlService SDK Call.
BOOL Stop() const;
Remarks
This is a simple wrapper for calling Control with the parameter SERVICE_CONTROL_STOP
BOOL Pause() const;
Remarks
This is a simple wrapper for calling Control with the parameter SERVICE_CONTROL_PAUSE
BOOL Continue() const;
Remarks
This is a simple wrapper for calling Control with the parameter SERVICE_CONTROL_CONTINUE
BOOL Interrogate() const;
Remarks
This is a simple wrapper for calling Control with the parameter SERVICE_CONTROL_INTERROGATE
BOOL Start(DWORD dwNumServiceArgs, LPCTSTR* lpServiceArgVectors) const;
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.
TRUE If the function succeeds otherwise FALSE. To get extended error information, call GetLastError.
Starts this service with the specified parameters.
BOOL AcceptStop(BOOL& bStop);
Parameters
bStop Upon a successful return from this function, bStop will indicate whether this service can be stopped.
TRUE If the function succeeds otherwise FALSE. To get extended error information, call GetLastError.
Queries this service to determine if this service can currently be stopped.
CNTScmService::AcceptPauseContinue
BOOL AcceptPauseContinue(BOOL& bPauseContinue);
Parameters
bPauseContinue Upon a successful return from this function, bPauseContinue will indicate whether this service can be paused and continued.
TRUE If the function succeeds otherwise FALSE. To get extended error information, call GetLastError.
Queries this service to determine if this service can currently be paused / continued.
BOOL AcceptShutdown(BOOL& bShutdown);
Parameters
bShutdown Upon a successful return from this function, bShutdown will indicate whether this service handles the shutdown request.
TRUE If the function succeeds otherwise FALSE. To get extended error information, call GetLastError.
Queries this service to determine if this service handles the shutdown request.
BOOL QueryStatus(LPSERVICE_STATUS lpServiceStatus) const;
Parameters
lpServiceStatus Upon a successful return from this function, lpServiceStatus will contain the current status of this service.
TRUE If the function succeeds otherwise FALSE. To get extended error information, call GetLastError.
Queries this service for its current status.
BOOL QueryConfig(LPQUERY_SERVICE_CONFIG& lpServiceConfig) const;
Parameters
lpServiceConfig Upon a successful return from this function, lpServiceConfig will contain the current configuration of this service.
TRUE If the function succeeds otherwise FALSE. To get extended error information, call GetLastError.
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;
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.
BOOL Delete() const;
Remarks
This is a simple wrapper for the SDK call DeleteService. See the SDK for full details on this function.
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 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::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 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=(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.
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_wEventCategory
WORD m_wEventCategory;
Remarks
Specifies a subcategory for this event. This subcategory is source specific.
CByteArray m_UserSID;
Remarks
A CByteArray representation of the security identifier of the active user at the time this event was logged.
CStringArray m_Strings;
Remarks
A CStringArray representation of the strings which are merged into the message before it is displayed to the user.
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 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();
Remarks
This is the default constructor which just initialises all internal variables to a safe state.
See Also ~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
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.
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
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
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.
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.
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".
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".
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".
BOOL Close();
Remarks
This frees the HANDLE by internally calling CloseEventLog which this class encapsulates.
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.
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.
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.
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.
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.
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.
PJ Naughter
Email: pjn@indigo.ie
Web: http://indigo.ie/~pjn
24 January 2000