ACE
6.3.3
|
Provide the base class which defines the interface for controlling an NT service. More...
#include <NT_Service.h>
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. More... | |
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_TCHAR * | name (void) const |
Get the service name. More... | |
const ACE_TCHAR * | desc (void) const |
Get the service description. More... | |
void | host (const ACE_TCHAR *host) |
Sets the host machine. More... | |
const ACE_TCHAR * | host (void) const |
Get the host machine. More... | |
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, DWORD desired_access=SERVICE_ALL_ACCESS) |
int | remove (void) |
int | startup (DWORD startup) |
Sets the startup type for the service. Returns -1 on error, 0 on success. More... | |
DWORD | startup (void) |
Returns the current startup type. More... | |
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. More... | |
int | continue_svc (ACE_Time_Value *wait_time=0, DWORD *svc_state=0) |
Continue the service. More... | |
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 Member Functions inherited from ACE_Task< ACE_MT_SYNCH > | |
ACE_Task (ACE_Thread_Manager *thr_mgr=0, ACE_Message_Queue< ACE_SYNCH_USE, ACE_System_Time_Policy > *mq=0) | |
virtual | ~ACE_Task (void) |
Destructor. More... | |
ACE_Message_Queue< ACE_SYNCH_USE, ACE_System_Time_Policy > * | msg_queue (void) |
Gets the message queue associated with this task. More... | |
void | msg_queue (ACE_Message_Queue< ACE_SYNCH_USE, ACE_System_Time_Policy > *) |
Sets the message queue associated with this task. More... | |
ACE_Time_Value_T< ACE_System_Time_Policy > | gettimeofday (void) const |
void | set_time_policy (ACE_System_Time_Policyconst &time_policy) |
int | putq (ACE_Message_Block *, ACE_Time_Value *timeout=0) |
int | getq (ACE_Message_Block *&mb, ACE_Time_Value *timeout=0) |
int | ungetq (ACE_Message_Block *, ACE_Time_Value *timeout=0) |
int | reply (ACE_Message_Block *mb, ACE_Time_Value *tv=0) |
int | put_next (ACE_Message_Block *msg, ACE_Time_Value *timeout=0) |
const ACE_TCHAR * | name (void) const |
ACE_Task< ACE_SYNCH_USE, ACE_System_Time_Policy > * | next (void) |
Get next Task pointer. More... | |
void | next (ACE_Task< ACE_SYNCH_USE, ACE_System_Time_Policy > *) |
Set next Task pointer. More... | |
ACE_Task< ACE_SYNCH_USE, ACE_System_Time_Policy > * | sibling (void) |
ACE_Module< ACE_SYNCH_USE, ACE_System_Time_Policy > * | module (void) const |
Return the Task's Module if there is one, else returns 0. More... | |
int | flush (u_long flag=ACE_Task_Flags::ACE_FLUSHALL) |
void | water_marks (ACE_IO_Cntl_Msg::ACE_IO_Cntl_Cmds, size_t) |
Manipulate watermarks. More... | |
void | dump (void) const |
Dump the state of an object. More... | |
Public Member Functions inherited from ACE_Task_Base | |
ACE_Task_Base (ACE_Thread_Manager *=0) | |
Constructor. More... | |
virtual | ~ACE_Task_Base (void) |
Destructor. More... | |
virtual int | close (u_long flags=0) |
Default ACE_Task close routine. More... | |
virtual int | module_closed (void) |
virtual int | put (ACE_Message_Block *, ACE_Time_Value *=0) |
Default ACE_Task put routine. More... | |
virtual int | activate (long flags=THR_NEW_LWP|THR_JOINABLE|THR_INHERIT_SCHED, int n_threads=1, int force_active=0, long priority=ACE_DEFAULT_THREAD_PRIORITY, int grp_id=-1, ACE_Task_Base *task=0, ACE_hthread_t thread_handles[]=0, void *stack[]=0, size_t stack_size[]=0, ACE_thread_t thread_ids[]=0, const char *thr_name[]=0) |
virtual int | wait (void) |
Wait for all threads running in a task to exit. More... | |
virtual int | suspend (void) |
Suspend a task. More... | |
virtual int | resume (void) |
Resume a suspended task. More... | |
int | grp_id (void) const |
Get the current group id. More... | |
void | grp_id (int) |
Set the current group id. More... | |
ACE_Thread_Manager * | thr_mgr (void) const |
Get the thread manager associated with this Task. More... | |
void | thr_mgr (ACE_Thread_Manager *) |
Set the thread manager associated with this Task. More... | |
int | is_reader (void) const |
True if queue is a reader, else false. More... | |
int | is_writer (void) const |
True if queue is a writer, else false. More... | |
size_t | thr_count (void) const |
ACE_thread_t | last_thread (void) const |
Public Member Functions inherited from ACE_Service_Object | |
ACE_Service_Object (ACE_Reactor *=0) | |
Constructor. More... | |
virtual | ~ACE_Service_Object (void) |
Destructor. More... | |
Public Member Functions inherited from ACE_Event_Handler | |
virtual | ~ACE_Event_Handler (void) |
Destructor is virtual to enable proper cleanup. More... | |
virtual ACE_HANDLE | get_handle (void) const |
Get the I/O handle. More... | |
virtual void | set_handle (ACE_HANDLE) |
Set the I/O handle. More... | |
virtual int | priority (void) const |
virtual void | priority (int priority) |
Set the priority of the Event_Handler. More... | |
virtual int | handle_input (ACE_HANDLE fd=ACE_INVALID_HANDLE) |
Called when input events occur (e.g., connection or data). More... | |
virtual int | handle_output (ACE_HANDLE fd=ACE_INVALID_HANDLE) |
virtual int | handle_exception (ACE_HANDLE fd=ACE_INVALID_HANDLE) |
Called when an exceptional events occur (e.g., SIGURG). More... | |
virtual int | handle_timeout (const ACE_Time_Value ¤t_time, const void *act=0) |
virtual int | handle_exit (ACE_Process *) |
Called when a process exits. More... | |
virtual int | handle_close (ACE_HANDLE handle, ACE_Reactor_Mask close_mask) |
virtual int | handle_signal (int signum, siginfo_t *=0, ucontext_t *=0) |
virtual int | resume_handler (void) |
virtual int | handle_qos (ACE_HANDLE=ACE_INVALID_HANDLE) |
virtual int | handle_group_qos (ACE_HANDLE=ACE_INVALID_HANDLE) |
virtual void | reactor (ACE_Reactor *reactor) |
Set the event demultiplexors. More... | |
virtual ACE_Reactor * | reactor (void) const |
Get the event demultiplexors. More... | |
virtual ACE_Reactor_Timer_Interface * | reactor_timer_interface (void) const |
Get only the reactor's timer related interface. More... | |
virtual Reference_Count | add_reference (void) |
Increment reference count on the handler. More... | |
virtual Reference_Count | remove_reference (void) |
Decrement reference count on the handler. More... | |
Reference_Counting_Policy & | reference_counting_policy (void) |
Current Reference_Counting_Policy. More... | |
Public Member Functions inherited from ACE_Shared_Object | |
ACE_Shared_Object (void) | |
Constructor. More... | |
virtual | ~ACE_Shared_Object (void) |
Destructor. More... | |
virtual int | init (int argc, ACE_TCHAR *argv[]) |
Initializes object when dynamic linking occurs. More... | |
virtual int | info (ACE_TCHAR **info_string, size_t length=0) const |
Returns information on a service object. More... | |
Public Attributes | |
ACE_ALLOC_HOOK_DECLARE | |
Declare the dynamic allocation hooks. More... | |
Public Attributes inherited from ACE_Task< ACE_MT_SYNCH > | |
ACE_Message_Queue< ACE_SYNCH_USE, ACE_System_Time_Policy > * | msg_queue_ |
Queue of messages on the ACE_Task.. More... | |
bool | delete_msg_queue_ |
true if should delete Message_Queue, false otherwise. More... | |
ACE_Module< ACE_SYNCH_USE, ACE_System_Time_Policy > * | mod_ |
Back-pointer to the enclosing module. More... | |
ACE_Task< ACE_SYNCH_USE, ACE_System_Time_Policy > * | next_ |
Pointer to adjacent ACE_Task. More... | |
ACE_ALLOC_HOOK_DECLARE | |
Declare the dynamic allocation hooks. More... | |
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. More... | |
virtual void | pause_requested (DWORD control_code) |
Called by <handle_control> when a pause was requested. More... | |
virtual void | continue_requested (DWORD control_code) |
Called by <handle_control> when a continue was requested. More... | |
virtual void | interrogate_requested (DWORD control_code) |
Called by <handle_control> when a interrogate was requested. More... | |
Protected Member Functions inherited from ACE_Event_Handler | |
ACE_Event_Handler (ACE_Reactor *=0, int priority=ACE_Event_Handler::LO_PRIORITY) | |
Force ACE_Event_Handler to be an abstract base class. More... | |
Protected Attributes | |
DWORD | start_time_ |
Estimate of init time needed. More... | |
SERVICE_STATUS_HANDLE | svc_handle_ |
Service handle - doesn't need close. More... | |
SERVICE_STATUS | svc_status_ |
SC_HANDLE | svc_sc_handle_ |
Service's SCM handle. More... | |
ACE_TCHAR * | name_ |
ACE_TCHAR * | desc_ |
ACE_TCHAR * | host_ |
ACE_OS_Log_Msg_Attributes | log_msg_attributes_ |
ACE_Log_Msg attributes to inherit from the starting thread. More... | |
Protected Attributes inherited from ACE_Task_Base | |
size_t | thr_count_ |
ACE_Thread_Manager * | thr_mgr_ |
Multi-threading manager. More... | |
u_long | flags_ |
ACE_Task flags. More... | |
int | grp_id_ |
This maintains the group id of the Task. More... | |
ACE_thread_t | last_thread_id_ |
Holds the thread ID of the last thread to exit svc() in this object. More... | |
Protected Attributes inherited from ACE_Event_Handler | |
Atomic_Reference_Count | reference_count_ |
Reference count. More... | |
Additional Inherited Members | |
Public Types inherited from ACE_Event_Handler | |
enum | { LO_PRIORITY = 0, HI_PRIORITY = 10, NULL_MASK = 0, READ_MASK = (1 << 0), WRITE_MASK = (1 << 1), EXCEPT_MASK = (1 << 2), ACCEPT_MASK = (1 << 3), CONNECT_MASK = (1 << 4), TIMER_MASK = (1 << 5), QOS_MASK = (1 << 6), GROUP_QOS_MASK = (1 << 7), SIGNAL_MASK = (1 << 8), ALL_EVENTS_MASK, RWE_MASK, DONT_CALL = (1 << 9) } |
enum | { ACE_EVENT_HANDLER_NOT_RESUMED = -1, ACE_REACTOR_RESUMES_HANDLER = 0, ACE_APPLICATION_RESUMES_HANDLER } |
typedef long | Reference_Count |
Reference count type. More... | |
Static Public Member Functions inherited from ACE_Task_Base | |
static ACE_THR_FUNC_RETURN | svc_run (void *) |
Routine that runs the service routine as a daemon thread. More... | |
static void | cleanup (void *object, void *params) |
Static Public Member Functions inherited from ACE_Event_Handler | |
static ACE_THR_FUNC_RETURN | read_adapter (void *event_handler) |
static int | register_stdin_handler (ACE_Event_Handler *eh, ACE_Reactor *reactor, ACE_Thread_Manager *thr_mgr, int flags=THR_DETACHED) |
static int | remove_stdin_handler (ACE_Reactor *reactor, ACE_Thread_Manager *thr_mgr) |
Performs the inverse of the register_stdin_handler() method. More... | |
Protected Types inherited from ACE_Event_Handler | |
typedef ACE_Atomic_Op< ACE_SYNCH_MUTEX, Reference_Count > | Atomic_Reference_Count |
Typedef for implementation of reference counting. More... | |
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:
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.
|
inline |
Constructor primarily for use when running the service.
|
inline |
Constructor primarily for use when inserting/removing/controlling the service.
|
virtual |
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.
|
protectedvirtual |
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.
|
inline |
Get the service description.
|
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.
|
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.
void ACE_NT_Service::host | ( | const ACE_TCHAR * | host | ) |
Sets the host machine.
|
inline |
Get 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 , |
||
DWORD | desired_access = SERVICE_ALL_ACCESS |
||
) |
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.
|
protectedvirtual |
Called by <handle_control> when a interrogate was requested.
Sets the name and description for the service. If desc is 0, it takes the same value as name.
|
inline |
Get the service name.
|
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.
|
protectedvirtual |
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.
|
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.
int ACE_NT_Service::startup | ( | DWORD | startup | ) |
Sets the startup type for the service. Returns -1 on error, 0 on success.
DWORD ACE_NT_Service::startup | ( | void | ) |
Returns the current startup type.
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.
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.
|
protectedvirtual |
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.
|
inlinevirtual |
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.
|
inline |
Set the svc_handle_ member. This is only a public function because the macro-generated service function calls it.
|
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.
|
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.
ACE_NT_Service::ACE_ALLOC_HOOK_DECLARE |
Declare the dynamic allocation hooks.
|
protected |
|
protected |
|
protected |
ACE_Log_Msg attributes to inherit from the starting thread.
|
protected |
|
protected |
Estimate of init time needed.
|
protected |
Service handle - doesn't need close.
|
protected |
Service's SCM handle.
|
protected |