service module (Windows)

use service manages Windows services through the Service Control Manager. It is Windows-only in this version: manage Linux services by running systemctl through the shell module. The module is registered on every platform so a playbook compiles and validates identically everywhere; on Linux and macOS every call returns a runtime error. Every function takes the service name and returns Result[…, string].

status

service::status(name: string) -> Result[string, string]

The current state of a service: running, stopped, start_pending, stop_pending, paused, pause_pending or continue_pending. A state the module does not recognise is reported as unknown.

start, stop and restart

service::start(name: string) -> Result[unit, string]
service::stop(name: string) -> Result[unit, string]
service::restart(name: string, opts: Value) -> Result[unit, string]
service::start_with(name: string, opts: Value) -> Result[unit, string]
service::stop_with(name: string, opts: Value) -> Result[unit, string]

Starts, stops or restarts a service and returns once it has reached the target state, so a re-check straight after apply sees running or stopped, never a *_pending state. Each first waits out any pending state. start on a paused service continues it. start on a running service and stop on a stopped one are no-ops. restart stops the service, waits, starts it and waits again.

The wait polls the service at a tenth of the wait hint it reports, between 100 ms and 1 s, for up to 60 seconds. restart and the _with forms take an options map with the key timeout (seconds, int or float; in restart it applies to each phase); Value::Null keeps the defaults. On timeout the call returns an Err naming the last state it saw. If the service drops back to its starting state after going pending (for example it crashes while starting), the call fails at once.

stop_with and restart also take stop_dependents (bool, default false). When it is true, the call first stops every dependent service that is not already stopped, in the order the SCM lists them (the reverse of start order, so a dependent of a dependent stops first), each with the same timeout and wait. It then stops the service. restart starts the service again and then starts the dependents it stopped, in reverse stop order. A dependent that was already stopped stays stopped. A dependent that fails to stop or start ends the call with an Err naming it. Before any dependent is touched, the call checks that it can open the service with stop rights, so a service it cannot stop fails without stopping anything. If the service itself then fails to stop, the dependents already stopped are started again, and the Err names any that would not start. start_with does not take stop_dependents; passing it is an Err.

dependents

service::dependents(name: string) -> Result[List[string], string]

The names of the services that depend on name, directly or through another dependent, in any state, sorted. An empty list means nothing depends on it.

set_startup and startup

service::set_startup(name: string, mode: string) -> Result[unit, string]
service::startup(name: string) -> Result[string, string]

set_startup sets the startup type to automatic, automatic_delayed, manual or disabled. automatic_delayed is Automatic (Delayed Start); setting plain automatic clears the delayed flag. startup reads the type back as one of those four, or boot or system for driver start types, or other for anything else.

use service
use value

fn apply(props: Value) -> Result[ApplyResult, string] {
    service::set_startup("Spooler", "disabled")?
    service::stop("Spooler")?
    Ok(ApplyResult::Success)
}