TrayIcon

1. Overview

StatusNotifierItem and DBusMenu implementation built directly on systemd sd-bus. It exposes the BastionGuard tray icon, tooltip, activation actions, persistent-startup action, and quit command.

File role: Implementation. The file contains 926 lines and belongs to the TrayIcon.cpp path.

The companion file is TrayIcon.hpp.

2. Component Responsibilities

  • Implement the behavior declared by the corresponding header or entry-point contract.
  • Generate a unique D-Bus service name
  • Acquire the user session bus and request the service name
  • Export StatusNotifierItem and DBusMenu objects
  • Register with the desktop StatusNotifierWatcher
  • Process D-Bus traffic in a dedicated worker thread
  • Marshal menu callbacks back to the bound GLib UI context
  • Unexport objects and release the bus during shutdown

3. Dependencies and Integration

Project-level dependencies:

  • TrayIcon.hpp
  • arpa/inet.h
  • unistd.h
  • signal.h
  • glibmm/main.h
  • gdk-pixbuf/gdk-pixbuf.h
  • glib.h
  • glib/gi18n.h
  • inttypes.h

System and library dependencies:

  • chrono
  • cstring
  • random
  • thread
  • vector
  • string
  • cstdio

4. Declared Types

Ev

Declares a struct.

5. Signals and Event Integration

The file exposes or connects the following signal-related elements:

  • void TrayIcon::emit_sni_signal(const char* signal_name) {
  • signal_name,

GTK-facing callbacks must execute on the main UI context. Components with worker threads use dispatchers or idle callbacks to cross the thread boundary.

6. Functions and Methods

The file exposes or implements 37 detected function or method signatures.

1. make_service_name

std::string TrayIcon::make_service_name()

Creates or derives service name.

2. TrayIcon

TrayIcon::TrayIcon()

Constructs the object, initializes its state, builds required resources, and connects the relevant callbacks.

3. ~TrayIcon

TrayIcon::~TrayIcon()

Releases resources owned by the object and stops any active background integration.

4. start

bool TrayIcon::start()

Starts start and activates the associated runtime resources.

5. dbusmenu_method_about_to_show_group

int TrayIcon::dbusmenu_method_about_to_show_group(sd_bus_message* m, void* userdata, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

6. dbusmenu_method_event_group

int TrayIcon::dbusmenu_method_event_group(sd_bus_message* m, void* userdata, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

7. stop

void TrayIcon::stop()

Stops stop and releases or signals its active resources.

8. bind_ui_context

void TrayIcon::bind_ui_context()

Binds ui context to the active execution context.

9. set_icon_file

void TrayIcon::set_icon_file(const std::string& png_path, int target_px)

Updates icon file and synchronizes dependent state.

10. set_icon

void TrayIcon::set_icon(const std::string& icon_name)

Updates icon and synchronizes dependent state.

11. set_tooltip

void TrayIcon::set_tooltip(const std::string& text)

Updates tooltip and synchronizes dependent state.

12. set_title

void TrayIcon::set_title(const std::string& title)

Updates title and synchronizes dependent state.

13. acquire_bus

bool TrayIcon::acquire_bus()

Acquires bus and stores the resulting handle.

14. request_name

bool TrayIcon::request_name()

Implements the request name operation declared by this component.

15. release_bus

void TrayIcon::release_bus()

Releases bus.

16. export_objects

bool TrayIcon::export_objects()

Exports objects through the relevant interface.

17. unexport_objects

void TrayIcon::unexport_objects()

Removes the exported objects.

18. register_to_watcher

bool TrayIcon::register_to_watcher()

Registers to watcher with the external subsystem.

19. bus_loop

void TrayIcon::bus_loop()

Runs the bus loop until shutdown or disconnection.

20. emit_sni_signal

void TrayIcon::emit_sni_signal(const char* signal_name)

Emits sni signal to subscribed components.

21. emit_dbusmenu_layout_updated

void TrayIcon::emit_dbusmenu_layout_updated()

Emits dbusmenu layout updated to subscribed components.

22. sni_method_activate

int TrayIcon::sni_method_activate(sd_bus_message* m, void* userdata, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

23. sni_method_context_menu

int TrayIcon::sni_method_context_menu(sd_bus_message* m, void*, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

24. sni_method_secondary_activate

int TrayIcon::sni_method_secondary_activate(sd_bus_message* m, void*, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

25. sni_prop_get

int TrayIcon::sni_prop_get(sd_bus*, const char*, const char*, const char* property, sd_bus_message* reply, void* userdata, sd_bus_error* ret_error)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

26. dbusmenu_prop_get

int TrayIcon::dbusmenu_prop_get(sd_bus*, const char*, const char*, const char* , sd_bus_message* reply, void*, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

27. dbusmenu_method_get_status

int TrayIcon::dbusmenu_method_get_status(sd_bus_message* m, void*, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

28. dbusmenu_method_get_children

int TrayIcon::dbusmenu_method_get_children(sd_bus_message* m, void* userdata, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

29. dbusmenu_method_get_layout

int TrayIcon::dbusmenu_method_get_layout(sd_bus_message* m, void* userdata, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

30. dbusmenu_method_event

int TrayIcon::dbusmenu_method_event(sd_bus_message* m, void* userdata, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

31. dbusmenu_method_about_to_show

int TrayIcon::dbusmenu_method_about_to_show(sd_bus_message* m, void*, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

32. dbusmenu_method_get_group_properties

int TrayIcon::dbusmenu_method_get_group_properties(sd_bus_message* m, void* userdata, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

33. dbusmenu_method_get_property

int TrayIcon::dbusmenu_method_get_property(sd_bus_message* m, void* userdata, sd_bus_error*)

Implements the corresponding D-Bus method or property callback required by the StatusNotifierItem/DBusMenu protocol.

34. invoke_std_function

static gboolean invoke_std_function(gpointer data)

Implements the invoke std function operation declared by this component.

35. label_for_menu_id

static inline const char* label_for_menu_id(int id)

Implements the label for menu id operation declared by this component.

36. enabled_for_menu_id

static inline bool enabled_for_menu_id(int)

Implements the enabled for menu id operation declared by this component.

37. append_item_properties

static int append_item_properties(sd_bus_message* m, int id, const char* label, bool enabled)

Implements the append item properties operation declared by this component.

7. Filesystem, IPC, Network, and Command Interfaces

Relevant literal paths, endpoints, or resource locations include:

  • /StatusNotifierItem
  • /Menu
  • /StatusNotifierWatcher

8. Runtime Flow

  1. Generate a unique D-Bus service name
  2. Acquire the user session bus and request the service name
  3. Export StatusNotifierItem and DBusMenu objects
  4. Register with the desktop StatusNotifierWatcher
  5. Process D-Bus traffic in a dedicated worker thread
  6. Marshal menu callbacks back to the bound GLib UI context
  7. Unexport objects and release the bus during shutdown

9. Concurrency and Main-Loop Behavior

  • Uses one or more C++ worker threads.
  • Marshals results or callbacks onto the GLib/GTK main context.

10. Runtime and Security Considerations

  • Runs D-Bus handling in a dedicated thread guarded by an atomic running flag.
  • Marshals callbacks to the GTK main context instead of directly invoking UI operations from the bus thread.
  • Exports a fixed and minimal tray-menu command set.

11. Error Handling and Operational Notes

  • Diagnostic failures are written to standard error or the GLib logging channel.
  • Boolean-returning operations use false to report recoverable failure.

12. Source Integrity

Relative source path: TrayIcon.cpp

SHA-256:

40b93985d6f2b536a47e5f5c3536a1c3f01e523b0c6e581ce6526b6b5cce0917

13. Licensing

The source header identifies this component as distributed under the GNU General Public License version 3. BastionGuard branding and trademarks remain subject to the notices stated in the source file.

Published on:
Last updated on: