Struct DesktopApp 

pub struct DesktopApp { /* private fields */ }

Validated Windows desktop app identity used by the app-data and single-instance helpers.

DesktopApp keeps a validated app identity in one place and uses it for app-data paths and single-instance locking. It does not own any global state.

Examples

let app = win_desktop_utils::DesktopApp::new(format!(
    "demo-app-{}",
    std::process::id()
))?;

let local = app.ensure_local_data_dir()?;
assert!(local.exists());

Implementations

impl DesktopApp

pub fn new(app_name: impl Into<String>) -> Result<Self>

Creates a desktop app identity without a company namespace.

Errors

Returns Error::InvalidInput if app_name is empty, contains NUL bytes, or contains characters that are invalid in Windows file names.

pub fn with_company( company_name: impl Into<String>, app_name: impl Into<String>, ) -> Result<Self>

Creates a desktop app identity grouped under a company namespace.

App-data paths are nested as Company\App, while the default single-instance mutex ID uses Company.App.

Examples

let app = win_desktop_utils::DesktopApp::with_company("Acme", "Editor")?;

assert_eq!(app.company_name(), Some("Acme"));
assert_eq!(app.app_name(), "Editor");
assert_eq!(app.app_dir_name(), "Acme\\Editor");
assert_eq!(app.app_id(), "Acme.Editor");

Errors

Returns Error::InvalidInput if either identity part is empty, contains NUL bytes, or contains characters that are invalid in Windows file names.

Examples found in repository

examples/desktop_app.rs (line 2)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = win_desktop_utils::DesktopApp::with_company("Acme", "Demo Utility")?;

    let _guard = match app.single_instance()? {
        Some(guard) => guard,
        None => {
            println!("{} is already running", app.app_name());
            return Ok(());
        }
    };

    let local_dir = app.ensure_local_data_dir()?;
    let state_file = local_dir.join("state.txt");
    std::fs::write(&state_file, "started\n")?;

    let docs_shortcut = local_dir.join("win-desktop-utils docs.url");
    win_desktop_utils::create_url_shortcut(&docs_shortcut, "https://docs.rs/win-desktop-utils")?;

    println!("app id: {}", app.app_id());
    println!("local data: {}", local_dir.display());
    println!("state file: {}", state_file.display());
    println!("docs shortcut: {}", docs_shortcut.display());

    Ok(())
}

pub fn instance_scope(self, scope: InstanceScope) -> Self

Sets the default single-instance mutex namespace scope used by Self::single_instance.

Examples

let app = win_desktop_utils::DesktopApp::new("Admin Tool")?
    .instance_scope(win_desktop_utils::InstanceScope::Global);

assert_eq!(
    app.configured_instance_scope(),
    win_desktop_utils::InstanceScope::Global,
);

pub fn company_name(&self) -> Option<&str>

Returns the optional company name.

pub fn app_name(&self) -> &str

Returns the app name.

Examples found in repository

examples/desktop_app.rs (line 7)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = win_desktop_utils::DesktopApp::with_company("Acme", "Demo Utility")?;

    let _guard = match app.single_instance()? {
        Some(guard) => guard,
        None => {
            println!("{} is already running", app.app_name());
            return Ok(());
        }
    };

    let local_dir = app.ensure_local_data_dir()?;
    let state_file = local_dir.join("state.txt");
    std::fs::write(&state_file, "started\n")?;

    let docs_shortcut = local_dir.join("win-desktop-utils docs.url");
    win_desktop_utils::create_url_shortcut(&docs_shortcut, "https://docs.rs/win-desktop-utils")?;

    println!("app id: {}", app.app_id());
    println!("local data: {}", local_dir.display());
    println!("state file: {}", state_file.display());
    println!("docs shortcut: {}", docs_shortcut.display());

    Ok(())
}

pub fn app_dir_name(&self) -> &str

Returns the app-data directory name used by the paths helpers.

pub fn app_id(&self) -> &str

Returns the default app ID used by the single-instance helpers.

Examples found in repository

examples/desktop_app.rs (line 19)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = win_desktop_utils::DesktopApp::with_company("Acme", "Demo Utility")?;

    let _guard = match app.single_instance()? {
        Some(guard) => guard,
        None => {
            println!("{} is already running", app.app_name());
            return Ok(());
        }
    };

    let local_dir = app.ensure_local_data_dir()?;
    let state_file = local_dir.join("state.txt");
    std::fs::write(&state_file, "started\n")?;

    let docs_shortcut = local_dir.join("win-desktop-utils docs.url");
    win_desktop_utils::create_url_shortcut(&docs_shortcut, "https://docs.rs/win-desktop-utils")?;

    println!("app id: {}", app.app_id());
    println!("local data: {}", local_dir.display());
    println!("state file: {}", state_file.display());
    println!("docs shortcut: {}", docs_shortcut.display());

    Ok(())
}

pub fn configured_instance_scope(&self) -> InstanceScope

Returns the configured single-instance scope.

pub fn local_data_dir(&self) -> Result<PathBuf>

Returns the per-user local app-data directory for this app without creating it.

pub fn roaming_data_dir(&self) -> Result<PathBuf>

Returns the per-user roaming app-data directory for this app without creating it.

pub fn ensure_local_data_dir(&self) -> Result<PathBuf>

Creates and returns the per-user local app-data directory for this app.

Examples found in repository

examples/desktop_app.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = win_desktop_utils::DesktopApp::with_company("Acme", "Demo Utility")?;

    let _guard = match app.single_instance()? {
        Some(guard) => guard,
        None => {
            println!("{} is already running", app.app_name());
            return Ok(());
        }
    };

    let local_dir = app.ensure_local_data_dir()?;
    let state_file = local_dir.join("state.txt");
    std::fs::write(&state_file, "started\n")?;

    let docs_shortcut = local_dir.join("win-desktop-utils docs.url");
    win_desktop_utils::create_url_shortcut(&docs_shortcut, "https://docs.rs/win-desktop-utils")?;

    println!("app id: {}", app.app_id());
    println!("local data: {}", local_dir.display());
    println!("state file: {}", state_file.display());
    println!("docs shortcut: {}", docs_shortcut.display());

    Ok(())
}

pub fn ensure_roaming_data_dir(&self) -> Result<PathBuf>

Creates and returns the per-user roaming app-data directory for this app.

pub fn single_instance_options(&self) -> SingleInstanceOptions

Returns single-instance options for this app.

Examples

let app = win_desktop_utils::DesktopApp::with_company("Acme", "Editor")?;
let options = app.single_instance_options();

assert_eq!(options.app_id(), "Acme.Editor");
assert_eq!(
    options.configured_scope(),
    win_desktop_utils::InstanceScope::CurrentSession,
);

pub fn single_instance(&self) -> Result<Option<InstanceGuard>>

Attempts to acquire the configured single-instance guard for this app.

Examples found in repository

examples/desktop_app.rs (line 4)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = win_desktop_utils::DesktopApp::with_company("Acme", "Demo Utility")?;

    let _guard = match app.single_instance()? {
        Some(guard) => guard,
        None => {
            println!("{} is already running", app.app_name());
            return Ok(());
        }
    };

    let local_dir = app.ensure_local_data_dir()?;
    let state_file = local_dir.join("state.txt");
    std::fs::write(&state_file, "started\n")?;

    let docs_shortcut = local_dir.join("win-desktop-utils docs.url");
    win_desktop_utils::create_url_shortcut(&docs_shortcut, "https://docs.rs/win-desktop-utils")?;

    println!("app id: {}", app.app_id());
    println!("local data: {}", local_dir.display());
    println!("state file: {}", state_file.display());
    println!("docs shortcut: {}", docs_shortcut.display());

    Ok(())
}

Trait Implementations

impl Clone for DesktopApp

fn clone(&self) -> DesktopApp

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DesktopApp

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for DesktopApp

fn eq(&self, other: &DesktopApp) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for DesktopApp

impl StructuralPartialEq for DesktopApp