glib: Improve documentation for g_strfreev()
[platform/upstream/glib.git] / gio / gactiongroupexporter.c
1 /*
2  * Copyright © 2010 Codethink Limited
3  * Copyright © 2011 Canonical Limited
4  *
5  * This program is free software: you can redistribute it and/or modify
6  * it under the terms of the GNU Lesser General Public License as published
7  * by the Free Software Foundation; either version 2 of the licence or (at
8  * your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General
16  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
17  *
18  * Authors: Ryan Lortie <desrt@desrt.ca>
19  */
20
21 #include "config.h"
22
23 #include "gactiongroupexporter.h"
24
25 #include "gdbusmethodinvocation.h"
26 #include "gremoteactiongroup.h"
27 #include "gdbusintrospection.h"
28 #include "gdbusconnection.h"
29 #include "gactiongroup.h"
30 #include "gdbuserror.h"
31
32 /**
33  * SECTION:gactiongroupexporter
34  * @title: GActionGroup exporter
35  * @include: gio/gio.h
36  * @short_description: Export GActionGroups on D-Bus
37  * @see_also: #GActionGroup, #GDBusActionGroup
38  *
39  * These functions support exporting a #GActionGroup on D-Bus.
40  * The D-Bus interface that is used is a private implementation
41  * detail.
42  *
43  * To access an exported #GActionGroup remotely, use
44  * g_dbus_action_group_get() to obtain a #GDBusActionGroup.
45  */
46
47 static GVariant *
48 g_action_group_describe_action (GActionGroup *action_group,
49                                 const gchar  *name)
50 {
51   const GVariantType *type;
52   GVariantBuilder builder;
53   gboolean enabled;
54   GVariant *state;
55
56   g_variant_builder_init (&builder, G_VARIANT_TYPE ("(bgav)"));
57
58   enabled = g_action_group_get_action_enabled (action_group, name);
59   g_variant_builder_add (&builder, "b", enabled);
60
61   if ((type = g_action_group_get_action_parameter_type (action_group, name)))
62     {
63       gchar *str = g_variant_type_dup_string (type);
64       g_variant_builder_add (&builder, "g", str);
65       g_free (str);
66     }
67   else
68     g_variant_builder_add (&builder, "g", "");
69
70   g_variant_builder_open (&builder, G_VARIANT_TYPE ("av"));
71   if ((state = g_action_group_get_action_state (action_group, name)))
72     {
73       g_variant_builder_add (&builder, "v", state);
74       g_variant_unref (state);
75     }
76   g_variant_builder_close (&builder);
77
78   return g_variant_builder_end (&builder);
79 }
80
81 /* Using XML saves us dozens of relocations vs. using the introspection
82  * structure types.  We only need to burn cycles and memory if we
83  * actually use the exporter -- not in every single app using GIO.
84  *
85  * It's also a lot easier to read. :)
86  *
87  * For documentation of this interface, see
88  * https://wiki.gnome.org/Projects/GLib/GApplication/DBusAPI
89  */
90 const char org_gtk_Actions_xml[] =
91   "<node>"
92   "  <interface name='org.gtk.Actions'>"
93   "    <method name='List'>"
94   "      <arg type='as' name='list' direction='out'/>"
95   "    </method>"
96   "    <method name='Describe'>"
97   "      <arg type='s' name='action_name' direction='in'/>"
98   "      <arg type='(bgav)' name='description' direction='out'/>"
99   "    </method>"
100   "    <method name='DescribeAll'>"
101   "      <arg type='a{s(bgav)}' name='descriptions' direction='out'/>"
102   "    </method>"
103   "    <method name='Activate'>"
104   "      <arg type='s' name='action_name' direction='in'/>"
105   "      <arg type='av' name='parameter' direction='in'/>"
106   "      <arg type='a{sv}' name='platform_data' direction='in'/>"
107   "    </method>"
108   "    <method name='SetState'>"
109   "      <arg type='s' name='action_name' direction='in'/>"
110   "      <arg type='v' name='value' direction='in'/>"
111   "      <arg type='a{sv}' name='platform_data' direction='in'/>"
112   "    </method>"
113   "    <signal name='Changed'>"
114   "      <arg type='as' name='removals'/>"
115   "      <arg type='a{sb}' name='enable_changes'/>"
116   "      <arg type='a{sv}' name='state_changes'/>"
117   "      <arg type='a{s(bgav)}' name='additions'/>"
118   "    </signal>"
119   "  </interface>"
120   "</node>";
121
122 static GDBusInterfaceInfo *org_gtk_Actions;
123
124 typedef struct
125 {
126   GActionGroup    *action_group;
127   GDBusConnection *connection;
128   GMainContext    *context;
129   gchar           *object_path;
130   GHashTable      *pending_changes;
131   GSource         *pending_source;
132 } GActionGroupExporter;
133
134 #define ACTION_ADDED_EVENT             (1u<<0)
135 #define ACTION_REMOVED_EVENT           (1u<<1)
136 #define ACTION_STATE_CHANGED_EVENT     (1u<<2)
137 #define ACTION_ENABLED_CHANGED_EVENT   (1u<<3)
138
139 static gboolean
140 g_action_group_exporter_dispatch_events (gpointer user_data)
141 {
142   GActionGroupExporter *exporter = user_data;
143   GVariantBuilder removes;
144   GVariantBuilder enabled_changes;
145   GVariantBuilder state_changes;
146   GVariantBuilder adds;
147   GHashTableIter iter;
148   gpointer value;
149   gpointer key;
150
151   g_variant_builder_init (&removes, G_VARIANT_TYPE_STRING_ARRAY);
152   g_variant_builder_init (&enabled_changes, G_VARIANT_TYPE ("a{sb}"));
153   g_variant_builder_init (&state_changes, G_VARIANT_TYPE ("a{sv}"));
154   g_variant_builder_init (&adds, G_VARIANT_TYPE ("a{s(bgav)}"));
155
156   g_hash_table_iter_init (&iter, exporter->pending_changes);
157   while (g_hash_table_iter_next (&iter, &key, &value))
158     {
159       guint events = GPOINTER_TO_INT (value);
160       const gchar *name = key;
161
162       /* Adds and removes are incompatible with enabled or state
163        * changes, but we must report at least one event.
164        */
165       g_assert (((events & (ACTION_ENABLED_CHANGED_EVENT | ACTION_STATE_CHANGED_EVENT)) == 0) !=
166                 ((events & (ACTION_REMOVED_EVENT | ACTION_ADDED_EVENT)) == 0));
167
168       if (events & ACTION_REMOVED_EVENT)
169         g_variant_builder_add (&removes, "s", name);
170
171       if (events & ACTION_ENABLED_CHANGED_EVENT)
172         {
173           gboolean enabled;
174
175           enabled = g_action_group_get_action_enabled (exporter->action_group, name);
176           g_variant_builder_add (&enabled_changes, "{sb}", name, enabled);
177         }
178
179       if (events & ACTION_STATE_CHANGED_EVENT)
180         {
181           GVariant *state;
182
183           state = g_action_group_get_action_state (exporter->action_group, name);
184           g_variant_builder_add (&state_changes, "{sv}", name, state);
185           g_variant_unref (state);
186         }
187
188       if (events & ACTION_ADDED_EVENT)
189         {
190           GVariant *description;
191
192           description = g_action_group_describe_action (exporter->action_group, name);
193           g_variant_builder_add (&adds, "{s@(bgav)}", name, description);
194         }
195     }
196
197   g_hash_table_remove_all (exporter->pending_changes);
198
199   g_dbus_connection_emit_signal (exporter->connection, NULL, exporter->object_path,
200                                  "org.gtk.Actions", "Changed",
201                                  g_variant_new ("(asa{sb}a{sv}a{s(bgav)})",
202                                                 &removes, &enabled_changes,
203                                                 &state_changes, &adds),
204                                  NULL);
205
206   exporter->pending_source = NULL;
207
208   return FALSE;
209 }
210
211 static guint
212 g_action_group_exporter_get_events (GActionGroupExporter *exporter,
213                                     const gchar          *name)
214 {
215   return (gsize) g_hash_table_lookup (exporter->pending_changes, name);
216 }
217
218 static void
219 g_action_group_exporter_set_events (GActionGroupExporter *exporter,
220                                     const gchar          *name,
221                                     guint                 events)
222 {
223   gboolean have_events;
224   gboolean is_queued;
225
226   if (events != 0)
227     g_hash_table_insert (exporter->pending_changes, g_strdup (name), GINT_TO_POINTER (events));
228   else
229     g_hash_table_remove (exporter->pending_changes, name);
230
231   have_events = g_hash_table_size (exporter->pending_changes) > 0;
232   is_queued = exporter->pending_source != NULL;
233
234   if (have_events && !is_queued)
235     {
236       GSource *source;
237
238       source = g_idle_source_new ();
239       exporter->pending_source = source;
240       g_source_set_callback (source, g_action_group_exporter_dispatch_events, exporter, NULL);
241       g_source_set_name (source, "[gio] g_action_group_exporter_dispatch_events");
242       g_source_attach (source, exporter->context);
243       g_source_unref (source);
244     }
245
246   if (!have_events && is_queued)
247     {
248       g_source_destroy (exporter->pending_source);
249       exporter->pending_source = NULL;
250     }
251 }
252
253 static void
254 g_action_group_exporter_action_added (GActionGroup *action_group,
255                                       const gchar  *action_name,
256                                       gpointer      user_data)
257 {
258   GActionGroupExporter *exporter = user_data;
259   guint event_mask;
260
261   event_mask = g_action_group_exporter_get_events (exporter, action_name);
262
263   /* The action is new, so we should not have any pending
264    * enabled-changed or state-changed signals for it.
265    */
266   g_assert (~event_mask & (ACTION_STATE_CHANGED_EVENT |
267                            ACTION_ENABLED_CHANGED_EVENT));
268
269   event_mask |= ACTION_ADDED_EVENT;
270
271   g_action_group_exporter_set_events (exporter, action_name, event_mask);
272 }
273
274 static void
275 g_action_group_exporter_action_removed (GActionGroup *action_group,
276                                         const gchar  *action_name,
277                                         gpointer      user_data)
278 {
279   GActionGroupExporter *exporter = user_data;
280   guint event_mask;
281
282   event_mask = g_action_group_exporter_get_events (exporter, action_name);
283
284   /* If the add event for this is still queued then just cancel it since
285    * it's gone now.
286    *
287    * If the event was freshly added, there should not have been any
288    * enabled or state changed events.
289    */
290   if (event_mask & ACTION_ADDED_EVENT)
291     {
292       g_assert (~event_mask & ~(ACTION_STATE_CHANGED_EVENT | ACTION_ENABLED_CHANGED_EVENT));
293       event_mask &= ~ACTION_ADDED_EVENT;
294     }
295
296   /* Otherwise, queue a remove event.  Drop any state or enabled changes
297    * that were queued before the remove. */
298   else
299     {
300       event_mask |= ACTION_REMOVED_EVENT;
301       event_mask &= ~(ACTION_STATE_CHANGED_EVENT | ACTION_ENABLED_CHANGED_EVENT);
302     }
303
304   g_action_group_exporter_set_events (exporter, action_name, event_mask);
305 }
306
307 static void
308 g_action_group_exporter_action_state_changed (GActionGroup *action_group,
309                                               const gchar  *action_name,
310                                               GVariant     *value,
311                                               gpointer      user_data)
312 {
313   GActionGroupExporter *exporter = user_data;
314   guint event_mask;
315
316   event_mask = g_action_group_exporter_get_events (exporter, action_name);
317
318   /* If it was removed, it must have been added back.  Otherwise, why
319    * are we hearing about changes?
320    */
321   g_assert (~event_mask & ACTION_REMOVED_EVENT ||
322             event_mask & ACTION_ADDED_EVENT);
323
324   /* If it is freshly added, don't also bother with the state change
325    * signal since the updated state will be sent as part of the pending
326    * add message.
327    */
328   if (~event_mask & ACTION_ADDED_EVENT)
329     event_mask |= ACTION_STATE_CHANGED_EVENT;
330
331   g_action_group_exporter_set_events (exporter, action_name, event_mask);
332 }
333
334 static void
335 g_action_group_exporter_action_enabled_changed (GActionGroup *action_group,
336                                                 const gchar  *action_name,
337                                                 gboolean      enabled,
338                                                 gpointer      user_data)
339 {
340   GActionGroupExporter *exporter = user_data;
341   guint event_mask;
342
343   event_mask = g_action_group_exporter_get_events (exporter, action_name);
344
345   /* Reasoning as above. */
346   g_assert (~event_mask & ACTION_REMOVED_EVENT ||
347             event_mask & ACTION_ADDED_EVENT);
348
349   if (~event_mask & ACTION_ADDED_EVENT)
350     event_mask |= ACTION_ENABLED_CHANGED_EVENT;
351
352   g_action_group_exporter_set_events (exporter, action_name, event_mask);
353 }
354
355 static void
356 org_gtk_Actions_method_call (GDBusConnection       *connection,
357                              const gchar           *sender,
358                              const gchar           *object_path,
359                              const gchar           *interface_name,
360                              const gchar           *method_name,
361                              GVariant              *parameters,
362                              GDBusMethodInvocation *invocation,
363                              gpointer               user_data)
364 {
365   GActionGroupExporter *exporter = user_data;
366   GVariant *result = NULL;
367
368   if (g_str_equal (method_name, "List"))
369     {
370       gchar **list;
371
372       list = g_action_group_list_actions (exporter->action_group);
373       result = g_variant_new ("(^as)", list);
374       g_strfreev (list);
375     }
376
377   else if (g_str_equal (method_name, "Describe"))
378     {
379       const gchar *name;
380       GVariant *desc;
381
382       g_variant_get (parameters, "(&s)", &name);
383
384       if (!g_action_group_has_action (exporter->action_group, name))
385         {
386           g_dbus_method_invocation_return_error (invocation, G_DBUS_ERROR, G_DBUS_ERROR_INVALID_ARGS,
387                                                  "The named action ('%s') does not exist.", name);
388           return;
389         }
390
391       desc = g_action_group_describe_action (exporter->action_group, name);
392       result = g_variant_new ("(@(bgav))", desc);
393     }
394
395   else if (g_str_equal (method_name, "DescribeAll"))
396     {
397       GVariantBuilder builder;
398       gchar **list;
399       gint i;
400
401       list = g_action_group_list_actions (exporter->action_group);
402       g_variant_builder_init (&builder, G_VARIANT_TYPE ("a{s(bgav)}"));
403       for (i = 0; list[i]; i++)
404         {
405           const gchar *name = list[i];
406           GVariant *description;
407
408           description = g_action_group_describe_action (exporter->action_group, name);
409           g_variant_builder_add (&builder, "{s@(bgav)}", name, description);
410         }
411       result = g_variant_new ("(a{s(bgav)})", &builder);
412       g_strfreev (list);
413     }
414
415   else if (g_str_equal (method_name, "Activate"))
416     {
417       GVariant *parameter = NULL;
418       GVariant *platform_data;
419       GVariantIter *iter;
420       const gchar *name;
421
422       g_variant_get (parameters, "(&sav@a{sv})", &name, &iter, &platform_data);
423       g_variant_iter_next (iter, "v", &parameter);
424       g_variant_iter_free (iter);
425
426       if (G_IS_REMOTE_ACTION_GROUP (exporter->action_group))
427         g_remote_action_group_activate_action_full (G_REMOTE_ACTION_GROUP (exporter->action_group),
428                                                     name, parameter, platform_data);
429       else
430         g_action_group_activate_action (exporter->action_group, name, parameter);
431
432       if (parameter)
433         g_variant_unref (parameter);
434
435       g_variant_unref (platform_data);
436     }
437
438   else if (g_str_equal (method_name, "SetState"))
439     {
440       GVariant *platform_data;
441       const gchar *name;
442       GVariant *state;
443
444       g_variant_get (parameters, "(&sv@a{sv})", &name, &state, &platform_data);
445
446       if (G_IS_REMOTE_ACTION_GROUP (exporter->action_group))
447         g_remote_action_group_change_action_state_full (G_REMOTE_ACTION_GROUP (exporter->action_group),
448                                                         name, state, platform_data);
449       else
450         g_action_group_change_action_state (exporter->action_group, name, state);
451
452       g_variant_unref (platform_data);
453       g_variant_unref (state);
454     }
455
456   else
457     g_assert_not_reached ();
458
459   g_dbus_method_invocation_return_value (invocation, result);
460 }
461
462 static void
463 g_action_group_exporter_free (gpointer user_data)
464 {
465   GActionGroupExporter *exporter = user_data;
466
467   g_signal_handlers_disconnect_by_func (exporter->action_group,
468                                         g_action_group_exporter_action_added, exporter);
469   g_signal_handlers_disconnect_by_func (exporter->action_group,
470                                         g_action_group_exporter_action_enabled_changed, exporter);
471   g_signal_handlers_disconnect_by_func (exporter->action_group,
472                                         g_action_group_exporter_action_state_changed, exporter);
473   g_signal_handlers_disconnect_by_func (exporter->action_group,
474                                         g_action_group_exporter_action_removed, exporter);
475
476   g_hash_table_unref (exporter->pending_changes);
477   if (exporter->pending_source)
478     g_source_destroy (exporter->pending_source);
479
480   g_main_context_unref (exporter->context);
481   g_object_unref (exporter->connection);
482   g_object_unref (exporter->action_group);
483   g_free (exporter->object_path);
484
485   g_slice_free (GActionGroupExporter, exporter);
486 }
487
488 /**
489  * g_dbus_connection_export_action_group:
490  * @connection: a #GDBusConnection
491  * @object_path: a D-Bus object path
492  * @action_group: a #GActionGroup
493  * @error: a pointer to a %NULL #GError, or %NULL
494  *
495  * Exports @action_group on @connection at @object_path.
496  *
497  * The implemented D-Bus API should be considered private.  It is
498  * subject to change in the future.
499  *
500  * A given object path can only have one action group exported on it.
501  * If this constraint is violated, the export will fail and 0 will be
502  * returned (with @error set accordingly).
503  *
504  * You can unexport the action group using
505  * g_dbus_connection_unexport_action_group() with the return value of
506  * this function.
507  *
508  * The thread default main context is taken at the time of this call.
509  * All incoming action activations and state change requests are
510  * reported from this context.  Any changes on the action group that
511  * cause it to emit signals must also come from this same context.
512  * Since incoming action activations and state change requests are
513  * rather likely to cause changes on the action group, this effectively
514  * limits a given action group to being exported from only one main
515  * context.
516  *
517  * Returns: the ID of the export (never zero), or 0 in case of failure
518  *
519  * Since: 2.32
520  **/
521 guint
522 g_dbus_connection_export_action_group (GDBusConnection  *connection,
523                                        const gchar      *object_path,
524                                        GActionGroup     *action_group,
525                                        GError          **error)
526 {
527   const GDBusInterfaceVTable vtable = {
528     org_gtk_Actions_method_call
529   };
530   GActionGroupExporter *exporter;
531   guint id;
532
533   if G_UNLIKELY (org_gtk_Actions == NULL)
534     {
535       GError *error = NULL;
536       GDBusNodeInfo *info;
537
538       info = g_dbus_node_info_new_for_xml (org_gtk_Actions_xml, &error);
539       if G_UNLIKELY (info == NULL)
540         g_error ("%s", error->message);
541       org_gtk_Actions = g_dbus_node_info_lookup_interface (info, "org.gtk.Actions");
542       g_assert (org_gtk_Actions != NULL);
543       g_dbus_interface_info_ref (org_gtk_Actions);
544       g_dbus_node_info_unref (info);
545     }
546
547   exporter = g_slice_new (GActionGroupExporter);
548   id = g_dbus_connection_register_object (connection, object_path, org_gtk_Actions, &vtable,
549                                           exporter, g_action_group_exporter_free, error);
550
551   if (id == 0)
552     {
553       g_slice_free (GActionGroupExporter, exporter);
554       return 0;
555     }
556
557   exporter->context = g_main_context_ref_thread_default ();
558   exporter->pending_changes = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, NULL);
559   exporter->pending_source = NULL;
560   exporter->action_group = g_object_ref (action_group);
561   exporter->connection = g_object_ref (connection);
562   exporter->object_path = g_strdup (object_path);
563
564   g_signal_connect (action_group, "action-added",
565                     G_CALLBACK (g_action_group_exporter_action_added), exporter);
566   g_signal_connect (action_group, "action-removed",
567                     G_CALLBACK (g_action_group_exporter_action_removed), exporter);
568   g_signal_connect (action_group, "action-state-changed",
569                     G_CALLBACK (g_action_group_exporter_action_state_changed), exporter);
570   g_signal_connect (action_group, "action-enabled-changed",
571                     G_CALLBACK (g_action_group_exporter_action_enabled_changed), exporter);
572
573   return id;
574 }
575
576 /**
577  * g_dbus_connection_unexport_action_group:
578  * @connection: a #GDBusConnection
579  * @export_id: the ID from g_dbus_connection_export_action_group()
580  *
581  * Reverses the effect of a previous call to
582  * g_dbus_connection_export_action_group().
583  *
584  * It is an error to call this function with an ID that wasn't returned
585  * from g_dbus_connection_export_action_group() or to call it with the
586  * same ID more than once.
587  *
588  * Since: 2.32
589  **/
590 void
591 g_dbus_connection_unexport_action_group (GDBusConnection *connection,
592                                          guint            export_id)
593 {
594   g_dbus_connection_unregister_object (connection, export_id);
595 }