Utils::notify (Core Desktop Notification Helper)

1. Overview

Utils::notify is a small core utility function that provides a unified way for BastionGuard components to emit desktop notifications using the GLib / GIO notification system.

It is intentionally minimal and toolkit-agnostic, allowing both GTK-based and non-UI core components (daemons, background tasks, security engines) to surface user-visible messages without directly depending on higher-level UI code.

2. Purpose and Scope

The function is designed to:

  • Send user notifications in a desktop-environment–compliant way
  • Integrate with the active GApplication instance
  • Keep notification logic centralized and consistent across the project

It does not:

  • Queue or persist notifications
  • Handle notification actions or buttons
  • Fallback to external tools (e.g. notify-send)

3. API Signature

void Utils::notify(const std::string& title,
                   const std::string& msg);

Parameters

  • title – short notification title (UTF-8)
  • msg – notification body text (UTF-8)

The caller is responsible for localization (typically via _()) before invoking this function.

4. Implementation Details

4.1 Notification Creation

A new GNotification object is created using the provided title:

GNotification* n = g_notification_new(title.c_str());

The message body is then attached:

g_notification_set_body(n, msg.c_str());

4.2 Application Context Resolution

The function retrieves the currently active GApplication:

GApplication* app = g_application_get_default();

If a default application instance exists, the notification is dispatched:

g_application_send_notification(app, nullptr, n);

If no GApplication is available (e.g. very early startup or misconfigured runtime), the function silently does nothing.

5. Design Considerations

  • Loose coupling: no dependency on GTK widgets or Qt APIs
  • DE integration: leverages the native desktop notification system via GIO
  • Fail-safe behavior: absence of a running GApplication does not crash the process
  • Consistency: ensures all BastionGuard notifications originate from a single helper

6. Usage Context

Typical use cases include:

  • Security alerts raised by background engines
  • Status notifications from tray-driven actions
  • Non-blocking warnings originating outside the main UI thread

Because it relies on the existing GApplication, this helper is best used in components that are part of the main BastionGuard runtime rather than standalone system services.

7. Limitations and Future Extensions

  • No support for notification actions or callbacks
  • No urgency/priority configuration
  • No fallback for non-GIO environments

These limitations are intentional, keeping Utils::notify simple and predictable. More advanced notification behavior can be layered on top if required.

In summary, Utils::notify is a lightweight core helper that standardizes how BastionGuard emits desktop notifications, ensuring consistency, safety, and minimal dependencies across the project.

Published on:
Last updated on: