push_notifications.hpp

Go to the documentation of this file.

#pragma once
 
// pulp::events::PushNotifications — cross-platform local notification surface.
//
// Supported operations:
//   * Local notifications: `post_local_notification(title, body, category)`
//     posts a notification immediately through the host platform's user-
//     notification surface.
//   * Authorization: `request_authorization(callback)` asks the OS for
//     permission to post notifications and reports the user's decision.
//   * Tap handler: `set_handler(callback)` registers a callback that fires
//     when the user activates a delivered notification.
//
// Not currently implemented by the built-in backends:
//   * Remote / push notifications via APNs (Apple) and FCM (Android).
//   * Notification categories with custom action buttons.
//   * Scheduled / time-triggered notifications.
//   * Per-notification badge / sound / attachment customization.
//
// Backends (runtime-detected; build never hard-fails on a missing SDK):
//   * macOS / iOS: `UNUserNotificationCenter` from `UserNotifications.framework`.
//   * Linux: `libnotify.so.4` via runtime-dlopen.
//   * Windows: scaffold-only `winrt-toast-scaffold` backend that probes WinRT
//     availability via runtime-LoadLibrary `combase.dll`, but reports
//     unavailable until full toast activator / AUMID integration ships.
//   * Other platforms / build configurations: `is_available()` returns false
//     and `post_local_notification` reports a posted notification id of 0.
 
#include <cstdint>
#include <functional>
#include <memory>
#include <string>
#include <string_view>
 
namespace pulp::events {

enum class NotificationAuthorization {
    NotDetermined, 
    Denied,        
    Granted,       
    Unsupported,   
};

struct LocalNotification {
    std::string title;    
    std::string body;     
    std::string category; 
    std::string id;       
};

struct NotificationActivation {
    std::string id;          
    std::string category;    
    std::string action_id;   
};
 
using AuthorizationCallback = std::function<void(NotificationAuthorization)>;
using NotificationHandler = std::function<void(const NotificationActivation&)>;

class PushNotifications {
public:
    static PushNotifications& instance();
 
    virtual ~PushNotifications() = default;

    virtual bool is_available() const = 0;

    virtual std::string backend_id() const = 0;

    virtual void request_authorization(AuthorizationCallback callback) = 0;

    virtual NotificationAuthorization current_authorization() const = 0;

    virtual uint64_t post_local_notification(const LocalNotification& notification) = 0;

    virtual void set_handler(NotificationHandler handler) = 0;

    virtual bool cancel_notification(const std::string& id) = 0;

    virtual void cancel_all() = 0;
 
protected:
    PushNotifications() = default;
    PushNotifications(const PushNotifications&) = delete;
    PushNotifications& operator=(const PushNotifications&) = delete;
};
 
} // namespace pulp::events