windows-service-rs

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).

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) {
    // The entry point where execution will start on a background thread after a call to
    // `service_dispatcher::start` from `main`.
}

fn main() -> Result {
    // 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.

…

Please see the corresponding MSDN article that describes how event handler works internally:\

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.

…

Please refer to the "Service State Transitions" article on MSDN for more info:\

License: MIT/Apache-2.0