diff options
Diffstat (limited to 'ace/NT_Service.h')
| -rw-r--r-- | ace/NT_Service.h | 352 |
1 files changed, 0 insertions, 352 deletions
diff --git a/ace/NT_Service.h b/ace/NT_Service.h deleted file mode 100644 index c266454568e..00000000000 --- a/ace/NT_Service.h +++ /dev/null @@ -1,352 +0,0 @@ -/* -*- C++ -*- */ -// $Id$ - -// ============================================================================ -// -// = LIBRARY -// ace -// -// = FILENAME -// NT_Service.h -// -// = AUTHOR -// Steve Huston -// -// ============================================================================ - -#ifndef ACE_NT_SERVICE_H -#define ACE_NT_SERVICE_H - -#include "ace/inc_user_config.h" - -#if !defined (ACE_LACKS_PRAGMA_ONCE) -# pragma once -#endif /* ACE_LACKS_PRAGMA_ONCE */ - -#if defined (ACE_HAS_WINNT4) && ACE_HAS_WINNT4 != 0 - -#include "ace/Service_Object.h" -#include "ace/Synch.h" -#include "ace/Task.h" - -// 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. - - -// 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<ACE_MT_SYNCH> -{ - // = TITLE - // Provide the base class which defines the interface for controlling - // an NT service. - // - // = DESCRIPTION -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 (LPCTSTR name, - LPCTSTR 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 - // START_PENDING, svc(), wait(), 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 svc() 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, suspend(), set paused - // SERVICE_CONTROL_CONTINUE: set continue pending, resume(), 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 (LPCTSTR name, LPCTSTR desc = 0); - // Sets the name and description for the service. - // If desc is 0, it takes the same value as name. - - LPCTSTR name (void) const; - // Get the service name. - - LPCTSTR desc (void) const; - // Get the service description. - - int insert (DWORD start_type = SERVICE_DEMAND_START, - DWORD error_control = SERVICE_ERROR_IGNORE, - LPCTSTR exe_path = 0, - LPCTSTR group_name = 0, - LPDWORD tag_id = 0, - LPCTSTR dependencies = 0, - LPCTSTR account_name = 0, - LPCTSTR 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 <wait_time> and return value. - // <wait_time> 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 <wait_time> 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 <svc_state> 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, LPCTSTR *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 <wait_time> 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 <wait_time> 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 <svc_state> 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 <wait_hint> 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 state() which 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 <desired_state> or get (apparently) stuck - // before it reaches that state. Will wait at most <wait_time> to get to - // the desired state. If <wait_time> 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 handle_control () when a stop/shutdown was requested. - - virtual void pause_requested (DWORD control_code); - // Called by handle_control () when a pause was requested. - - virtual void continue_requested (DWORD control_code); - // Called by handle_control () when a continue was requested. - - virtual void interrogate_requested (DWORD control_code); - // Called by handle_control () 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 - LPTSTR name_; - LPTSTR desc_; - -}; - -// 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, LPTSTR *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 VOID WINAPI ace_nt_svc_main_##SVCNAME (DWORD dwArgc, LPTSTR *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_HAS_WINNT4 */ -#endif /* ACE_SERVICE_OBJECT_H */ |