Crate unifiedpush 

UnifiedPush

Main crate for UnifiedPush, to interact with the UnifiedPush distributor, and receive push notifications.

Use UnifiedPush::new as a starting point to implement the feature.

To work, it needs a storage that implements UnifiedPush-Storage, like UnifiedPush-Storage using Preferences.

It is possible to configure your app to start from a push notification.

Example

use std::sync::mpsc::channel;

use tokio::runtime::{Handle, Runtime};
use unifiedpush::{auth_to_string, pubkey_to_string, PushEvent, PushMessage, UnifiedPush};
use unifiedpush_storage_preferences::{preferences::AppInfo, UnifiedPushStoragePreferences};

// fake picker for the example
let my_selection = || { "org.example.distributor" };

async {
    // First init storage and UnifiedPush
    let mut storage = UnifiedPushStoragePreferences::new(AppInfo {
        name: "org.unifiedpush.example",
        author: "UnifiedPush",
    });
    let (event_tx, event_rx) = channel::<PushEvent>();
    let handle = Handle::try_current().unwrap_or_else(|_| Runtime::new().unwrap().handle().to_owned());
    let mut unifiedpush = UnifiedPush::new(
        "org.unifiedpush.example",
        storage,
        event_tx,
        handle,
    ).await.unwrap();

    // Then, save the distributor
    if !unifiedpush.try_use_default_distributor().await {
        // If we can't use the default distributor: use our own picker:
        let distributor = my_selection();
        unifiedpush.save_distributor(&distributor).await;
    }

    // Finally, register. The distributor will send a new endpoint,
    // and `on_new_endpoint` will be called.
    unifiedpush.register(
        "default",
        Some("Default registration for the example"),
        Some("BA1Hxzyi1RUM1b5wjxsn7nGxAszw2u61m164i3MrAIxHF6YK5h4SDYic-dRuU_RCPCfA5aq9ojSwk5Y2EmClBPs")
    ).await;

    for event in event_rx.iter() {
        match event {
            PushEvent::NewEndpoint { instance, endpoint } => {
                println!(
                    "Push: New endpoint for {}:\n\turl={}\n\tpubkey={}\n\tauth={}",
                    instance,
                    endpoint.endpoint,
                    pubkey_to_string(&endpoint.pubkey).unwrap(),
                    auth_to_string(&endpoint.auth).unwrap()
                );
                // Here, the endpoint, the public key and the auth secret
                // must be sent to the application server
            }
            PushEvent::Message { instance, message } => {
                match message {
                    PushMessage::Raw { content } => {
                        println!(
                            "Push: New unencrypted message for {instance}: {}",
                             String::from_utf8(content).unwrap()
                        );
                    }
                    PushMessage::Decrypted { content } => {
                        println!(
                            "Push: New decrypted message for {instance}: {}",
                             String::from_utf8(content).unwrap()
                        );
                    }
                };
            }
            PushEvent::Unregistered { instance } => {
                println!("Push: {instance} unregistered");
            }
            PushEvent::Abort => {
                println!("Push: Aborting");
                break;
            }
        }
    }
};

Start from a push notification

In order to be able to start the application from a push notification, you must set a D-Bus activable service. It can be done using systemd’s D-Bus Service.

For example, the following config file stored in any of these directories allows the app to start from a push notifications:

• ~/.local/share/dbus-1/services/org.unifiedpush.example.service,
• /usr/share/dbus-1/services/org.unifiedpush.example.service,
• /var/lib/flatpak/exports/share/dbus-1/services/org.unifiedpush.example.service:

[D-BUS Service]
Name=org.unifiedpush.example
Exec=my_example --unifiedpush-bg

The file name and the Name= attribute must match the dbus_name argument passed during UnifiedPush::new initialization.

The command line argument --unifiedpush-bg can be used to implement a different behavior when the application is started from the background. For example:

• to start without any UI,
• to stop automatically if the application doesn’t receive new push messages after a few seconds
• to stop automatically if another instance of the application, with the UI, starts

Structs

Distributor

EventHandler

EventSink implementation using functions to handle events

PushEndpoint

Received on new endpoint

UnifiedPush

Entrypoint to support UnifiedPush

Enums

PushEvent

Event received from the distributor

PushMessage

Received on message

Traits

EventSink

Trait that must be implemented to handle incoming [PushEvents]

Functions

auth_to_string

Convert Auth to URL-safe Base64 encoded without padding string

pubkey_to_string

Convert PublicKey to a string of its uncompressed format, URL-safe Base64 encoded without padding