Struct UniServiceManager 

pub struct UniServiceManager { /* private fields */ }

A service manager to manage services on the current system. It uses platform-specific implementations behind the scenes to perform the actual service management, but provides a unified interface regardless of the platform.

Implementations

impl UniServiceManager

pub fn new( name: impl Into<OsString>, prefix: impl Into<OsString>, user: bool, ) -> UniResult<Self, ServiceErrKind>

Creates a new service manager for the given service name. The prefix is a java-style reverse domain name prefix (e.g. com.example.) and is only used on macOS (ignored on other platforms). If user is true, the service applies directly to the current user only. On Windows, user level services require administrator privileges to manage and won’t start until the first logon.

Examples found in repository

examples/manager.rs (line 17)

fn run(
    service_name: &str,
    display_name: &str,
    description: &str,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Windows user services require a new logon before they can be started, so we will use a system service on Windows.
    // NOTE: Windows services always require elevated privileges to install, so run this example as administrator.
    let user = !UniServiceManager::capabilities()
        .contains(ServiceCapabilities::USER_SERVICES_REQUIRE_NEW_LOGON);
    let user_manager = UniServiceManager::new(service_name, "com.example.", user)?;

    let mut bin_path = std::env::current_exe().unwrap();
    bin_path.set_file_name(service_name);

    if !bin_path.exists() {
        return Err(format!(
            "Executable not found: {}. Make sure to build the service examples first.",
            bin_path.display()
        )
        .into());
    }

    let spec = ServiceSpec::new(bin_path)
        .arg("service")?
        .display_name(display_name)?
        .description(description)?;

    print!("Installing service '{service_name}'...",);
    user_manager.install_and_wait(&spec, TIMEOUT)?;
    println!("done");

    print!("Starting service '{service_name}'...");
    user_manager.start_and_wait(TIMEOUT)?;
    println!("done");

    io::stdout().flush()?;
    println!("Press Enter to stop the service...");
    let mut buffer = String::new();
    io::stdin().read_line(&mut buffer)?;

    print!("Stopping service '{service_name}'...");
    user_manager.stop_and_wait(TIMEOUT)?;
    println!("done");

    print!("Uninstalling service '{service_name}'...");
    user_manager.uninstall_and_wait(TIMEOUT)?;
    println!("done");

    Ok(())
}

pub fn capabilities() -> ServiceCapabilities

Gets the capabilities of the underlying platform service manager.

Examples found in repository

examples/manager.rs (line 15)

fn run(
    service_name: &str,
    display_name: &str,
    description: &str,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Windows user services require a new logon before they can be started, so we will use a system service on Windows.
    // NOTE: Windows services always require elevated privileges to install, so run this example as administrator.
    let user = !UniServiceManager::capabilities()
        .contains(ServiceCapabilities::USER_SERVICES_REQUIRE_NEW_LOGON);
    let user_manager = UniServiceManager::new(service_name, "com.example.", user)?;

    let mut bin_path = std::env::current_exe().unwrap();
    bin_path.set_file_name(service_name);

    if !bin_path.exists() {
        return Err(format!(
            "Executable not found: {}. Make sure to build the service examples first.",
            bin_path.display()
        )
        .into());
    }

    let spec = ServiceSpec::new(bin_path)
        .arg("service")?
        .display_name(display_name)?
        .description(description)?;

    print!("Installing service '{service_name}'...",);
    user_manager.install_and_wait(&spec, TIMEOUT)?;
    println!("done");

    print!("Starting service '{service_name}'...");
    user_manager.start_and_wait(TIMEOUT)?;
    println!("done");

    io::stdout().flush()?;
    println!("Press Enter to stop the service...");
    let mut buffer = String::new();
    io::stdin().read_line(&mut buffer)?;

    print!("Stopping service '{service_name}'...");
    user_manager.stop_and_wait(TIMEOUT)?;
    println!("done");

    print!("Uninstalling service '{service_name}'...");
    user_manager.uninstall_and_wait(TIMEOUT)?;
    println!("done");

    Ok(())
}

pub fn fully_qualified_name(&self) -> Cow<'_, OsStr>

Gets the fully qualified name of the service. Note that Windows user services have a dynamic name that changes between sessions.

pub fn is_user_service(&self) -> bool

true if the service is a user service, false if it is a system service.

pub fn install(&self, spec: &ServiceSpec) -> UniResult<(), ServiceErrKind>

Installs the service. The program is the path to the executable to run when the service starts. The args are the arguments to pass to the executable. The display_name is the name to display to the user. The desc is the description of the service. After the method returns successfully, the service may or may not be installed yet, as this is platform-dependent. An error is returned if the service is already installed or if the installation fails.

pub fn install_and_wait( &self, spec: &ServiceSpec, timeout: Duration, ) -> UniResult<ServiceStatus, ServiceErrKind>

Installs the service and waits for it to reach the expected status. The timeout is the maximum time to wait for the service to reach that status. The expected status is Running if autostart is enabled and the service starts immediately after install, otherwise Stopped. The current status is returned when successful.

Examples found in repository

examples/manager.rs (line 36)

fn run(
    service_name: &str,
    display_name: &str,
    description: &str,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Windows user services require a new logon before they can be started, so we will use a system service on Windows.
    // NOTE: Windows services always require elevated privileges to install, so run this example as administrator.
    let user = !UniServiceManager::capabilities()
        .contains(ServiceCapabilities::USER_SERVICES_REQUIRE_NEW_LOGON);
    let user_manager = UniServiceManager::new(service_name, "com.example.", user)?;

    let mut bin_path = std::env::current_exe().unwrap();
    bin_path.set_file_name(service_name);

    if !bin_path.exists() {
        return Err(format!(
            "Executable not found: {}. Make sure to build the service examples first.",
            bin_path.display()
        )
        .into());
    }

    let spec = ServiceSpec::new(bin_path)
        .arg("service")?
        .display_name(display_name)?
        .description(description)?;

    print!("Installing service '{service_name}'...",);
    user_manager.install_and_wait(&spec, TIMEOUT)?;
    println!("done");

    print!("Starting service '{service_name}'...");
    user_manager.start_and_wait(TIMEOUT)?;
    println!("done");

    io::stdout().flush()?;
    println!("Press Enter to stop the service...");
    let mut buffer = String::new();
    io::stdin().read_line(&mut buffer)?;

    print!("Stopping service '{service_name}'...");
    user_manager.stop_and_wait(TIMEOUT)?;
    println!("done");

    print!("Uninstalling service '{service_name}'...");
    user_manager.uninstall_and_wait(TIMEOUT)?;
    println!("done");

    Ok(())
}

pub fn install_if_needed_and_start( &self, spec: &ServiceSpec, timeout: Duration, ) -> UniResult<(), ServiceErrKind>

Installs the service if it is not already installed and starts it. The timeout is the maximum time to wait for the service to reach the expected status. The expected status is Running if autostart is enabled and the service starts immediately after install, otherwise Stopped. The current status is returned when successful.

pub fn uninstall(&self) -> UniResult<(), ServiceErrKind>

Uninstalls the service. After the method returns successfully, the service may or may not be uninstalled yet, as this is platform-dependent. An error is returned if the service is not installed, if the service is not stopped, or if the uninstallation fails.

pub fn uninstall_and_wait( &self, timeout: Duration, ) -> UniResult<(), ServiceErrKind>

Uninstalls the service and waits for it to reach the expected status of NotInstalled. The timeout is the maximum time to wait for the service to reach that status.

Examples found in repository

examples/manager.rs (line 53)

fn run(
    service_name: &str,
    display_name: &str,
    description: &str,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Windows user services require a new logon before they can be started, so we will use a system service on Windows.
    // NOTE: Windows services always require elevated privileges to install, so run this example as administrator.
    let user = !UniServiceManager::capabilities()
        .contains(ServiceCapabilities::USER_SERVICES_REQUIRE_NEW_LOGON);
    let user_manager = UniServiceManager::new(service_name, "com.example.", user)?;

    let mut bin_path = std::env::current_exe().unwrap();
    bin_path.set_file_name(service_name);

    if !bin_path.exists() {
        return Err(format!(
            "Executable not found: {}. Make sure to build the service examples first.",
            bin_path.display()
        )
        .into());
    }

    let spec = ServiceSpec::new(bin_path)
        .arg("service")?
        .display_name(display_name)?
        .description(description)?;

    print!("Installing service '{service_name}'...",);
    user_manager.install_and_wait(&spec, TIMEOUT)?;
    println!("done");

    print!("Starting service '{service_name}'...");
    user_manager.start_and_wait(TIMEOUT)?;
    println!("done");

    io::stdout().flush()?;
    println!("Press Enter to stop the service...");
    let mut buffer = String::new();
    io::stdin().read_line(&mut buffer)?;

    print!("Stopping service '{service_name}'...");
    user_manager.stop_and_wait(TIMEOUT)?;
    println!("done");

    print!("Uninstalling service '{service_name}'...");
    user_manager.uninstall_and_wait(TIMEOUT)?;
    println!("done");

    Ok(())
}

pub fn stop_if_needed_and_uninstall( &self, timeout: Duration, ) -> UniResult<(), ServiceErrKind>

Stops the service if it is running and uninstalls it. If the service is already stopped, it will be uninstalled without further action. The timeout is the maximum time to wait for the service to reach each expected status.

pub fn start(&self) -> UniResult<(), ServiceErrKind>

Starts the service. After the method returns successfully, the service may or may not be started yet, as this is platform-dependent. An error is returned if the service is not stopped or if the starting fails.

pub fn start_and_wait(&self, timeout: Duration) -> UniResult<(), ServiceErrKind>

Starts the service and waits for it to reach the expected status of Running. The timeout is the maximum time to wait for the service to reach that status.

Examples found in repository

examples/manager.rs (line 40)

fn run(
    service_name: &str,
    display_name: &str,
    description: &str,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Windows user services require a new logon before they can be started, so we will use a system service on Windows.
    // NOTE: Windows services always require elevated privileges to install, so run this example as administrator.
    let user = !UniServiceManager::capabilities()
        .contains(ServiceCapabilities::USER_SERVICES_REQUIRE_NEW_LOGON);
    let user_manager = UniServiceManager::new(service_name, "com.example.", user)?;

    let mut bin_path = std::env::current_exe().unwrap();
    bin_path.set_file_name(service_name);

    if !bin_path.exists() {
        return Err(format!(
            "Executable not found: {}. Make sure to build the service examples first.",
            bin_path.display()
        )
        .into());
    }

    let spec = ServiceSpec::new(bin_path)
        .arg("service")?
        .display_name(display_name)?
        .description(description)?;

    print!("Installing service '{service_name}'...",);
    user_manager.install_and_wait(&spec, TIMEOUT)?;
    println!("done");

    print!("Starting service '{service_name}'...");
    user_manager.start_and_wait(TIMEOUT)?;
    println!("done");

    io::stdout().flush()?;
    println!("Press Enter to stop the service...");
    let mut buffer = String::new();
    io::stdin().read_line(&mut buffer)?;

    print!("Stopping service '{service_name}'...");
    user_manager.stop_and_wait(TIMEOUT)?;
    println!("done");

    print!("Uninstalling service '{service_name}'...");
    user_manager.uninstall_and_wait(TIMEOUT)?;
    println!("done");

    Ok(())
}

pub fn stop(&self) -> UniResult<(), ServiceErrKind>

Stops the service. After the method returns successfully, the service may or may not be stopped yet, as this is platform-dependent. An error is returned if the service is not running or if the stopping fails.

pub fn stop_and_wait(&self, timeout: Duration) -> UniResult<(), ServiceErrKind>

Stops the service and waits for it to reach the expected status of Stopped. The timeout is the maximum time to wait for the service to reach that status.

Examples found in repository

examples/manager.rs (line 49)

fn run(
    service_name: &str,
    display_name: &str,
    description: &str,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Windows user services require a new logon before they can be started, so we will use a system service on Windows.
    // NOTE: Windows services always require elevated privileges to install, so run this example as administrator.
    let user = !UniServiceManager::capabilities()
        .contains(ServiceCapabilities::USER_SERVICES_REQUIRE_NEW_LOGON);
    let user_manager = UniServiceManager::new(service_name, "com.example.", user)?;

    let mut bin_path = std::env::current_exe().unwrap();
    bin_path.set_file_name(service_name);

    if !bin_path.exists() {
        return Err(format!(
            "Executable not found: {}. Make sure to build the service examples first.",
            bin_path.display()
        )
        .into());
    }

    let spec = ServiceSpec::new(bin_path)
        .arg("service")?
        .display_name(display_name)?
        .description(description)?;

    print!("Installing service '{service_name}'...",);
    user_manager.install_and_wait(&spec, TIMEOUT)?;
    println!("done");

    print!("Starting service '{service_name}'...");
    user_manager.start_and_wait(TIMEOUT)?;
    println!("done");

    io::stdout().flush()?;
    println!("Press Enter to stop the service...");
    let mut buffer = String::new();
    io::stdin().read_line(&mut buffer)?;

    print!("Stopping service '{service_name}'...");
    user_manager.stop_and_wait(TIMEOUT)?;
    println!("done");

    print!("Uninstalling service '{service_name}'...");
    user_manager.uninstall_and_wait(TIMEOUT)?;
    println!("done");

    Ok(())
}

pub fn status(&self) -> UniResult<ServiceStatus, ServiceErrKind>

Gets the current status of the service. It returns an error if the service is not installed or if the status cannot be determined.

pub fn wait_for_status( &self, desired_status: ServiceStatus, timeout: Duration, ) -> UniResult<(), ServiceErrKind>

Waits for the service to reach the desired status. It returns an error if the service is not installed the status cannot be determined, or if the service does not reach the desired status before the timeout.