Struct PresenceRunner 

pub struct PresenceRunner { /* private fields */ }

A runner that manages the Discord RPC background task. Create a runner, configure it, run it to get a client handle, then clone the handle for sharing.

Implementations

impl PresenceRunner

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

Create a new PresenceRunner instance. Requires the client ID of your chosen app from the Discord Developer Portal.

Examples found in repository

examples/disconnect.rs (line 5)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .show_errors()
        .on_disconnect(|reason| {
            eprintln!("discord rpc disconnected: {reason:?}");
        });

    runner.run(false).await?;
    runner.wait().await?;

    Ok(())
}

examples/simple.rs (line 5)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160");

    let activity = Activity::new()
        .name("cool app name")
        .details("Something?")
        .state("Probably~")
        .build()?;

    let client = runner.run(true).await?;
    client.set_activity(activity).await?;

    // indefinitely block here
    runner.wait().await?;

    Ok(())
}

examples/timed.rs (line 17)

async fn main() -> Result<(), PresenceError> {
    // simple atomic counter
    let count = Arc::new(AtomicUsize::new(0));

    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| println!("Connected to user: {}", data.user.username()))
        .on_activity_send(move |_| {

            // increments the counter with every send_activity()
            let val = count.fetch_add(1, Ordering::Relaxed) + 1;

            println!("Activity {val} sent successfully.")

        })
        .show_errors() // enables verbose error logging
    ;

    // create activities for later use
    let activity_1 = Activity::new()
        .details("this runs")
        .state("for ten seconds")
        .build()?;

    let activity_2 = Activity::new()
        .details("believe it")
        .state("or not")
        .build()?;

    let closing_activity = Activity::new()
        .details("closing presence in...")
        .duration(Duration::from_secs(5))
        .small_image("status")
        .build()?;

    // first run
    let client = runner.run(true).await?;

    client.set_activity(activity_1).await?;
    sleep(Duration::from_secs(5)).await;
    client.set_activity(activity_2).await?;
    sleep(Duration::from_secs(5)).await;
    client.set_activity(closing_activity).await?;
    sleep(Duration::from_secs(5)).await;

    client.close().await?;

    println!("Stopped.");

    Ok(())
}

examples/indefinite.rs (line 9)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| {
            println!(
                "RPC version: v{}; Connected to user: {}",
                data.version(),
                data.user.global_name().unwrap_or_default(),
            )
        })
        .on_activity_send(|data| {
            println!(
                "Activity sent to app! (running on {})\nCreated at: {}",
                data.platform().unwrap_or_default(),
                data.activity.created_at()
            );
        })
        .on_disconnect(|f| println!("Disconnected: {f:?}"))
        .show_errors() // enables verbose error logging
        .on_retry(move |c| {
            if c % 10 == 0 {
                println!("Retry count {c}; is Discord open?");
            }
        });

    let client = runner.run(true).await?;

    // the activity can include any combination of builder function calls
    let activity = Activity::new()
        .activity_type(ActivityType::Playing)
        .details("epic game")
        .details_url("https://github.com/hitblast")
        .status_display_type(StatusDisplayType::Details)
        .large_image("game_icon")
        .large_text("Playing a game")
        .large_url("https://hitblast.github.io/")
        .small_image("status")
        .small_text("Online")
        .build()?;

    client.set_activity(activity).await?;

    // indefinitely block here
    runner.wait().await?;

    Ok(())
}

pub fn on_ready<F: Fn(ReadyData) + Send + Sync + 'static>(self, f: F) -> Self

Runs a particular closure after receiving a READY event.

This can fire multiple times depending on how many times the client needs to disconnect and reconnect.

Examples found in repository

examples/timed.rs (line 18)

async fn main() -> Result<(), PresenceError> {
    // simple atomic counter
    let count = Arc::new(AtomicUsize::new(0));

    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| println!("Connected to user: {}", data.user.username()))
        .on_activity_send(move |_| {

            // increments the counter with every send_activity()
            let val = count.fetch_add(1, Ordering::Relaxed) + 1;

            println!("Activity {val} sent successfully.")

        })
        .show_errors() // enables verbose error logging
    ;

    // create activities for later use
    let activity_1 = Activity::new()
        .details("this runs")
        .state("for ten seconds")
        .build()?;

    let activity_2 = Activity::new()
        .details("believe it")
        .state("or not")
        .build()?;

    let closing_activity = Activity::new()
        .details("closing presence in...")
        .duration(Duration::from_secs(5))
        .small_image("status")
        .build()?;

    // first run
    let client = runner.run(true).await?;

    client.set_activity(activity_1).await?;
    sleep(Duration::from_secs(5)).await;
    client.set_activity(activity_2).await?;
    sleep(Duration::from_secs(5)).await;
    client.set_activity(closing_activity).await?;
    sleep(Duration::from_secs(5)).await;

    client.close().await?;

    println!("Stopped.");

    Ok(())
}

examples/indefinite.rs (lines 10-16)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| {
            println!(
                "RPC version: v{}; Connected to user: {}",
                data.version(),
                data.user.global_name().unwrap_or_default(),
            )
        })
        .on_activity_send(|data| {
            println!(
                "Activity sent to app! (running on {})\nCreated at: {}",
                data.platform().unwrap_or_default(),
                data.activity.created_at()
            );
        })
        .on_disconnect(|f| println!("Disconnected: {f:?}"))
        .show_errors() // enables verbose error logging
        .on_retry(move |c| {
            if c % 10 == 0 {
                println!("Retry count {c}; is Discord open?");
            }
        });

    let client = runner.run(true).await?;

    // the activity can include any combination of builder function calls
    let activity = Activity::new()
        .activity_type(ActivityType::Playing)
        .details("epic game")
        .details_url("https://github.com/hitblast")
        .status_display_type(StatusDisplayType::Details)
        .large_image("game_icon")
        .large_text("Playing a game")
        .large_url("https://hitblast.github.io/")
        .small_image("status")
        .small_text("Online")
        .build()?;

    client.set_activity(activity).await?;

    // indefinitely block here
    runner.wait().await?;

    Ok(())
}

pub fn on_activity_send<F: Fn(ActivityResponseData) + Send + Sync + 'static>( self, f: F, ) -> Self

Run a particular closure after ensuring that a PresenceClient::set_activity has successfully managed to pass its data through the IPC channel.

This can fire multiple times.

Examples found in repository

examples/timed.rs (lines 19-26)

async fn main() -> Result<(), PresenceError> {
    // simple atomic counter
    let count = Arc::new(AtomicUsize::new(0));

    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| println!("Connected to user: {}", data.user.username()))
        .on_activity_send(move |_| {

            // increments the counter with every send_activity()
            let val = count.fetch_add(1, Ordering::Relaxed) + 1;

            println!("Activity {val} sent successfully.")

        })
        .show_errors() // enables verbose error logging
    ;

    // create activities for later use
    let activity_1 = Activity::new()
        .details("this runs")
        .state("for ten seconds")
        .build()?;

    let activity_2 = Activity::new()
        .details("believe it")
        .state("or not")
        .build()?;

    let closing_activity = Activity::new()
        .details("closing presence in...")
        .duration(Duration::from_secs(5))
        .small_image("status")
        .build()?;

    // first run
    let client = runner.run(true).await?;

    client.set_activity(activity_1).await?;
    sleep(Duration::from_secs(5)).await;
    client.set_activity(activity_2).await?;
    sleep(Duration::from_secs(5)).await;
    client.set_activity(closing_activity).await?;
    sleep(Duration::from_secs(5)).await;

    client.close().await?;

    println!("Stopped.");

    Ok(())
}

examples/indefinite.rs (lines 17-23)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| {
            println!(
                "RPC version: v{}; Connected to user: {}",
                data.version(),
                data.user.global_name().unwrap_or_default(),
            )
        })
        .on_activity_send(|data| {
            println!(
                "Activity sent to app! (running on {})\nCreated at: {}",
                data.platform().unwrap_or_default(),
                data.activity.created_at()
            );
        })
        .on_disconnect(|f| println!("Disconnected: {f:?}"))
        .show_errors() // enables verbose error logging
        .on_retry(move |c| {
            if c % 10 == 0 {
                println!("Retry count {c}; is Discord open?");
            }
        });

    let client = runner.run(true).await?;

    // the activity can include any combination of builder function calls
    let activity = Activity::new()
        .activity_type(ActivityType::Playing)
        .details("epic game")
        .details_url("https://github.com/hitblast")
        .status_display_type(StatusDisplayType::Details)
        .large_image("game_icon")
        .large_text("Playing a game")
        .large_url("https://hitblast.github.io/")
        .small_image("status")
        .small_text("Online")
        .build()?;

    client.set_activity(activity).await?;

    // indefinitely block here
    runner.wait().await?;

    Ok(())
}

pub fn on_disconnect<F: Fn(DisconnectReason) + Send + Sync + 'static>( self, f: F, ) -> Self

Runs a particular closure after the RPC connection is lost.

Unlike on_retry, this fires only when a previously initialized connection drops, which means that you should prefer on_retry instead if you want more accurate responses to the initial connect or handshake failures, and on_disconnect for reacting to post-connection failures.

This can fire multiple times depending on how many times the client disconnects and reconnects again.

Examples found in repository

examples/disconnect.rs (lines 7-9)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .show_errors()
        .on_disconnect(|reason| {
            eprintln!("discord rpc disconnected: {reason:?}");
        });

    runner.run(false).await?;
    runner.wait().await?;

    Ok(())
}

examples/indefinite.rs (line 24)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| {
            println!(
                "RPC version: v{}; Connected to user: {}",
                data.version(),
                data.user.global_name().unwrap_or_default(),
            )
        })
        .on_activity_send(|data| {
            println!(
                "Activity sent to app! (running on {})\nCreated at: {}",
                data.platform().unwrap_or_default(),
                data.activity.created_at()
            );
        })
        .on_disconnect(|f| println!("Disconnected: {f:?}"))
        .show_errors() // enables verbose error logging
        .on_retry(move |c| {
            if c % 10 == 0 {
                println!("Retry count {c}; is Discord open?");
            }
        });

    let client = runner.run(true).await?;

    // the activity can include any combination of builder function calls
    let activity = Activity::new()
        .activity_type(ActivityType::Playing)
        .details("epic game")
        .details_url("https://github.com/hitblast")
        .status_display_type(StatusDisplayType::Details)
        .large_image("game_icon")
        .large_text("Playing a game")
        .large_url("https://hitblast.github.io/")
        .small_image("status")
        .small_text("Online")
        .build()?;

    client.set_activity(activity).await?;

    // indefinitely block here
    runner.wait().await?;

    Ok(())
}

pub fn on_retry<F: Fn(usize) + Send + Sync + 'static>(self, f: F) -> Self

Runs a particular closure when retrying for socket creation or handshake.

This can fire multiple times, or for a limited amount depending on the amount of maximum retries that has been set (through PresenceRunner::set_max_retries).

The closure parameter is the count of retries done at the time of its execution.

Examples found in repository

examples/indefinite.rs (lines 26-30)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| {
            println!(
                "RPC version: v{}; Connected to user: {}",
                data.version(),
                data.user.global_name().unwrap_or_default(),
            )
        })
        .on_activity_send(|data| {
            println!(
                "Activity sent to app! (running on {})\nCreated at: {}",
                data.platform().unwrap_or_default(),
                data.activity.created_at()
            );
        })
        .on_disconnect(|f| println!("Disconnected: {f:?}"))
        .show_errors() // enables verbose error logging
        .on_retry(move |c| {
            if c % 10 == 0 {
                println!("Retry count {c}; is Discord open?");
            }
        });

    let client = runner.run(true).await?;

    // the activity can include any combination of builder function calls
    let activity = Activity::new()
        .activity_type(ActivityType::Playing)
        .details("epic game")
        .details_url("https://github.com/hitblast")
        .status_display_type(StatusDisplayType::Details)
        .large_image("game_icon")
        .large_text("Playing a game")
        .large_url("https://hitblast.github.io/")
        .small_image("status")
        .small_text("Online")
        .build()?;

    client.set_activity(activity).await?;

    // indefinitely block here
    runner.wait().await?;

    Ok(())
}

pub fn show_errors(self) -> Self

Enable verbose error logging over std::io::stderr writes for RPC and code events.

Examples found in repository

examples/disconnect.rs (line 6)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .show_errors()
        .on_disconnect(|reason| {
            eprintln!("discord rpc disconnected: {reason:?}");
        });

    runner.run(false).await?;
    runner.wait().await?;

    Ok(())
}

examples/timed.rs (line 27)

async fn main() -> Result<(), PresenceError> {
    // simple atomic counter
    let count = Arc::new(AtomicUsize::new(0));

    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| println!("Connected to user: {}", data.user.username()))
        .on_activity_send(move |_| {

            // increments the counter with every send_activity()
            let val = count.fetch_add(1, Ordering::Relaxed) + 1;

            println!("Activity {val} sent successfully.")

        })
        .show_errors() // enables verbose error logging
    ;

    // create activities for later use
    let activity_1 = Activity::new()
        .details("this runs")
        .state("for ten seconds")
        .build()?;

    let activity_2 = Activity::new()
        .details("believe it")
        .state("or not")
        .build()?;

    let closing_activity = Activity::new()
        .details("closing presence in...")
        .duration(Duration::from_secs(5))
        .small_image("status")
        .build()?;

    // first run
    let client = runner.run(true).await?;

    client.set_activity(activity_1).await?;
    sleep(Duration::from_secs(5)).await;
    client.set_activity(activity_2).await?;
    sleep(Duration::from_secs(5)).await;
    client.set_activity(closing_activity).await?;
    sleep(Duration::from_secs(5)).await;

    client.close().await?;

    println!("Stopped.");

    Ok(())
}

examples/indefinite.rs (line 25)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| {
            println!(
                "RPC version: v{}; Connected to user: {}",
                data.version(),
                data.user.global_name().unwrap_or_default(),
            )
        })
        .on_activity_send(|data| {
            println!(
                "Activity sent to app! (running on {})\nCreated at: {}",
                data.platform().unwrap_or_default(),
                data.activity.created_at()
            );
        })
        .on_disconnect(|f| println!("Disconnected: {f:?}"))
        .show_errors() // enables verbose error logging
        .on_retry(move |c| {
            if c % 10 == 0 {
                println!("Retry count {c}; is Discord open?");
            }
        });

    let client = runner.run(true).await?;

    // the activity can include any combination of builder function calls
    let activity = Activity::new()
        .activity_type(ActivityType::Playing)
        .details("epic game")
        .details_url("https://github.com/hitblast")
        .status_display_type(StatusDisplayType::Details)
        .large_image("game_icon")
        .large_text("Playing a game")
        .large_url("https://hitblast.github.io/")
        .small_image("status")
        .small_text("Online")
        .build()?;

    client.set_activity(activity).await?;

    // indefinitely block here
    runner.wait().await?;

    Ok(())
}

pub fn set_max_retries(self, count: usize) -> Self

Sets the amount of maximum retries to do on socket creation and handshakes before the runner should give up.

By default this is set to 0 internally, which means the inner loop would retry indefinitely.

pub async fn run( &mut self, wait_for_ready: bool, ) -> Result<&PresenceClient, PresenceRunnerError>

Run the runner. Must be called before any client handle operations.

Examples found in repository

examples/disconnect.rs (line 11)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .show_errors()
        .on_disconnect(|reason| {
            eprintln!("discord rpc disconnected: {reason:?}");
        });

    runner.run(false).await?;
    runner.wait().await?;

    Ok(())
}

examples/simple.rs (line 13)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160");

    let activity = Activity::new()
        .name("cool app name")
        .details("Something?")
        .state("Probably~")
        .build()?;

    let client = runner.run(true).await?;
    client.set_activity(activity).await?;

    // indefinitely block here
    runner.wait().await?;

    Ok(())
}

examples/timed.rs (line 48)

async fn main() -> Result<(), PresenceError> {
    // simple atomic counter
    let count = Arc::new(AtomicUsize::new(0));

    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| println!("Connected to user: {}", data.user.username()))
        .on_activity_send(move |_| {

            // increments the counter with every send_activity()
            let val = count.fetch_add(1, Ordering::Relaxed) + 1;

            println!("Activity {val} sent successfully.")

        })
        .show_errors() // enables verbose error logging
    ;

    // create activities for later use
    let activity_1 = Activity::new()
        .details("this runs")
        .state("for ten seconds")
        .build()?;

    let activity_2 = Activity::new()
        .details("believe it")
        .state("or not")
        .build()?;

    let closing_activity = Activity::new()
        .details("closing presence in...")
        .duration(Duration::from_secs(5))
        .small_image("status")
        .build()?;

    // first run
    let client = runner.run(true).await?;

    client.set_activity(activity_1).await?;
    sleep(Duration::from_secs(5)).await;
    client.set_activity(activity_2).await?;
    sleep(Duration::from_secs(5)).await;
    client.set_activity(closing_activity).await?;
    sleep(Duration::from_secs(5)).await;

    client.close().await?;

    println!("Stopped.");

    Ok(())
}

examples/indefinite.rs (line 32)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| {
            println!(
                "RPC version: v{}; Connected to user: {}",
                data.version(),
                data.user.global_name().unwrap_or_default(),
            )
        })
        .on_activity_send(|data| {
            println!(
                "Activity sent to app! (running on {})\nCreated at: {}",
                data.platform().unwrap_or_default(),
                data.activity.created_at()
            );
        })
        .on_disconnect(|f| println!("Disconnected: {f:?}"))
        .show_errors() // enables verbose error logging
        .on_retry(move |c| {
            if c % 10 == 0 {
                println!("Retry count {c}; is Discord open?");
            }
        });

    let client = runner.run(true).await?;

    // the activity can include any combination of builder function calls
    let activity = Activity::new()
        .activity_type(ActivityType::Playing)
        .details("epic game")
        .details_url("https://github.com/hitblast")
        .status_display_type(StatusDisplayType::Details)
        .large_image("game_icon")
        .large_text("Playing a game")
        .large_url("https://hitblast.github.io/")
        .small_image("status")
        .small_text("Online")
        .build()?;

    client.set_activity(activity).await?;

    // indefinitely block here
    runner.wait().await?;

    Ok(())
}

pub fn clone_handle(&self) -> PresenceClient

Returns a clone of the client handle for sharing.

pub async fn wait(&mut self) -> Result<(), PresenceRunnerError>

Waits for the IPC task to finish.

NOTE: If there’s no join_handle present, the function will do nothing and just return blank.

Examples found in repository

examples/disconnect.rs (line 12)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .show_errors()
        .on_disconnect(|reason| {
            eprintln!("discord rpc disconnected: {reason:?}");
        });

    runner.run(false).await?;
    runner.wait().await?;

    Ok(())
}

examples/simple.rs (line 17)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160");

    let activity = Activity::new()
        .name("cool app name")
        .details("Something?")
        .state("Probably~")
        .build()?;

    let client = runner.run(true).await?;
    client.set_activity(activity).await?;

    // indefinitely block here
    runner.wait().await?;

    Ok(())
}

examples/indefinite.rs (line 50)

async fn main() -> Result<(), PresenceError> {
    let mut runner = PresenceRunner::new("1463450870480900160")
        .on_ready(|data| {
            println!(
                "RPC version: v{}; Connected to user: {}",
                data.version(),
                data.user.global_name().unwrap_or_default(),
            )
        })
        .on_activity_send(|data| {
            println!(
                "Activity sent to app! (running on {})\nCreated at: {}",
                data.platform().unwrap_or_default(),
                data.activity.created_at()
            );
        })
        .on_disconnect(|f| println!("Disconnected: {f:?}"))
        .show_errors() // enables verbose error logging
        .on_retry(move |c| {
            if c % 10 == 0 {
                println!("Retry count {c}; is Discord open?");
            }
        });

    let client = runner.run(true).await?;

    // the activity can include any combination of builder function calls
    let activity = Activity::new()
        .activity_type(ActivityType::Playing)
        .details("epic game")
        .details_url("https://github.com/hitblast")
        .status_display_type(StatusDisplayType::Details)
        .large_image("game_icon")
        .large_text("Playing a game")
        .large_url("https://hitblast.github.io/")
        .small_image("status")
        .small_text("Online")
        .build()?;

    client.set_activity(activity).await?;

    // indefinitely block here
    runner.wait().await?;

    Ok(())
}