Click here to Skip to main content
65,938 articles
CodeProject is changing. Read more.
Articles
(untagged)

CNTService v1.06 - NT Service Framework

0.00/5 (No votes)
3 Mar 2000 4  
A class framework for developing NT services in MFC.
  • 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
    Usage
    History
    Class Framework Reference
    Planned Enhancements
    References
    Contacting the Author


    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)
    • Initial public release.

    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 #included into the final rc file testsrv.rc. This is done so that the testsrc.rc file can be edited by the resource designer inside Visual C++. In previous versions of CNTService, if your tried to edit the rc file (which was generated by the MC command line compiler), you would end up corrupting the file. If you are developing your own service using CNTService, then I would suggest you take this approach. What you need to do is create a resource script inside VC++, adding whatever resources you want to be in your services resources (e.g. version info, 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:

    • 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
        System
          CurrentControlSet
            Services
              EventLog
                Application
                  WinApp
                Security
                System
      

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

    See Also:
    Deregister


    CNTEventLogSource::Report

    BOOL Report(WORD wType, WORD wCategory, DWORD dwEventID, PSID 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:

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


    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:

    1. Call the RegisterServiceCtrlHandler() function immediately to register a handler function to handle control requests for the service.
    2. 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().
    3. When initialization is complete, call SetServiceStatus(), specifying the SERVICE_RUNNING state in the SERVICE_STATUS structure.
    4. 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.
    5. 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:

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


    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


    License

    This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

    A list of licenses authors might use can be found here