ACE_NT_Service Class Reference

Provide the base class which defines the interface for controlling an NT service. More...

#include <NT_Service.h>

Inheritance diagram for ACE_NT_Service:

Inheritance graph
[legend]
Collaboration diagram for ACE_NT_Service:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 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)
virtual ~ACE_NT_Service (void)
virtual int open (void *args=0)
virtual int fini (void)
virtual int svc (void)
virtual void handle_control (DWORD control_code)
void svc_handle (const SERVICE_STATUS_HANDLE new_svc_handle)
void name (const ACE_TCHAR *name, const ACE_TCHAR *desc=0)
const ACE_TCHARname (void) const
 Get the service name.
const ACE_TCHARdesc (void) const
 Get the service description.
void host (const ACE_TCHAR *host)
 Sets the host machine.
const ACE_TCHARhost (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)
int remove (void)
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.
void capture_log_msg_attributes (void)
void inherit_log_msg_attributes (void)
int start_svc (ACE_Time_Value *wait_time=0, DWORD *svc_state=0, DWORD argc=0, const ACE_TCHAR **argv=0)
int stop_svc (ACE_Time_Value *wait_time=0, DWORD *svc_state=0)
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)
int state (DWORD *pstate, ACE_Time_Value *wait_hint=0)
int test_access (DWORD desired_access=SERVICE_ALL_ACCESS)

Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks.

Protected Member Functions

int report_status (DWORD new_status, DWORD time_hint=0)
SC_HANDLE svc_sc_handle (void)
void wait_for_service_state (DWORD desired_state, ACE_Time_Value *wait_time)
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 Attributes

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_TCHARname_
ACE_TCHARdesc_
ACE_TCHARhost_
ACE_OS_Log_Msg_Attributes log_msg_attributes_
 ACE_Log_Msg attributes to inherit from the starting thread.

Detailed Description

Provide the base class which defines the interface for controlling an NT service.

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:

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.


Constructor & Destructor Documentation

ACE_INLINE ACE_NT_Service::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_INLINE ACE_NT_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.

ACE_NT_Service::~ACE_NT_Service void   )  [virtual]
 


Member Function Documentation

void ACE_NT_Service::capture_log_msg_attributes void   ) 
 

Set the ACE_Log_Msg attributes that the service thread will use to initialize its ACE_Log_Msg instance. This is how the initiating thread's logging ostream, etc. get into the service thread. The logging attributes in effect when this function is called are what the service thread will have at its disposal when it starts; therefore, the main thread should set up logging options for the process, and call this function just before calling the StartServiceCtrlDispatcher function.

void ACE_NT_Service::continue_requested DWORD  control_code  )  [protected, virtual]
 

Called by <handle_control> when a continue was requested.

int ACE_NT_Service::continue_svc ACE_Time_Value wait_time = 0,
DWORD *  svc_state = 0
 

Continue the service.

ACE_INLINE const ACE_TCHAR * ACE_NT_Service::desc void   )  const
 

Get the service description.

int ACE_NT_Service::fini void   )  [virtual]
 

Hook called when terminating the service. Inherited from ACE_Shared_Object. Default implementation sets the service status to SERVICE_STOPPED.

Reimplemented from ACE_Shared_Object.

void ACE_NT_Service::handle_control DWORD  control_code  )  [virtual]
 

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.

ACE_INLINE const ACE_TCHAR * ACE_NT_Service::host void   )  const
 

Get the host machine.

void ACE_NT_Service::host const ACE_TCHAR host  ) 
 

Sets the host machine.

void ACE_NT_Service::inherit_log_msg_attributes void   ) 
 

Set the ACE_Log_Msg attributes in the current thread to those saved in the most recent call to capture_log_msg_attributes(). This function should be called from the service's service thread. Ideally, it is the first method called to be sure that any logging done is incorporated correctly into the process's established logging setup.

int ACE_NT_Service::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.

void ACE_NT_Service::interrogate_requested DWORD  control_code  )  [protected, virtual]
 

Called by <handle_control> when a interrogate was requested.

ACE_INLINE const ACE_TCHAR * ACE_NT_Service::name void   )  const
 

Get the service name.

Reimplemented from ACE_Task< ACE_MT_SYNCH >.

void ACE_NT_Service::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.

int ACE_NT_Service::open void *  args = 0  )  [virtual]
 

Hook called to open the service. By default, sets the service status to SERVICE_START_PENDING, calls the svc() method, interprets and sets the service status, and returns.

Reimplemented from ACE_Task_Base.

void ACE_NT_Service::pause_requested DWORD  control_code  )  [protected, virtual]
 

Called by <handle_control> when a pause was requested.

int ACE_NT_Service::pause_svc ACE_Time_Value wait_time = 0,
DWORD *  svc_state = 0
 

Pause the service.

int ACE_NT_Service::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 ACE_NT_Service::report_status DWORD  new_status,
DWORD  time_hint = 0
[protected]
 

int ACE_NT_Service::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 <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.

DWORD ACE_NT_Service::startup void   ) 
 

Returns the current startup type.

int ACE_NT_Service::startup DWORD  startup  ) 
 

Sets the startup type for the service. Returns -1 on error, 0 on success.

int ACE_NT_Service::state DWORD *  pstate,
ACE_Time_Value wait_hint = 0
 

A version of <state> that returns -1 for failure, 0 for success. The DWORD pointed to by pstate receives the state value.

DWORD ACE_NT_Service::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.

void ACE_NT_Service::stop_requested DWORD  control_code  )  [protected, virtual]
 

Called by <handle_control> when a stop/shutdown was requested.

int ACE_NT_Service::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.

ACE_INLINE int ACE_NT_Service::svc void   )  [virtual]
 

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.

Reimplemented from ACE_Task_Base.

ACE_INLINE void ACE_NT_Service::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.

SC_HANDLE ACE_NT_Service::svc_sc_handle void   )  [protected]
 

Return the svc_sc_handle_ member. If the member is null, it retrieves the handle from the Service Control Manager and caches it.

int ACE_NT_Service::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.

void ACE_NT_Service::wait_for_service_state DWORD  desired_state,
ACE_Time_Value wait_time
[protected]
 

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.


Member Data Documentation

ACE_NT_Service::ACE_ALLOC_HOOK_DECLARE
 

Declare the dynamic allocation hooks.

Reimplemented from ACE_Task< ACE_MT_SYNCH >.

ACE_TCHAR* ACE_NT_Service::desc_ [protected]
 

ACE_TCHAR* ACE_NT_Service::host_ [protected]
 

ACE_OS_Log_Msg_Attributes ACE_NT_Service::log_msg_attributes_ [protected]
 

ACE_Log_Msg attributes to inherit from the starting thread.

ACE_TCHAR* ACE_NT_Service::name_ [protected]
 

DWORD ACE_NT_Service::start_time_ [protected]
 

Estimate of init time needed.

SERVICE_STATUS_HANDLE ACE_NT_Service::svc_handle_ [protected]
 

Service handle - doesn't need close.

SC_HANDLE ACE_NT_Service::svc_sc_handle_ [protected]
 

Service's SCM handle.

SERVICE_STATUS ACE_NT_Service::svc_status_ [protected]
 


The documentation for this class was generated from the following files:
Generated on Wed Nov 23 15:49:30 2005 for ACE by  doxygen 1.4.5