2 * Copyright © 2011 Canonical Ltd.
4 * This library is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as
6 * published by the Free Software Foundation; either version 2 of the
7 * licence, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful, but
10 * WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
19 * Author: Ryan Lortie <desrt@desrt.ca>
22 #include "gmenuexporter.h"
24 #include "gdbusmethodinvocation.h"
25 #include "gdbusintrospection.h"
26 #include "gdbusnamewatching.h"
27 #include "gdbuserror.h"
30 * SECTION:gmenuexporter
31 * @title: GMenuModel exporter
32 * @short_description: Export GMenuModels on D-Bus
33 * @see_also: #GMenuModel, #GDBusMenuModel
35 * These functions support exporting a #GMenuModel on D-Bus.
36 * The D-Bus interface that is used is a private implementation
39 * To access an exported #GMenuModel remotely, use
40 * g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
43 /* {{{1 D-Bus Interface description */
45 /* The org.gtk.Menus interface
46 * ===========================
48 * The interface is primarily concerned with three things:
50 * - communicating menus to the client
51 * - establishing links between menus and other menus
52 * - notifying clients of changes
54 * As a basic principle, it is recognised that the menu structure
55 * of an application is often large. It is also recognised that some
56 * menus are liable to frequently change without the user ever having
57 * opened the menu. For both of these reasons, the individual menus are
58 * arranged into subscription groups. Each subscription group is specified
59 * by an unsigned integer. The assignment of integers need not be consecutive.
61 * Within a subscription group there are multiple menus. Each menu is
62 * identified with an unsigned integer, unique to its subscription group.
64 * By convention, the primary menu is numbered 0 without subscription group 0.
66 * Actionable menu items (ie: those that produce some effect in the
67 * application when they are activated) have a related action, specified by
68 * a string. This string specifies the name of the action, according to the
69 * org.gtk.Actions interface, at the same object path as the menu.
74 * Start :: (au) → (a(uuaa{sv}))
76 * The Start method is used to indicate that a client is interested in
77 * tracking and displaying the content of the menus of a particular list
78 * of subscription groups.
80 * Most typically, the client will request subscription group 0 to start.
82 * The call has two effects. First, it replies with all menus defined
83 * within the requested subscription groups. The format of the reply is
84 * an array of tuples, where the items in each tuple are:
85 * - the subscription group of the menu
86 * - the number of the menu within that group
87 * - an array of menu items
89 * Each menu item is a dictionary of attributes (a{sv}).
91 * Secondly, this call has a side effect: it atomically requests that
92 * the Changed signal start to be emitted for the requested subscription
93 * group. Each group has a subscription count and only signals changes
94 * on itself when this count is greater than zero.
96 * If a group is specified multiple times then the result is that the
97 * contents of that group is only returned once, but the subscription
98 * count is increased multiple times.
100 * If a client disconnects from the bus while holding subscriptions then
101 * its subscriptions will be cancelled. This prevents "leaking" subscriptions
102 * in the case of crashes and is also useful for applications that want
103 * to exit without manually cleaning up.
107 * The End method reverses the previous effects of a call to Start.
109 * When clients are no longer interested in the contents of a subscription
110 * group, they should call the End method.
112 * The parameter lists the subscription groups. A subscription group
113 * needs to be cancelled the same number of times as it was requested.
114 * For this reason, it might make sense to specify the same subscription
115 * group multiple times (if multiple Start calls were made for this group).
120 * Changed :: (a(uuuuaa{sv}))
122 * The changed signal indicates changes to a particular menu.
124 * The changes come as an array of tuples where the items in each tuple are:
125 * - the subscription group of the menu
126 * - the number of the menu within that group
127 * - the position in the menu at which to make the change
128 * - the number of items to delete from that position
129 * - a list of new items to insert at that position
131 * Each new menu item is a dictionary of attributes (a{sv}).
136 * label (string): the label to display
137 * action (string): the name of the action
138 * target (variant): the parameter to pass when activating the action
139 * :section ((uu)): the menu to use to populate that section, specified
140 * as a pair of subscription group and menu within that group
141 * :submenu ((uu)): the menu to use as a submenu, specified
142 * as a pair of subscription group and menu within that group
145 static GDBusInterfaceInfo *
146 org_gtk_Menus_get_interface (void)
148 static GDBusInterfaceInfo *interface_info;
150 if (interface_info == NULL)
152 GError *error = NULL;
155 info = g_dbus_node_info_new_for_xml ("<node>"
156 " <interface name='org.gtk.Menus'>"
157 " <method name='Start'>"
158 " <arg type='au' name='groups' direction='in'/>"
159 " <arg type='a(uuaa{sv})' name='content' direction='out'/>"
161 " <method name='End'>"
162 " <arg type='au' name='groups' direction='in'/>"
164 " <signal name='Changed'>"
165 " arg type='a(uuuuaa{sv})' name='changes'/>"
170 g_error ("%s\n", error->message);
171 interface_info = g_dbus_node_info_lookup_interface (info, "org.gtk.Menus");
172 g_assert (interface_info != NULL);
173 g_dbus_interface_info_ref (interface_info);
174 g_dbus_node_info_unref (info);
177 return interface_info;
180 /* {{{1 Forward declarations */
181 typedef struct _GMenuExporterMenu GMenuExporterMenu;
182 typedef struct _GMenuExporterLink GMenuExporterLink;
183 typedef struct _GMenuExporterGroup GMenuExporterGroup;
184 typedef struct _GMenuExporterRemote GMenuExporterRemote;
185 typedef struct _GMenuExporterWatch GMenuExporterWatch;
186 typedef struct _GMenuExporter GMenuExporter;
188 static gboolean g_menu_exporter_group_is_subscribed (GMenuExporterGroup *group);
189 static guint g_menu_exporter_group_get_id (GMenuExporterGroup *group);
190 static GMenuExporter * g_menu_exporter_group_get_exporter (GMenuExporterGroup *group);
191 static GMenuExporterMenu * g_menu_exporter_group_add_menu (GMenuExporterGroup *group,
193 static void g_menu_exporter_group_remove_menu (GMenuExporterGroup *group,
196 static GMenuExporterGroup * g_menu_exporter_create_group (GMenuExporter *exporter);
197 static GMenuExporterGroup * g_menu_exporter_lookup_group (GMenuExporter *exporter,
199 static void g_menu_exporter_report (GMenuExporter *exporter,
201 static void g_menu_exporter_remove_group (GMenuExporter *exporter,
204 /* {{{1 GMenuExporterLink, GMenuExporterMenu */
206 struct _GMenuExporterMenu
208 GMenuExporterGroup *group;
213 GSequence *item_links;
216 struct _GMenuExporterLink
219 GMenuExporterMenu *menu;
220 GMenuExporterLink *next;
224 g_menu_exporter_menu_free (GMenuExporterMenu *menu)
226 g_menu_exporter_group_remove_menu (menu->group, menu->id);
228 if (menu->handler_id != 0)
229 g_signal_handler_disconnect (menu->model, menu->handler_id);
231 if (menu->item_links != NULL)
232 g_sequence_free (menu->item_links);
234 g_object_unref (menu->model);
236 g_slice_free (GMenuExporterMenu, menu);
240 g_menu_exporter_link_free (gpointer data)
242 GMenuExporterLink *link = data;
246 GMenuExporterLink *tmp = link;
249 g_menu_exporter_menu_free (tmp->menu);
252 g_slice_free (GMenuExporterLink, tmp);
256 static GMenuExporterLink *
257 g_menu_exporter_menu_create_links (GMenuExporterMenu *menu,
260 GMenuExporterLink *list = NULL;
265 iter = g_menu_model_iterate_item_links (menu->model, position);
267 while (g_menu_link_iter_get_next (iter, &name, &model))
269 GMenuExporterGroup *group;
270 GMenuExporterLink *tmp;
272 /* keep sections in the same group, but create new groups
275 if (!g_str_equal (name, "section"))
276 group = g_menu_exporter_create_group (g_menu_exporter_group_get_exporter (menu->group));
280 tmp = g_slice_new (GMenuExporterLink);
281 tmp->name = g_strconcat (":", name, NULL);
282 tmp->menu = g_menu_exporter_group_add_menu (group, model);
286 g_object_unref (model);
289 g_object_unref (iter);
295 g_menu_exporter_menu_describe_item (GMenuExporterMenu *menu,
298 GMenuAttributeIter *attr_iter;
299 GVariantBuilder builder;
301 GMenuExporterLink *link;
305 g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT);
307 attr_iter = g_menu_model_iterate_item_attributes (menu->model, position);
308 while (g_menu_attribute_iter_get_next (attr_iter, &name, &value))
310 g_variant_builder_add (&builder, "{sv}", name, value);
311 g_variant_unref (value);
313 g_object_unref (attr_iter);
315 iter = g_sequence_get_iter_at_pos (menu->item_links, position);
316 for (link = g_sequence_get (iter); link; link = link->next)
317 g_variant_builder_add (&builder, "{sv}", link->name,
318 g_variant_new ("(uu)", g_menu_exporter_group_get_id (link->menu->group), link->menu->id));
320 return g_variant_builder_end (&builder);
324 g_menu_exporter_menu_list (GMenuExporterMenu *menu)
326 GVariantBuilder builder;
329 g_variant_builder_init (&builder, G_VARIANT_TYPE ("aa{sv}"));
331 n = g_sequence_get_length (menu->item_links);
332 for (i = 0; i < n; i++)
333 g_variant_builder_add_value (&builder, g_menu_exporter_menu_describe_item (menu, i));
335 return g_variant_builder_end (&builder);
339 g_menu_exporter_menu_items_changed (GMenuModel *model,
345 GMenuExporterMenu *menu = user_data;
346 GSequenceIter *point;
349 g_assert (menu->model == model);
350 g_assert (menu->item_links != NULL);
351 g_assert (position + removed <= g_sequence_get_length (menu->item_links));
353 point = g_sequence_get_iter_at_pos (menu->item_links, position + removed);
354 g_sequence_remove_range (g_sequence_get_iter_at_pos (menu->item_links, position), point);
356 for (i = position; i < position + added; i++)
357 g_sequence_insert_before (point, g_menu_exporter_menu_create_links (menu, i));
359 if (g_menu_exporter_group_is_subscribed (menu->group))
361 GVariantBuilder builder;
363 g_variant_builder_init (&builder, G_VARIANT_TYPE ("(uuuuaa{sv})"));
364 g_variant_builder_add (&builder, "u", g_menu_exporter_group_get_id (menu->group));
365 g_variant_builder_add (&builder, "u", menu->id);
366 g_variant_builder_add (&builder, "u", position);
367 g_variant_builder_add (&builder, "u", removed);
369 g_variant_builder_open (&builder, G_VARIANT_TYPE ("aa{sv}"));
370 for (i = position; i < position + added; i++)
371 g_variant_builder_add_value (&builder, g_menu_exporter_menu_describe_item (menu, i));
372 g_variant_builder_close (&builder);
374 g_menu_exporter_report (g_menu_exporter_group_get_exporter (menu->group), g_variant_builder_end (&builder));
379 g_menu_exporter_menu_prepare (GMenuExporterMenu *menu)
383 g_assert (menu->item_links == NULL);
385 if (g_menu_model_is_mutable (menu->model))
386 menu->handler_id = g_signal_connect (menu->model, "items-changed",
387 G_CALLBACK (g_menu_exporter_menu_items_changed), menu);
389 menu->item_links = g_sequence_new (g_menu_exporter_link_free);
391 n_items = g_menu_model_get_n_items (menu->model);
393 g_menu_exporter_menu_items_changed (menu->model, 0, 0, n_items, menu);
396 static GMenuExporterMenu *
397 g_menu_exporter_menu_new (GMenuExporterGroup *group,
401 GMenuExporterMenu *menu;
403 menu = g_slice_new0 (GMenuExporterMenu);
406 menu->model = g_object_ref (model);
411 /* {{{1 GMenuExporterGroup */
413 struct _GMenuExporterGroup
415 GMenuExporter *exporter;
426 g_menu_exporter_group_check_if_useless (GMenuExporterGroup *group)
428 if (g_hash_table_size (group->menus) == 0 && group->subscribed == 0)
430 g_menu_exporter_remove_group (group->exporter, group->id);
432 g_hash_table_unref (group->menus);
434 g_slice_free (GMenuExporterGroup, group);
439 g_menu_exporter_group_subscribe (GMenuExporterGroup *group,
440 GVariantBuilder *builder)
445 if (!group->prepared)
447 GMenuExporterMenu *menu;
449 /* set this first, so that any menus created during the
450 * preparation of the first menu also end up in the prepared
453 group->prepared = TRUE;
455 menu = g_hash_table_lookup (group->menus, 0);
456 g_menu_exporter_menu_prepare (menu);
461 g_hash_table_iter_init (&iter, group->menus);
462 while (g_hash_table_iter_next (&iter, &key, &val))
464 guint id = GPOINTER_TO_INT (key);
465 GMenuExporterMenu *menu = val;
467 if (g_sequence_get_length (menu->item_links))
469 g_variant_builder_open (builder, G_VARIANT_TYPE ("(uuaa{sv})"));
470 g_variant_builder_add (builder, "u", group->id);
471 g_variant_builder_add (builder, "u", id);
472 g_variant_builder_add_value (builder, g_menu_exporter_menu_list (menu));
473 g_variant_builder_close (builder);
479 g_menu_exporter_group_unsubscribe (GMenuExporterGroup *group,
482 g_assert (group->subscribed >= count);
484 group->subscribed -= count;
486 g_menu_exporter_group_check_if_useless (group);
489 static GMenuExporter *
490 g_menu_exporter_group_get_exporter (GMenuExporterGroup *group)
492 return group->exporter;
496 g_menu_exporter_group_is_subscribed (GMenuExporterGroup *group)
498 return group->subscribed > 0;
502 g_menu_exporter_group_get_id (GMenuExporterGroup *group)
508 g_menu_exporter_group_remove_menu (GMenuExporterGroup *group,
511 g_hash_table_remove (group->menus, GINT_TO_POINTER (id));
513 g_menu_exporter_group_check_if_useless (group);
516 static GMenuExporterMenu *
517 g_menu_exporter_group_add_menu (GMenuExporterGroup *group,
520 GMenuExporterMenu *menu;
523 id = group->next_menu_id++;
524 menu = g_menu_exporter_menu_new (group, id, model);
525 g_hash_table_insert (group->menus, GINT_TO_POINTER (id), menu);
528 g_menu_exporter_menu_prepare (menu);
533 static GMenuExporterGroup *
534 g_menu_exporter_group_new (GMenuExporter *exporter,
537 GMenuExporterGroup *group;
539 group = g_slice_new0 (GMenuExporterGroup);
540 group->menus = g_hash_table_new (NULL, NULL);
541 group->exporter = exporter;
547 /* {{{1 GMenuExporterRemote */
549 struct _GMenuExporterRemote
551 GMenuExporter *exporter;
557 g_menu_exporter_remote_subscribe (GMenuExporterRemote *remote,
559 GVariantBuilder *builder)
561 GMenuExporterGroup *group;
564 count = (gsize) g_hash_table_lookup (remote->watches, GINT_TO_POINTER (group_id));
565 g_hash_table_insert (remote->watches, GINT_TO_POINTER (group_id), GINT_TO_POINTER (count + 1));
567 group = g_menu_exporter_lookup_group (remote->exporter, group_id);
568 g_menu_exporter_group_subscribe (group, builder);
572 g_menu_exporter_remote_unsubscribe (GMenuExporterRemote *remote,
575 GMenuExporterGroup *group;
578 count = (gsize) g_hash_table_lookup (remote->watches, GINT_TO_POINTER (group_id));
584 g_hash_table_insert (remote->watches, GINT_TO_POINTER (group_id), GINT_TO_POINTER (count - 1));
586 g_hash_table_remove (remote->watches, GINT_TO_POINTER (group_id));
588 group = g_menu_exporter_lookup_group (remote->exporter, group_id);
589 g_menu_exporter_group_unsubscribe (group, 1);
593 g_menu_exporter_remote_has_subscriptions (GMenuExporterRemote *remote)
595 return g_hash_table_size (remote->watches) != 0;
599 g_menu_exporter_remote_free (gpointer data)
601 GMenuExporterRemote *remote = data;
605 g_hash_table_iter_init (&iter, remote->watches);
606 while (g_hash_table_iter_next (&iter, &key, &val))
608 GMenuExporterGroup *group;
610 group = g_menu_exporter_lookup_group (remote->exporter, GPOINTER_TO_INT (key));
611 g_menu_exporter_group_unsubscribe (group, GPOINTER_TO_INT (val));
614 g_bus_unwatch_name (remote->watch_id);
615 g_hash_table_unref (remote->watches);
617 g_slice_free (GMenuExporterRemote, remote);
620 static GMenuExporterRemote *
621 g_menu_exporter_remote_new (GMenuExporter *exporter,
624 GMenuExporterRemote *remote;
626 remote = g_slice_new0 (GMenuExporterRemote);
627 remote->exporter = exporter;
628 remote->watches = g_hash_table_new (NULL, NULL);
629 remote->watch_id = watch_id;
634 /* {{{1 GMenuExporter */
636 struct _GMenuExporter
638 GDBusConnection *connection;
640 guint registration_id;
644 GMenuExporterMenu *root;
649 g_menu_exporter_name_vanished (GDBusConnection *connection,
653 GMenuExporter *exporter = user_data;
655 g_assert (exporter->connection == connection);
657 g_hash_table_remove (exporter->remotes, name);
661 g_menu_exporter_subscribe (GMenuExporter *exporter,
665 GMenuExporterRemote *remote;
666 GVariantBuilder builder;
670 remote = g_hash_table_lookup (exporter->remotes, sender);
676 watch_id = g_bus_watch_name_on_connection (exporter->connection, sender, G_BUS_NAME_WATCHER_FLAGS_NONE,
677 NULL, g_menu_exporter_name_vanished, exporter, NULL);
678 remote = g_menu_exporter_remote_new (exporter, watch_id);
679 g_hash_table_insert (exporter->remotes, g_strdup (sender), remote);
682 g_variant_builder_init (&builder, G_VARIANT_TYPE ("(a(uuaa{sv}))"));
684 g_variant_builder_open (&builder, G_VARIANT_TYPE ("a(uuaa{sv})"));
686 g_variant_iter_init (&iter, group_ids);
687 while (g_variant_iter_next (&iter, "u", &id))
688 g_menu_exporter_remote_subscribe (remote, id, &builder);
690 g_variant_builder_close (&builder);
692 return g_variant_builder_end (&builder);
696 g_menu_exporter_unsubscribe (GMenuExporter *exporter,
700 GMenuExporterRemote *remote;
704 remote = g_hash_table_lookup (exporter->remotes, sender);
709 g_variant_iter_init (&iter, group_ids);
710 while (g_variant_iter_next (&iter, "u", &id))
711 g_menu_exporter_remote_unsubscribe (remote, id);
713 if (!g_menu_exporter_remote_has_subscriptions (remote))
714 g_hash_table_remove (exporter->remotes, sender);
718 g_menu_exporter_report (GMenuExporter *exporter,
721 GVariantBuilder builder;
723 g_variant_builder_init (&builder, G_VARIANT_TYPE_TUPLE);
724 g_variant_builder_open (&builder, G_VARIANT_TYPE_ARRAY);
725 g_variant_builder_add_value (&builder, report);
726 g_variant_builder_close (&builder);
728 g_dbus_connection_emit_signal (exporter->connection,
730 exporter->object_path,
731 "org.gtk.Menus", "Changed",
732 g_variant_builder_end (&builder),
737 g_menu_exporter_remove_group (GMenuExporter *exporter,
740 g_hash_table_remove (exporter->groups, GINT_TO_POINTER (id));
743 static GMenuExporterGroup *
744 g_menu_exporter_lookup_group (GMenuExporter *exporter,
747 GMenuExporterGroup *group;
749 group = g_hash_table_lookup (exporter->groups, GINT_TO_POINTER (group_id));
753 group = g_menu_exporter_group_new (exporter, group_id);
754 g_hash_table_insert (exporter->groups, GINT_TO_POINTER (group_id), group);
760 static GMenuExporterGroup *
761 g_menu_exporter_create_group (GMenuExporter *exporter)
763 GMenuExporterGroup *group;
766 id = exporter->next_group_id++;
767 group = g_menu_exporter_group_new (exporter, id);
768 g_hash_table_insert (exporter->groups, GINT_TO_POINTER (id), group);
774 g_menu_exporter_free (gpointer user_data)
776 GMenuExporter *exporter = user_data;
778 g_menu_exporter_menu_free (exporter->root);
779 g_hash_table_unref (exporter->remotes);
780 g_hash_table_unref (exporter->groups);
781 g_object_unref (exporter->connection);
782 g_free (exporter->object_path);
784 g_slice_free (GMenuExporter, exporter);
788 g_menu_exporter_method_call (GDBusConnection *connection,
790 const gchar *object_path,
791 const gchar *interface_name,
792 const gchar *method_name,
793 GVariant *parameters,
794 GDBusMethodInvocation *invocation,
797 GMenuExporter *exporter = user_data;
800 group_ids = g_variant_get_child_value (parameters, 0);
802 if (g_str_equal (method_name, "Start"))
803 g_dbus_method_invocation_return_value (invocation, g_menu_exporter_subscribe (exporter, sender, group_ids));
805 else if (g_str_equal (method_name, "End"))
807 g_menu_exporter_unsubscribe (exporter, sender, group_ids);
808 g_dbus_method_invocation_return_value (invocation, NULL);
812 g_assert_not_reached ();
814 g_variant_unref (group_ids);
817 /* {{{1 Public API */
820 * g_dbus_connection_export_menu_model:
821 * @connection: a #GDBusConnection
822 * @object_path: a D-Bus object path
823 * @menu: a #GMenuModel
824 * @error: return location for an error, or %NULL
826 * Exports @menu on @connection at @object_path.
828 * The implemented D-Bus API should be considered private.
829 * It is subject to change in the future.
831 * An object path can only have one action group exported on it. If this
832 * constraint is violated, the export will fail and 0 will be
833 * returned (with @error set accordingly).
835 * You can unexport the menu model using
836 * g_dbus_connection_unexport_menu_model() with the return value of
839 * Returns: the ID of the export (never zero), or 0 in case of failure
844 g_dbus_connection_export_menu_model (GDBusConnection *connection,
845 const gchar *object_path,
849 const GDBusInterfaceVTable vtable = {
850 g_menu_exporter_method_call,
852 GMenuExporter *exporter;
855 exporter = g_slice_new0 (GMenuExporter);
857 id = g_dbus_connection_register_object (connection, object_path, org_gtk_Menus_get_interface (),
858 &vtable, exporter, g_menu_exporter_free, error);
862 g_slice_free (GMenuExporter, exporter);
866 exporter->connection = g_object_ref (connection);
867 exporter->object_path = g_strdup (object_path);
868 exporter->groups = g_hash_table_new (NULL, NULL);
869 exporter->remotes = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, g_menu_exporter_remote_free);
870 exporter->root = g_menu_exporter_group_add_menu (g_menu_exporter_create_group (exporter), menu);
876 * g_dbus_connection_unexport_menu_model:
877 * @connection: a #GDBusConnection
878 * @export_id: the ID from g_dbus_connection_export_menu_model()
880 * Reverses the effect of a previous call to
881 * g_dbus_connection_export_menu_model().
883 * It is an error to call this function with an ID that wasn't returned
884 * from g_dbus_connection_export_menu_model() or to call it with the
885 * same ID more than once.
890 g_dbus_connection_unexport_menu_model (GDBusConnection *connection,
893 g_dbus_connection_unregister_object (connection, export_id);
897 /* vim:set foldmethod=marker: */