Utils.hpp

1. Overview

The Utils.hpp header defines the Utils utility class, a lightweight helper component that provides common cross-cutting functionality for BastionGuard. In its current form, the class exposes a centralized interface for delivering desktop notifications to the user.

Functionally, Utils provides:

  • A unified API for displaying system notifications
  • Abstraction over platform-specific notification mechanisms
  • Consistent formatting of alert and informational messages
  • Decoupling of notification logic from core business components

2. Dependencies and Includes

#include <string>
  • <string> – message titles and body text passed to the notification system

3. Class Declaration and Scope

class Utils

The class is implemented as a static utility container. All methods are static, and no instances of Utils are intended to be created.

4. Public Interface

4.1 Desktop Notification Helper

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

Sends a desktop notification with the specified title and message body. The implementation abstracts the underlying notification backend (e.g., D-Bus/Notify, Qt notifications, platform-native APIs).

  • title – short summary displayed as the notification heading
  • msg – detailed message content

5. UI Components

This component does not directly define GTK or Qt widgets. Notifications are displayed through the operating system’s native notification service.

6. Internal State and Data Model

No persistent state is declared in this header. All notification-related configuration and runtime context are managed internally in the implementation.

7. Usage Context

Utils::notify() is typically used by security-sensitive and background components to surface important events to the user, including:

  • Detection of infected files
  • Update completion or failure
  • Privacy or device access alerts
  • Service state changes
  • Critical configuration issues

8. Internal Logic

Although implementation details are not exposed in this header, a typical notification workflow includes:

  • Validation and sanitization of title and message strings
  • Selection of the appropriate notification backend
  • Dispatch of the message to the desktop notification daemon
  • Optional fallback to console logging if notifications are unavailable

9. Auto-Update (Scheduled Refresh)

This component does not implement scheduled behavior. Notifications are emitted on-demand in response to application events.

10. Settings Storage

Notification preferences (e.g., enable/disable, urgency levels) are not managed directly by this class. Such preferences are expected to be stored in the central settings subsystem.

11. Helper Functions and Platform Integration

The implementation is expected to adapt to different desktop environments and operating systems by selecting appropriate notification APIs, such as:

  • Freedesktop.org Desktop Notifications (Linux, D-Bus)
  • Qt notification wrappers
  • Native Windows/macOS notification services

12. Runtime and Security Considerations

  • Information disclosure: notifications should avoid exposing sensitive paths, credentials, or internal identifiers.
  • Rate limiting: frequent alerts should be throttled to prevent notification spam and user fatigue.
  • Thread context: notification dispatch should be marshaled to the main event loop if required by the backend.
  • Reliability: failures in the notification subsystem should not compromise core security functionality.
  • User trust: notifications must be clearly attributable to BastionGuard to prevent spoofing or confusion.
Published on:
Last updated on: