windows-service
A crate that provides facilities for management and implementation of windows services.
Implementing windows service
This section describes the steps of implementing a program that runs as a windows service, for complete source code of such program take a look at examples folder.
Basics
Each windows service has to implement a service entry function fn(argc: u32, argv: *mut *mut u16) and register it with the system from the application's main.
This crate provides a handy [define_windows_service!] macro to generate a low level
boilerplate for the service entry function that parses input from the system and delegates
handling to user defined higher level function fn(arguments: Vec<OsString>).
This guide references the low level entry function as ffi_service_main and higher
level function as my_service_main but it's up to developer how to call them.
#[macro_use]
extern crate windows_service;
use std::ffi::OsString;
use windows_service::service_dispatcher;
define_windows_service!(ffi_service_main, my_service_main);
fn my_service_main(arguments: Vec<OsString>) {
// The entry point where execution will start on a background thread after a call to
// `service_dispatcher::start` from `main`.
}
fn main() -> Result<(), windows_service::Error> {
// Register generated `ffi_service_main` with the system and start the service, blocking
// this thread until the service is stopped.
service_dispatcher::start("myservice", ffi_service_main)?;
Ok(())
}Handling service events
The first thing that a windows service should do early in its lifecycle is to subscribe for service events such as stop or pause and many other.
extern crate windows_service;
use std::ffi::OsString;
use windows_service::service::ServiceControl;
use windows_service::service_control_handler::{self, ServiceControlHandlerResult};
fn my_service_main(arguments: Vec<OsString>) {
if let Err(_e) = run_service(arguments) {
// Handle errors in some way.
}
}
fn run_service(arguments: Vec<OsString>) -> Result<(), windows_service::Error> {
let event_handler = move |control_event| -> ServiceControlHandlerResult {
match control_event {
ServiceControl::Stop => {
// Handle stop event and return control back to the system.
ServiceControlHandlerResult::NoError
}
// All services must accept Interrogate even if it's a no-op.
ServiceControl::Interrogate => ServiceControlHandlerResult::NoError,
_ => ServiceControlHandlerResult::NotImplemented,
}
};
// Register system service event handler
let status_handle = service_control_handler::register("myservice", event_handler)?;
Ok(())
}Please see the corresponding MSDN article that describes how event handler works internally:
https://msdn.microsoft.com/en-us/library/windows/desktop/ms685149(v=vs.85).aspx
Updating service status
When application that implements a windows service is launched by the system, it's
automatically put in the StartPending state.
The application needs to complete the initialization, obtain ServiceStatusHandle (see
[service_control_handler::register]) and transition to Running state.
If service has a lengthy initialization, it should immediately tell the system how
much time it needs to complete it, by sending the StartPending state, time
estimate using ServiceStatus::wait_hint and increment ServiceStatus::checkpoint each
time the service completes a step in initialization.
The system will attempt to kill a service that is not able to transition to Running
state before the proposed ServiceStatus::wait_hint expired.
The same concept applies when transitioning between other pending states and their corresponding target states.
Note that it's safe to clone ServiceStatusHandle and use it from any thread.
extern crate windows_service;
use std::ffi::OsString;
use std::time::Duration;
use windows_service::service::{
ServiceControl, ServiceControlAccept, ServiceExitCode, ServiceState, ServiceStatus,
ServiceType,
};
use windows_service::service_control_handler::{self, ServiceControlHandlerResult};
fn my_service_main(arguments: Vec<OsString>) {
if let Err(_e) = run_service(arguments) {
// Handle error in some way.
}
}
fn run_service(arguments: Vec<OsString>) -> windows_service::Result<()> {
let event_handler = move |control_event| -> ServiceControlHandlerResult {
match control_event {
ServiceControl::Stop | ServiceControl::Interrogate => {
ServiceControlHandlerResult::NoError
}
_ => ServiceControlHandlerResult::NotImplemented,
}
};
// Register system service event handler
let status_handle = service_control_handler::register("my_service_name", event_handler)?;
let next_status = ServiceStatus {
// Should match the one from system service registry
service_type: ServiceType::OWN_PROCESS,
// The new state
current_state: ServiceState::Running,
// Accept stop events when running
controls_accepted: ServiceControlAccept::STOP,
// Used to report an error when starting or stopping only, otherwise must be zero
exit_code: ServiceExitCode::Win32(0),
// Only used for pending states, otherwise must be zero
checkpoint: 0,
// Only used for pending states, otherwise must be zero
wait_hint: Duration::default(),
};
// Tell the system that the service is running now
status_handle.set_service_status(next_status)?;
// Do some work
Ok(())
}Please refer to the "Service State Transitions" article on MSDN for more info:
https://msdn.microsoft.com/en-us/library/windows/desktop/ee126211(v=vs.85).aspx
License: MIT/Apache-2.0