/* -*- C++ -*- */ // $Id$ // ============================================================================ // // = LIBRARY // ace // // = FILENAME // NT_Service.h // // = AUTHOR // Steve Huston // // ============================================================================ #ifndef ACE_NT_SERVICE_H #define ACE_NT_SERVICE_H #include "ace/pre.h" #include "ace/config-all.h" #if !defined (ACE_LACKS_PRAGMA_ONCE) # pragma once #endif /* ACE_LACKS_PRAGMA_ONCE */ #if defined (ACE_WIN32) && !defined (ACE_HAS_PHARLAP) #include "ace/Service_Object.h" #include "ace/Synch.h" #include "ace/Task.h" // ACE_NT_SERVICE_START_TIMEOUT is an estimate of the number of // milliseconds your service will take to start. Default is 5 // seconds; you can pass a different value (or set one) when you // create the ACE_NT_Service object for your service. #if !defined ACE_NT_SERVICE_START_TIMEOUT #define ACE_NT_SERVICE_START_TIMEOUT 5000 #endif /* ACE_NT_SERVICE_TIMEOUT */ class ACE_Export ACE_NT_Service : public ACE_Task { // = TITLE // Provide the base class which defines the interface for controlling // an NT service. // // = DESCRIPTION // NT Services can be implemented using the framework defined by // the ACE_NT_Service class, and the macros defined in this file. // Some quick refresher notes on NT Services: // - The main program defines an array of entries describing the // services offered. The ACE_NT_SERVICE_ENTRY macro can help with // this. // - For each service, a separate ServiceMain and Handler function // need to be defined. These are taken care of by the // ACE_NT_SERVICE_DEFINE macro. // - When the main program/thread calls // StartServiceCtrlDispatcher, NT creates a thread for each // service, and runs the ServiceMain function for the service in // that new thread. When that thread exits, the service is gone. // // To use this facility, you could derive a class from // ACE_Service_Object (if you want to start via ACE's service // configurator), or use any other class to run when the image // starts (assuming that NT runs the image). You must set up an // NT SERVICE_TABLE_ENTRY array to define your service(s). You // can use the ACE_NT_SERVICE_... macros defined below for this. // // A SERVICE_TABLE might look like this: // ACE_NT_SERVICE_REFERENCE(Svc1); // If service is in another file // SERVICE_TABLE_ENTRY myServices[] = { // ACE_NT_SERVICE_ENTRY ("MyNeatService", Svc1), // { 0, 0 } }; // // In the file where your service(s) are implemented, use the // ACE_NT_SERVICE_DEFINE macro to set up the following: // 1. A pointer to the service's implementation object (must be derived // from ACE_NT_Service). // 2. The service's Handler function (forwards all requests to the // ACE_NT_Service-derived object's handle_control function). // 3. The service's ServiceMain function. Creates a new instance // of the ACE_NT_Service-derived class SVCCLASS, unless one has // been created already. // // If you are using all the default constructor values, you can // let the generated ServiceMain function create the object, else // you need to create it by hand before calling // StartServiceCtrlDispatcher. Set the pointer so ServiceMain // won't create another one. Another reason you may want to do // the object creation yourself is if you want to also implement // suspend and resume functions (the ones inherited from // ACE_Service_Object) to do something intelligent to the services // which are running, like call their handle_control functions to // request suspend and resume actions, similar to what NT would do // if a Services control panel applet would do if the user clicks // on Suspend. public: // = Initialization and termination methods. ACE_NT_Service (DWORD start_timeout = ACE_NT_SERVICE_START_TIMEOUT, DWORD service_type = SERVICE_WIN32_OWN_PROCESS, DWORD controls_mask = SERVICE_ACCEPT_STOP); // Constructor primarily for use when running the service. ACE_NT_Service (const ACE_TCHAR *name, const ACE_TCHAR *desc = 0, DWORD start_timeout = ACE_NT_SERVICE_START_TIMEOUT, DWORD service_type = SERVICE_WIN32_OWN_PROCESS, DWORD controls_mask = SERVICE_ACCEPT_STOP); // Constructor primarily for use when inserting/removing/controlling // the service. virtual ~ACE_NT_Service (void); // = Functions to operate the service virtual int open (void *args = 0); // Hook called to open the service. By default, will set the status // to _PENDING, , , then set the status to // STOPPED. virtual int svc (void); // The actual service implementation. This function need not be overridden // by applications that are just using SCM capabilities, but must be // by subclasses when actually running the service. It is expected that // this function will set the status to RUNNING. virtual void handle_control (DWORD control_code); // This function is called in response to a request from the Service // Dispatcher. It must interact with the function to effect the // requested control operation. The default implementation handles // all requests as follows: // SERVICE_CONTROL_STOP: set stop pending, set cancel flag // SERVICE_CONTROL_PAUSE: set pause pending, , set paused // SERVICE_CONTROL_CONTINUE: set continue pending, , set running // SERVICE_CONTROL_INTERROGATE: reports current status // SERVICE_CONTROL_SHUTDOWN: same as SERVICE_CONTROL_STOP. void svc_handle (const SERVICE_STATUS_HANDLE new_svc_handle); // Set the svc_handle_ member. This is only a public function because // the macro-generated service function calls it. // = Methods which can be used to do SCP-like functions. The first group // are used to register/insert and remove the service's definition in the // SCM registry. void name (const ACE_TCHAR *name, const ACE_TCHAR *desc = 0); // Sets the name and description for the service. // If desc is 0, it takes the same value as name. const ACE_TCHAR *name (void) const; // Get the service name. const ACE_TCHAR *desc (void) const; // Get the service description. void host (const ACE_TCHAR *host); // Sets the host machine const ACE_TCHAR *host (void) const; // Get the host machine. int insert (DWORD start_type = SERVICE_DEMAND_START, DWORD error_control = SERVICE_ERROR_IGNORE, const ACE_TCHAR *exe_path = 0, const ACE_TCHAR *group_name = 0, LPDWORD tag_id = 0, const ACE_TCHAR *dependencies = 0, const ACE_TCHAR *account_name = 0, const ACE_TCHAR *password = 0); // Insert (create) the service in the NT Service Control Manager, // with the given creation values. exe_path defaults to the path name // of the program that calls the function. All other 0-defaulted arguments // pass 0 into the service creation, taking NT_specified defaults. // Returns -1 on error, 0 on success. int remove (void); // Remove the service from the NT Service Control Manager. Returns -1 on // error, 0 on success. This just affects the SCM and registry - the // can and will keep running fine if it is already running. int startup (DWORD startup); // Sets the startup type for the service. Returns -1 on error, 0 on success. DWORD startup (void); // Returns the current startup type. // = Methods which control the service's execution. // These methods to start/pause/resume/stop/check the service all // have the following common behavior with respect to // and return value. is a pointer to an ACE_Time_Value // object. If not supplied (a zero pointer) the function will wait // indefinitely for the action to be finalized (service reach // running state, completely shut down, etc.) or get "stuck" before // returning. If the time is supplied, it specifies how long to // wait for the service to reach a steady state, and on return, it // is updated to the service's last reported wait hint. So, if you // want to control the waiting yourself (for example, you want to // react to UI events during the wait) specify a of (0, // 0) and use the updated time to know when to check the service's // state again. NOTE!!!! The wait_time things don't work yet. The // calls always check status once, and do not wait for it to change. // // The return value from start_svc, stop_svc, pause_svc, // continue_svc is 0 if the request to NT to effect the change was // made successfully. The service may refuse to change, or not do // what you wanted; so if you need to know, supply a // pointer to receive the service's reported last state on return // and check it to see if it's what you want. The functions only // return -1 when the actual request to the service is refused - // this would include privilege restrictions and if the service is // not configured to receive the request (this is most likely to // happen in the case of pause and continue). int start_svc (ACE_Time_Value *wait_time = 0, DWORD *svc_state = 0, DWORD argc = 0, const ACE_TCHAR **argv = 0); // Start the service (must have been inserted before). wait_time is // the time to wait for the service to reach a steady state before // returning. If it is 0, the function waits as long as it takes // for the service to reach the 'running' state, or gets stuck in // some other state, or exits. If is supplied, it is // updated on return to hold the service's last reported wait hint. // svc_state can be used to receive the state which the service // settled in. If the value is 0, the service never ran. argc/argv // are passed to the service's ServiceMain function when it starts. // Returns 0 for success, -1 for error. int stop_svc (ACE_Time_Value *wait_time = 0, DWORD *svc_state = 0); // Requests the service to stop. Will wait up to for // the service to actually stop. If not specified, the function // waits until the service either stops or gets stuck in some other // state before it stops. If is specified, it receives // the last reported state of the service. Returns 0 if the request // was made successfully, -1 if not. int pause_svc (ACE_Time_Value *wait_time = 0, DWORD *svc_state = 0); // Pause the service. int continue_svc (ACE_Time_Value *wait_time = 0, DWORD *svc_state = 0); // Continue the service. DWORD state (ACE_Time_Value *wait_hint = 0); // Get the current state for the service. If is not 0, // it receives the service's reported wait hint. Note that this // function returns 0 on failure (not -1 as is usual in ACE). A // zero return would (probably) only be returned if there is either // no service with the given name in the SCM database, or the caller // does not have sufficient rights to access the service state. The // set of valid service state values are all greater than 0. int state (DWORD *pstate, ACE_Time_Value *wait_hint = 0); // A version of that returns -1 for failure, 0 for success. // The DWORD pointed to by pstate receives the state value. int test_access (DWORD desired_access = SERVICE_ALL_ACCESS); // Test access to the object's service in the SCM. The service must // already have been inserted in the SCM database. This function // has no affect on the service itself. Returns 0 if the specified // access is allowed, -1 otherwise (either the access is denied, or // there is a problem with the service's definition - check // ACE_OS::last_error to get the specific error indication. ACE_ALLOC_HOOK_DECLARE; // Declare the dynamic allocation hooks. protected: int report_status (DWORD new_status, DWORD time_hint = 0); SC_HANDLE svc_sc_handle (void); // Return the svc_sc_handle_ member. If the member is null, it // retrieves the handle from the Service Control Manager and caches // it. void wait_for_service_state (DWORD desired_state, ACE_Time_Value *wait_time); // Waits for the service to reach or get // (apparently) stuck before it reaches that state. Will wait at // most to get to the desired state. If is // 0, then the function keeps waiting until the desired state is // reached or the service doesn't update its state any further. The // svc_status_ class member is updated upon return. NOTE - the // timeout doesn't currently work - it always acts like // ACE_Time_Value::zero is passed - it checks the state once but // doesn't wait after that. virtual void stop_requested (DWORD control_code); // Called by when a stop/shutdown was requested. virtual void pause_requested (DWORD control_code); // Called by when a pause was requested. virtual void continue_requested (DWORD control_code); // Called by when a continue was requested. virtual void interrogate_requested (DWORD control_code); // Called by when a interrogate was requested. protected: DWORD start_time_; // Estimate of init time needed SERVICE_STATUS_HANDLE svc_handle_; // Service handle - doesn't need close. SERVICE_STATUS svc_status_; SC_HANDLE svc_sc_handle_; // Service's SCM handle ACE_TCHAR *name_; ACE_TCHAR *desc_; ACE_TCHAR *host_; }; // These macros help to get things set up correctly at compile time // and to take most of the grudge work out of creating the proper // functions and doing the registrations. // // ACE_NT_SERVICE_DEFINE - defines the 'ServiceMain' function which NT will // call in its own thread when the service control // dispatcher starts. #define ACE_NT_SERVICE_DEFINE(SVCNAME, SVCCLASS, SVCDESC) \ ACE_NT_Service * _ace_nt_svc_obj_##SVCNAME = 0; \ VOID WINAPI ace_nt_svc_handler_##SVCNAME (DWORD fdwControl) { \ _ace_nt_svc_obj_##SVCNAME->handle_control(fdwControl); \ } \ VOID WINAPI ace_nt_svc_main_##SVCNAME (DWORD dwArgc, \ ACE_TCHAR **lpszArgv) { \ int delete_svc_obj = 0; \ if (_ace_nt_svc_obj_##SVCNAME == 0) { \ ACE_NEW (_ace_nt_svc_obj_##SVCNAME, SVCCLASS); \ if (_ace_nt_svc_obj_##SVCNAME == 0) \ return; \ delete_svc_obj = 1; \ } \ _ace_nt_svc_obj_##SVCNAME->init(dwArgc, lpszArgv); \ _ace_nt_svc_obj_##SVCNAME->svc_handle( \ RegisterServiceCtrlHandler(SVCDESC, \ &ace_nt_svc_handler_##SVCNAME)); \ _ace_nt_svc_obj_##SVCNAME->open(); \ _ace_nt_svc_obj_##SVCNAME->wait(); \ _ace_nt_svc_obj_##SVCNAME->fini(); \ if (delete_svc_obj) { \ delete _ace_nt_svc_obj_##SVCNAME; \ _ace_nt_svc_obj_##SVCNAME = 0; \ } \ return; \ } #define ACE_NT_SERVICE_REFERENCE(SVCNAME) \ extern ACE_NT_Service * _ace_nt_svc_obj_##SVCNAME; \ extern VOID WINAPI ace_nt_svc_main_##SVCNAME (DWORD dwArgc, \ ACE_TCHAR **lpszArgv); #define ACE_NT_SERVICE_ENTRY(SVCDESC, SVCNAME) \ { SVCDESC, &ace_nt_svc_main_##SVCNAME } #define ACE_NT_SERVICE_RUN(SVCNAME, SVCINSTANCE, RET) \ SERVICE_TABLE_ENTRY _ace_nt_svc_table[2] = \ { \ ACE_NT_SERVICE_ENTRY(#SVCNAME, SVCNAME), \ { 0, 0 } \ }; \ _ace_nt_svc_obj_##SVCNAME = SVCINSTANCE; \ ACE_OS::last_error (0); \ int RET = StartServiceCtrlDispatcher(_ace_nt_svc_table); #if defined (__ACE_INLINE__) #include "ace/NT_Service.i" #endif /* __ACE_INLINE__ */ #endif /* ACE_WIN32 && !ACE_HAS_PHARLAP */ #include "ace/post.h" #endif /* ACE_SERVICE_OBJECT_H */