windows-service

https://docs.rs/windows-service/latest/
Admin
A Rust crate providing facilities for management and implementation of Windows services with support...
Tokens:235,034
Snippets:1,816
Trust Score:9.1
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start a service with arguments using Service::start

Source: https://docs.rs/windows-service/latest/src/windows_service/service.rs.html

Example from the start method documentation. Opens a service with ServiceAccess::START and calls start with an argument. Requires ServiceManagerAccess::CONNECT. Returns a windows_service::Result.

```rust
use std::ffi::OsStr;
use windows_service::service::ServiceAccess;
use windows_service::service_manager::{ServiceManager, ServiceManagerAccess};

# fn main() -> windows_service::Result<()> {
let manager = ServiceManager::local_computer(None::<&str>, ServiceManagerAccess::CONNECT)?;
let my_service = manager.open_service("my_service", ServiceAccess::START)?;
my_service.start(&[OsStr::new("Started from Rust!")])?;
# Ok(())
# }

```

--------------------------------

### Example from ping_service.rs: start service

Source: https://docs.rs/windows-service/latest/windows_service/service_dispatcher/fn.start.html

Excerpt from `examples/ping_service.rs` (line 53) showing a `run` function that calls `service_dispatcher::start` with a `SERVICE_NAME` constant and the generated `ffi_service_main`.

```rust
pub fn run() -> Result<()> {
    // Register generated `ffi_service_main` with the system and start the service, blocking
    // this thread until the service is stopped.
    service_dispatcher::start(SERVICE_NAME, ffi_service_main)
}
```

--------------------------------

### service_dispatcher::start usage example

Source: https://docs.rs/windows-service/latest/src/windows_service/service_dispatcher.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to start a Windows service using service_dispatcher::start. The example registers the generated ffi_service_main with the system and blocks the current thread until the service is stopped.

```rust
#[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() -> windows_service::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(())
}

```

--------------------------------

### Install Windows service with windows-service crate

Source: https://docs.rs/windows-service/latest/src/install_service/install_service.rs.html?search=u32+-%3E+bool

Rust example that installs a Windows service named 'ping_service'. It requires Windows and uses the windows-service crate. The service is configured to run as System with OnDemand start type. The executable path is set to the current executable's directory with 'ping_service.exe'.

```rust
#[cfg(windows)]
fn main() -> windows_service::Result<()> {
    use std::ffi::OsString;
    use windows_service::{
        service::{ServiceAccess, ServiceErrorControl, ServiceInfo, ServiceStartType, ServiceType},
        service_manager::{ServiceManager, ServiceManagerAccess},
    };

    let manager_access = ServiceManagerAccess::CONNECT | ServiceManagerAccess::CREATE_SERVICE;
    let service_manager = ServiceManager::local_computer(None::<&str>, manager_access)?;

    // This example installs the service defined in `examples/ping_service.rs`.
    // In the real world code you would set the executable path to point to your own binary
    // that implements windows service.
    let service_binary_path = ::std::env::current_exe()
        .unwrap()
        .with_file_name("ping_service.exe");

    let service_info = ServiceInfo {
        name: OsString::from("ping_service"),
        display_name: OsString::from("Ping service"),
        service_type: ServiceType::OWN_PROCESS,
        start_type: ServiceStartType::OnDemand,
        error_control: ServiceErrorControl::Normal,
        executable_path: service_binary_path,
        launch_arguments: vec![],
        dependencies: vec![],
        account_name: None, // run as System
        account_password: None,
    };
    let service = service_manager.create_service(&service_info, ServiceAccess::CHANGE_CONFIG)?;
    service.set_description("Windows service example from windows-service-rs")?;
    Ok(())
}

#[cfg(not(windows))]
fn main() {
    panic!("This program is only intended to run on Windows.");
}
```

--------------------------------

### start

Source: https://docs.rs/windows-service/latest/windows_service/service_dispatcher/fn.start.html

Documentation for the `start` function in the `windows_service::service_dispatcher` module.

```APIDOC
## start

### Description
Starts the service control dispatcher. Once started, it blocks the current thread until the service is stopped. On successful initialization, the system calls the provided `service_main` on a background thread. On failure, it immediately returns an error and no threads are spawned.

### Function Signature
```rust
pub fn start(
    service_name: impl AsRef<OsStr>,
    service_main: extern "system" fn(u32, *mut *mut u16),
) -> Result<()>
```

### Parameters
- **service_name** (`impl AsRef<OsStr>`) - Required - The name of the service to start.
- **service_main** (`extern "system" fn(u32, *mut *mut u16)`) - Required - The service main function that will be called on a background thread after successful initialization.

### Return Value
- `Result<()>` - Returns `Ok(())` on success, or an error if the service control dispatcher fails to start.

### Example
```rust
#[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() -> windows_service::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(())
}
```
```

--------------------------------

### service_dispatcher::start example

Source: https://docs.rs/windows-service/latest/src/windows_service/service_dispatcher.rs.html?search=std%3A%3Avec

Shows how to start the service control dispatcher from main. The start function blocks the current thread until the service is stopped and calls the service_main on a background thread.

```rust
#[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() -> windows_service::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(())
}
```

--------------------------------

### Create a service example

Source: https://docs.rs/windows-service/latest/src/windows_service/service_manager.rs.html

Example showing how to create a service using ServiceManager::local_computer with CREATE_SERVICE access and a ServiceInfo struct. The executable path is set to a placeholder.

```rust
use std::ffi::OsString;
use std::path::PathBuf;
use windows_service::service::{
    ServiceAccess, ServiceErrorControl, ServiceInfo, ServiceStartType, ServiceType,
};
use windows_service::service_manager::{ServiceManager, ServiceManagerAccess};

fn main() -> windows_service::Result<()> {
    let manager =
        ServiceManager::local_computer(None::<&str>, ServiceManagerAccess::CREATE_SERVICE)?;

    let my_service_info = ServiceInfo {
        name: OsString::from("my_service"),
        display_name: OsString::from("My service"),
        service_type: ServiceType::OWN_PROCESS,
        start_type: ServiceStartType::OnDemand,
        error_control: ServiceErrorControl::Normal,
        executable_path: PathBuf::from(r"C:\path\to\my\service.exe"),
        launch_arguments: vec![],
```

--------------------------------

### start function implementation

Source: https://docs.rs/windows-service/latest/src/windows_service/service_dispatcher.rs.html?search=std%3A%3Avec

The start function registers the service with the system and starts the service control dispatcher. It blocks the current thread until the service is stopped.

```rust
pub fn start(
    service_name: impl AsRef<OsStr>,
    service_main: extern "system" fn(u32, *mut *mut u16),
) -> Result<()> {
    let service_name = WideCString::from_os_str(service_name)
        .map_err(|_| Error::ArgumentHasNulByte("service name"))?;
    let service_table: &[Services::SERVICE_TABLE_ENTRYW] = &[
        Services::SERVICE_TABLE_ENTRYW {
            lpServiceName: service_name.as_ptr() as _,
            lpServiceProc: Some(service_main),
        },
        // the last item has to be { null, null }
        Services::SERVICE_TABLE_ENTRYW {
            lpServiceName: ptr::null_mut(),
            lpServiceProc: None,
        },
    ];

    let result = unsafe { Services::StartServiceCtrlDispatcherW(service_table.as_ptr()) };
    if result == 0 {
        Err(Error::Winapi(io::Error::last_os_error()))
    } else {
        Ok(())
    }
}
```

--------------------------------

### Start a service with arguments

Source: https://docs.rs/windows-service/latest/windows_service/service/struct.Service.html

Starts a service with the given arguments. Requires ServiceAccess::START and a service manager connection.

```rust
use std::ffi::OsStr;
use windows_service::service::ServiceAccess;
use windows_service::service_manager::{ServiceManager, ServiceManagerAccess};

let manager = ServiceManager::local_computer(None::<&str>, ServiceManagerAccess::CONNECT)?;
let my_service = manager.open_service("my_service", ServiceAccess::START)?;
my_service.start(&[OsStr::new("Started from Rust!")])?;
```

--------------------------------

### Pause and resume service example (pause_continue.rs)

Source: https://docs.rs/windows-service/latest/windows_service/service/struct.Service.html

Example from examples/pause_continue.rs (line 27) that pauses and resumes a service, defaulting to 'Winmgmt' if no argument is provided. Requires ServiceAccess::PAUSE_CONTINUE.

```rust
fn main() -> windows_service::Result<()> {
    use std::env;
    use windows_service::{
        service::ServiceAccess,
        service_manager::{ServiceManager, ServiceManagerAccess},
    };

    let service_name = env::args().nth(1).unwrap_or("Winmgmt".to_owned());

    let manager_access = ServiceManagerAccess::CONNECT;
    let service_manager = ServiceManager::local_computer(None::<&str>, manager_access)?;

    let service = service_manager.open_service(&service_name, ServiceAccess::PAUSE_CONTINUE)?;

    println!("Pause {}", service_name);
    let paused_state = service.pause()?;
    println!("{:?}", paused_state.current_state);

    println!("Resume {}", service_name);
    let resumed_state = service.resume()?;
    println!("{:?}", resumed_state.current_state);

    Ok(())
}
```

--------------------------------

### register and set_service_status example

Source: https://docs.rs/windows-service/latest/src/windows_service/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example showing how to register a service control handler and set the service status to Running.

```APIDOC
## register and set_service_status example

### Description
This example demonstrates how to register a system service event handler and set the service status to Running.

### Code Example
```rust
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(),
        // Unused for setting status
        process_id: None,
    };

    // Tell the system that the service is running now
    status_handle.set_service_status(next_status)?;

    // Do some work

    Ok(())
}
```

### Notes
- `ServiceStatusHandle` is safe to clone and use from any thread.
- 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>
```

--------------------------------

### Manage service failure actions with windows_service

Source: https://docs.rs/windows-service/latest/windows_service/service/struct.Service.html

Example from examples/service_failure_actions.rs (line 85) showing how to create a service, update its failure actions, query them, enable failure actions on non-crash failures, and delete the service. Requires ServiceManagerAccess::CONNECT | CREATE_SERVICE and ServiceAccess::QUERY_CONFIG | CHANGE_CONFIG | START | DELETE. The service runs as System and uses a command of "ping 127.0.0.1" for the RunCommand action.

```rust
fn main() -> windows_service::Result<()> {
    use std::ffi::OsString;
    use std::time::Duration;
    use windows_service::{
        service::{
            ServiceAccess, ServiceAction, ServiceActionType, ServiceErrorControl,
            ServiceFailureActions, ServiceFailureResetPeriod, ServiceInfo, ServiceStartType,
            ServiceType,
        },
        service_manager::{ServiceManager, ServiceManagerAccess},
    };

    const SERVICE_NAME: &str = "service_failure_actions_example";

    let manager_access = ServiceManagerAccess::CONNECT | ServiceManagerAccess::CREATE_SERVICE;
    let service_manager = ServiceManager::local_computer(None::<&str>, manager_access)?;

    let service_binary_path = ::std::env::current_exe()
        .unwrap()
        .with_file_name("service_failure_actions.exe");

    let service_info = ServiceInfo {
        name: OsString::from(SERVICE_NAME),
        display_name: OsString::from("Service Failure Actions Example"),
        service_type: ServiceType::OWN_PROCESS,
        start_type: ServiceStartType::OnDemand,
        error_control: ServiceErrorControl::Normal,
        executable_path: service_binary_path,
        launch_arguments: vec![],
        dependencies: vec![],
        account_name: None, // run as System
        account_password: None,
    };

    let service_access = ServiceAccess::QUERY_CONFIG
        | ServiceAccess::CHANGE_CONFIG
        | ServiceAccess::START
        | ServiceAccess::DELETE;

    println!("Create or open the service {}", SERVICE_NAME);
    let service = service_manager
        .create_service(&service_info, service_access)
        .or(service_manager.open_service(SERVICE_NAME, service_access))?;

    let actions = vec![
        ServiceAction {
            action_type: ServiceActionType::Restart,
            delay: Duration::from_secs(5),
        },
        ServiceAction {
            action_type: ServiceActionType::RunCommand,
            delay: Duration::from_secs(10),
        },
        ServiceAction {
            action_type: ServiceActionType::None,
            delay: Duration::default(),
        },
    ];

    println!("Update failure actions");
    let failure_actions = ServiceFailureActions {
        reset_period: ServiceFailureResetPeriod::After(Duration::from_secs(86400 * 2)),
        reboot_msg: None,
        command: Some(OsString::from("ping 127.0.0.1")),
        actions: Some(actions),
    };
    service.update_failure_actions(failure_actions)?;

    println!("Query failure actions");
    let updated_failure_actions = service.get_failure_actions()?;
    println!("{:#?}", updated_failure_actions);

    println!("Enable failure actions on non-crash failures");
    service.set_failure_actions_on_non_crash_failures(true)?;

    println!("Query failure actions on non-crash failures enabled");
    let failure_actions_flag = service.get_failure_actions_on_non_crash_failures()?;
    println!(
        "Failure actions on non-crash failures enabled: {}",
        failure_actions_flag
    );

    println!("Delete the service {}", SERVICE_NAME);
    service.delete()?;

    Ok(())
}
```

--------------------------------

### is_ok() Example

Source: https://docs.rs/windows-service/latest/windows_service/type.Result.html

Example of using the is_ok method to check if a Result is Ok.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

--------------------------------

### is_ok_and() Example

Source: https://docs.rs/windows-service/latest/windows_service/type.Result.html

Example of using the is_ok_and method to check if a Result is Ok and the value matches a predicate.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Full service_failure_actions.rs example

Source: https://docs.rs/windows-service/latest/windows_service/service/struct.Service.html?search=u32+-%3E+bool

Complete example from `examples/service_failure_actions.rs` that creates or opens a service, updates failure actions, queries them, enables non-crash failure actions, and deletes the service. Requires `ServiceManagerAccess::CREATE_SERVICE` and appropriate service access. Uses `ServiceStartType::OnDemand` and runs as System.

```rust
2fn main() -> windows_service::Result<()> {
3    use std::ffi::OsString;
4    use std::time::Duration;
5    use windows_service::{
6        service::{
7            ServiceAccess, ServiceAction, ServiceActionType, ServiceErrorControl,
8            ServiceFailureActions, ServiceFailureResetPeriod, ServiceInfo, ServiceStartType,
9            ServiceType,
10        },
11        service_manager::{ServiceManager, ServiceManagerAccess},
12    };
13
14    const SERVICE_NAME: &str = "service_failure_actions_example";
15
16    let manager_access = ServiceManagerAccess::CONNECT | ServiceManagerAccess::CREATE_SERVICE;
17    let service_manager = ServiceManager::local_computer(None::<&str>, manager_access)?;
18
19    let service_binary_path = ::std::env::current_exe()
20        .unwrap()
21        .with_file_name("service_failure_actions.exe");
22
23    let service_info = ServiceInfo {
24        name: OsString::from(SERVICE_NAME),
25        display_name: OsString::from("Service Failure Actions Example"),
26        service_type: ServiceType::OWN_PROCESS,
27        start_type: ServiceStartType::OnDemand,
28        error_control: ServiceErrorControl::Normal,
29        executable_path: service_binary_path,
30        launch_arguments: vec![],
31        dependencies: vec![],
32        account_name: None, // run as System
33        account_password: None,
34    };
35
36    let service_access = ServiceAccess::QUERY_CONFIG
37        | ServiceAccess::CHANGE_CONFIG
38        | ServiceAccess::START
39        | ServiceAccess::DELETE;
40
41    println!("Create or open the service {}", SERVICE_NAME);
42    let service = service_manager
43        .create_service(&service_info, service_access)
44        .or(service_manager.open_service(SERVICE_NAME, service_access))?;
45
46    let actions = vec![
47        ServiceAction {
48            action_type: ServiceActionType::Restart,
49            delay: Duration::from_secs(5),
50        },
51        ServiceAction {
52            action_type: ServiceActionType::RunCommand,
53            delay: Duration::from_secs(10),
54        },
55        ServiceAction {
56            action_type: ServiceActionType::None,
57            delay: Duration::default(),
58        },
59    ];
60
61    println!("Update failure actions");
62    let failure_actions = ServiceFailureActions {
63        reset_period: ServiceFailureResetPeriod::After(Duration::from_secs(86400 * 2)),
64        reboot_msg: None,
65        command: Some(OsString::from("ping 127.0.0.1")),
66        actions: Some(actions),
67    };
68    service.update_failure_actions(failure_actions)?;
69
70    println!("Query failure actions");
71    let updated_failure_actions = service.get_failure_actions()?;
72    println!("{:#?}", updated_failure_actions);
73
74    println!("Enable failure actions on non-crash failures");
75    service.set_failure_actions_on_non_crash_failures(true)?;
76
77    println!("Query failure actions on non-crash failures enabled");
78    let failure_actions_flag = service.get_failure_actions_on_non_crash_failures()?;
79    println!(
80        "Failure actions on non-crash failures enabled: {}",
81        failure_actions_flag
82    );
83
84    println!("Delete the service {}", SERVICE_NAME);
85    service.delete()?;
86
    Ok(())
87}
```

--------------------------------

### Define and start a Windows service with define_windows_service!

Source: https://docs.rs/windows-service/latest/index.html

Shows the minimal structure for a Windows service: define a service entry function with `define_windows_service!`, then register it with `service_dispatcher::start` in `main`. The service entry point runs on a background thread after `start` is called.

```rust
#[macro_use]
extern crate windows_service;

use std::ffi::OsString;
use windows_service::{Result, 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<()> {
    // 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(())
}
```

--------------------------------

### as_mut example

Source: https://docs.rs/windows-service/latest/windows_service/type.Result.html

Demonstrates using Result::as_mut to get mutable references to the contained values, allowing in-place mutation of Ok or Err variants.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### and_then: chain fallible operations

Source: https://docs.rs/windows-service/latest/windows_service/type.Result.html

Shows how to use Result::and_then to chain operations that may fail. The first example uses a function sq_then_to_string that returns a Result. The second example uses metadata() and modified() to get file modification times, handling errors with ErrorKind::NotFound.

```rust
assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));
assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));
assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));
```

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Install service and set description with set_description

Source: https://docs.rs/windows-service/latest/windows_service/service/struct.Service.html

Installs a Windows service named 'ping_service' and sets its description using set_description. Requires ServiceAccess::CHANGE_CONFIG. The executable path points to ping_service.exe in the current directory.

```rust
fn main() -> windows_service::Result<()> {
    use std::ffi::OsString;
    use windows_service::{
        service::{ServiceAccess, ServiceErrorControl, ServiceInfo, ServiceStartType, ServiceType},
        service_manager::{ServiceManager, ServiceManagerAccess},
    };

    let manager_access = ServiceManagerAccess::CONNECT | ServiceManagerAccess::CREATE_SERVICE;
    let service_manager = ServiceManager::local_computer(None::<&str>, manager_access)?;

    // This example installs the service defined in `examples/ping_service.rs`.
    // In the real world code you would set the executable path to point to your own binary
    // that implements windows service.
    let service_binary_path = ::std::env::current_exe()
        .unwrap()
        .with_file_name("ping_service.exe");

    let service_info = ServiceInfo {
        name: OsString::from("ping_service"),
        display_name: OsString::from("Ping service"),
        service_type: ServiceType::OWN_PROCESS,
        start_type: ServiceStartType::OnDemand,
        error_control: ServiceErrorControl::Normal,
        executable_path: service_binary_path,
        launch_arguments: vec![],
        dependencies: vec![],
        account_name: None, // run as System
        account_password: None,
    };
    let service = service_manager.create_service(&service_info, ServiceAccess::CHANGE_CONFIG)?;
    service.set_description("Windows service example from windows-service-rs")?;
    Ok(())
}
```

--------------------------------

### Get service name from display name with ServiceManager::service_name_from_display_name

Source: https://docs.rs/windows-service/latest/src/windows_service/service_manager.rs.html

Retrieves the service name from a display name using ServiceManager::service_name_from_display_name. The example passes a display name string and receives the corresponding service name as an OsString. Requires a connected ServiceManager with CONNECT access.

```rust
use windows_service::service_manager::{ServiceManager, ServiceManagerAccess};

# fn main() -> windows_service::Result<()> {
let manager = ServiceManager::local_computer(None::<&str>, ServiceManagerAccess::CONNECT)?;
let my_service_name = manager.service_name_from_display_name("My Service Display Name")?;
# Ok(())
# }
```

--------------------------------

### Service::start

Source: https://docs.rs/windows-service/latest/src/windows_service/service.rs.html

Starts the service with the given arguments.

```APIDOC
## Service::start

### Description
Starts the service with the given arguments.

### Method
start

### Signature
pub fn start<S: AsRef<OsStr>>(&self, service_arguments: &[S]) -> crate::Result<()>

### Parameters
- **service_arguments** (slice of S where S: AsRef<OsStr>) - Required - The arguments to pass to the service on start.

### Returns
- **crate::Result<()>** - Ok(()) on success, or an error.

### Example
```rust
use std::ffi::OsStr;
use windows_service::service::ServiceAccess;
use windows_service::service_manager::{ServiceManager, ServiceManagerAccess};

let manager = ServiceManager::local_computer(None::<&str>, ServiceManagerAccess::CONNECT)?;
let my_service = manager.open_service("my_service", ServiceAccess::START)?;
my_service.start(&[OsStr::new("Started from Rust!")])?;
```
```

--------------------------------

### PowerSchemePersonality conversion from GUID

Source: https://docs.rs/windows-service/latest/src/windows_service/service.rs.html?search=std%3A%3Avec

Converts a raw GUID to a PowerSchemePersonality enum. Matches known GUIDs for high performance, power saver, and typical power savings, returning an error for unknown GUIDs.

```rust
Ok(PowerSchemePersonality::HighPerformance)
        }
        x if is_equal_guid(x, &SystemServices::GUID_MAX_POWER_SAVINGS) => {
            Ok(PowerSchemePersonality::PowerSaver)
        }
        x if is_equal_guid(x, &SystemServices::GUID_TYPICAL_POWER_SAVINGS) => {
            Ok(PowerSchemePersonality::Automatic)
        }
        x => Err(ParseRawError::InvalidGuid(string_from_guid(x))),
    }
}
```

--------------------------------

### ServiceManager::local_computer and create_service

Source: https://docs.rs/windows-service/latest/windows_service/service_manager/struct.ServiceManager.html?search=u32+-%3E+bool

Example showing how to connect to the local service manager and create a new Windows service.

```APIDOC
## ServiceManager::local_computer and create_service

### Description
Connects to the local service manager and creates a new Windows service with the specified configuration.

### Method
N/A (Rust function)

### Endpoint
N/A (Rust API)

### Parameters
#### local_computer
- **machine_name** (Option<&str>) - Optional - The name of the target machine. `None` for local computer.
- **access** (ServiceManagerAccess) - Required - Access rights for the service manager.

#### create_service
- **service_info** (ServiceInfo) - Required - Configuration for the new service.
- **access** (ServiceAccess) - Required - Access rights for the service.

### Request Example
```rust
let manager = ServiceManager::local_computer(None::<&str>, ServiceManagerAccess::CREATE_SERVICE)?;

let my_service_info = ServiceInfo {
    name: OsString::from("my_service"),
    display_name: OsString::from("My service"),
    service_type: ServiceType::OWN_PROCESS,
    start_type: ServiceStartType::OnDemand,
    error_control: ServiceErrorControl::Normal,
    executable_path: PathBuf::from(r"C:\path\to\my\service.exe"),
    launch_arguments: vec![],
    dependencies: vec![],
    account_name: None, // run as System
    account_password: None,
};

let my_service = manager.create_service(&my_service_info, ServiceAccess::QUERY_STATUS)?;
```

### Response
#### Success Response
- Returns `Result<ServiceManager>` for `local_computer` and `Result<Service>` for `create_service`.

#### Response Example
```rust
Ok(manager)
Ok(my_service)
```

### Error Handling
- Returns `windows_service::Result` which may contain an error if the operation fails.
```

--------------------------------

### Uninstall service example (uninstall_service.rs)

Source: https://docs.rs/windows-service/latest/windows_service/service/struct.Service.html

Example from examples/uninstall_service.rs (line 26) that deletes a service, stops it if needed, and polls until it is removed from the database. Requires ServiceAccess::QUERY_STATUS | STOP | DELETE and uses ERROR_SERVICE_DOES_NOT_EXIST to detect deletion.

```rust
fn main() -> windows_service::Result<()> {
    use std::{
        thread::sleep,
        time::{Duration, Instant},
    };

    use windows_service::{
        service::{ServiceAccess, ServiceState},
        service_manager::{ServiceManager, ServiceManagerAccess},
    };
    use windows_sys::Win32::Foundation::ERROR_SERVICE_DOES_NOT_EXIST;

    let manager_access = ServiceManagerAccess::CONNECT;
    let service_manager = ServiceManager::local_computer(None::<&str>, manager_access)?;

    let service_access = ServiceAccess::QUERY_STATUS | ServiceAccess::STOP | ServiceAccess::DELETE;
    let service = service_manager.open_service("ping_service", service_access)?;

    // The service will be marked for deletion as long as this function call succeeds.
    // However, it will not be deleted from the database until it is stopped and all open handles to it are closed.
    service.delete()?;
    // Our handle to it is not closed yet. So we can still query it.
    if service.query_status()?.current_state != ServiceState::Stopped {
        // If the service cannot be stopped, it will be deleted when the system restarts.
        service.stop()?;
    }
    // Explicitly close our open handle to the service. This is automatically called when `service` goes out of scope.
    drop(service);

    // Win32 API does not give us a way to wait for service deletion.
    // To check if the service is deleted from the database, we have to poll it ourselves.
    let start = Instant::now();
    let timeout = Duration::from_secs(5);
    while start.elapsed() < timeout {
        if let Err(windows_service::Error::Winapi(e)) =
            service_manager.open_service("ping_service", ServiceAccess::QUERY_STATUS)
        {
            if e.raw_os_error() == Some(ERROR_SERVICE_DOES_NOT_EXIST as i32) {
                println!("ping_service is deleted.");
                return Ok(());
            }
        }
        sleep(Duration::from_secs(1));
    }
    println!("ping_service is marked for deletion.");

    Ok(())
}
```

--------------------------------

### Parse PowerBroadcastSetting from raw GUID and data

Source: https://docs.rs/windows-service/latest/src/windows_service/service.rs.html?search=std%3A%3Avec

Matches Windows GUIDs to parse power broadcast settings. Returns PowerBroadcastSetting variants or ParseRawError::InvalidGuid for unknown GUIDs.

```rust
x if is_equal_guid(x, &SystemServices::GUID_POWER_SAVING_STATUS) => {
    let battery_saver_state = *(data as *const u32);
    Ok(PowerBroadcastSetting::PowerSavingStatus(
        BatterySaverState::from_raw(battery_saver_state)?,
    ))
}
x if is_equal_guid(x, &SystemServices::GUID_POWERSCHEME_PERSONALITY) => {
    let guid = *(data as *const GUID);
    Ok(PowerBroadcastSetting::PowerSchemePersonality(
        PowerSchemePersonality::from_guid(&guid)?,
    ))
}
x if is_equal_guid(x, &SystemServices::GUID_SYSTEM_AWAYMODE) => {
    let away_mode_state = *(data as *const u32);
    Ok(PowerBroadcastSetting::SystemAwayMode(
        AwayModeState::from_raw(away_mode_state)?,
    ))
}
x if is_equal_guid(x, &SystemServices::GUID_LIDSWITCH_STATE_CHANGE) => {
    let lid_switch_state = *(data as *const u32);
    Ok(PowerBroadcastSetting::LidSwitchStateChange(
        LidSwitchStateChange::from_raw(lid_switch_state)?,
    ))
}
x => Err(ParseRawError::InvalidGuid(string_from_guid(x))),
```

--------------------------------

### Rust example: configure and query service failure actions

Source: https://docs.rs/windows-service/latest/src/service_failure_actions/service_failure_actions.rs.html?search=

Complete Rust program for the windows-service crate. It creates or opens a service, sets failure actions (Restart, RunCommand, None), updates and queries them, enables failure actions on non-crash failures, and deletes the service. Requires Windows and the windows-service crate.

```rust
#[cfg(windows)]
fn main() -> windows_service::Result<()> {
    use std::ffi::OsString;
    use std::time::Duration;
    use windows_service::{
        service::{
            ServiceAccess, ServiceAction, ServiceActionType, ServiceErrorControl,
            ServiceFailureActions, ServiceFailureResetPeriod, ServiceInfo, ServiceStartType,
            ServiceType,
        },
        service_manager::{ServiceManager, ServiceManagerAccess},
    };

    const SERVICE_NAME: &str = "service_failure_actions_example";

    let manager_access = ServiceManagerAccess::CONNECT | ServiceManagerAccess::CREATE_SERVICE;
    let service_manager = ServiceManager::local_computer(None::<&str>, manager_access)?;

    let service_binary_path = ::std::env::current_exe()
        .unwrap()
        .with_file_name("service_failure_actions.exe");

    let service_info = ServiceInfo {
        name: OsString::from(SERVICE_NAME),
        display_name: OsString::from("Service Failure Actions Example"),
        service_type: ServiceType::OWN_PROCESS,
        start_type: ServiceStartType::OnDemand,
        error_control: ServiceErrorControl::Normal,
        executable_path: service_binary_path,
        launch_arguments: vec![],
        dependencies: vec![],
        account_name: None, // run as System
        account_password: None,
    };

    let service_access = ServiceAccess::QUERY_CONFIG
        | ServiceAccess::CHANGE_CONFIG
        | ServiceAccess::START
        | ServiceAccess::DELETE;

    println!("Create or open the service {}", SERVICE_NAME);
    let service = service_manager
        .create_service(&service_info, service_access)
        .or(service_manager.open_service(SERVICE_NAME, service_access))?;

    let actions = vec![
        ServiceAction {
            action_type: ServiceActionType::Restart,
            delay: Duration::from_secs(5),
        },
        ServiceAction {
            action_type: ServiceActionType::RunCommand,
            delay: Duration::from_secs(10),
        },
        ServiceAction {
            action_type: ServiceActionType::None,
            delay: Duration::default(),
        },
    ];

    println!("Update failure actions");
    let failure_actions = ServiceFailureActions {
        reset_period: ServiceFailureResetPeriod::After(Duration::from_secs(86400 * 2)),
        reboot_msg: None,
        command: Some(OsString::from("ping 127.0.0.1")),
        actions: Some(actions),
    };
    service.update_failure_actions(failure_actions)?;

    println!("Query failure actions");
    let updated_failure_actions = service.get_failure_actions()?;
    println!("{:#?}", updated_failure_actions);

    println!("Enable failure actions on non-crash failures");
    service.set_failure_actions_on_non_crash_failures(true)?;

    println!("Query failure actions on non-crash failures enabled");
    let failure_actions_flag = service.get_failure_actions_on_non_crash_failures()?;
    println!(
        "Failure actions on non-crash failures enabled: {}",
        failure_actions_flag
    );

    println!("Delete the service {}", SERVICE_NAME);
    service.delete()?;

    Ok(())
}

#[cfg(not(windows))]
fn main() {
    panic!("This program is only intended to run on Windows.");
}

```

--------------------------------

### is_err() Example

Source: https://docs.rs/windows-service/latest/windows_service/type.Result.html

Example of using the is_err method to check if a Result is Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

--------------------------------

### Query Windows service configuration with windows-service

Source: https://docs.rs/windows-service/latest/src/service_config/service_config.rs.html?search=std%3A%3Avec

Opens a service by name (default 'netlogon') and prints its configuration using query_config(). Requires Windows; panics otherwise.

```rust
#[cfg(windows)]
fn main() -> windows_service::Result<()> {
    use std::env;
    use windows_service::{
        service::ServiceAccess,
        service_manager::{ServiceManager, ServiceManagerAccess},
    };

    let service_name = env::args().nth(1).unwrap_or("netlogon".to_owned());

    let manager_access = ServiceManagerAccess::CONNECT;
    let service_manager = ServiceManager::local_computer(None::<&str>, manager_access)?;

    let service = service_manager.open_service(service_name, ServiceAccess::QUERY_CONFIG)?;

    let config = service.query_config()?;
    println!("{:#?}", config);
    Ok(())
}

#[cfg(not(windows))]
fn main() {
    panic!("This program is only intended to run on Windows.");
}
```

--------------------------------

### Result::expect panic example

Source: https://docs.rs/windows-service/latest/windows_service/type.Result.html

Example for `Result::expect`, which returns the contained `Ok` value or panics with the given message and the `Err` content. This example demonstrates the panic behavior when the result is `Err`.

```rust
let x: Result<u32, &str> = Err("emergency failure");
x.expect("Testing expect"); // panics with `Testing expect: emergency failure`
```

--------------------------------

### start

Source: https://docs.rs/windows-service/latest/src/windows_service/service_dispatcher.rs.html?search=std%3A%3Avec

Starts the Windows service control dispatcher, blocking the current thread until the service is stopped.

```APIDOC
## [FUNCTION] start

### Description
Start service control dispatcher. Once started the service control dispatcher blocks the current thread execution until the service is stopped. Upon successful initialization, system calls the `service_main` on background thread. On failure: immediately returns an error, no threads are spawned.

### Signature
```rust
pub fn start(
    service_name: impl AsRef<OsStr>,
    service_main: extern "system" fn(u32, *mut *mut u16),
) -> Result<()>
```

### Parameters
- **service_name** (impl AsRef<OsStr>) - Required - The name of the service to register with the system.
- **service_main** (extern "system" fn(u32, *mut *mut u16)) - Required - The generated service main callback (e.g., from `define_windows_service!`).

### Return Value
- **Result<()>** - Returns `Ok(())` on success, or an `Error` on failure.

### Example
```rust
#[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() -> windows_service::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(())
}
```
```

--------------------------------

### cloned() Example for &T

Source: https://docs.rs/windows-service/latest/windows_service/type.Result.html

Example of using the cloned method on a Result<&T, E> to clone the Ok value.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### copied() Example for &T

Source: https://docs.rs/windows-service/latest/windows_service/type.Result.html

Example of using the copied method on a Result<&T, E> to copy the Ok value.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```
Tokens:
Raw