2 * Copyright © 2010 Codethink Limited
3 * Copyright © 2011 Canonical Limited
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.
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.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Authors: Ryan Lortie <desrt@desrt.ca>
25 #include "gactiongroupexporter.h"
27 #include "gdbusmethodinvocation.h"
28 #include "gdbusintrospection.h"
29 #include "gdbusconnection.h"
30 #include "gactiongroup.h"
31 #include "gapplication.h"
32 #include "gdbuserror.h"
35 * SECTION:gactiongroupexporter
36 * @title: GActionGroup exporter
37 * @short_description: Export GActionGroups on D-Bus
38 * @see_also: #GActionGroup, #GDBusActionGroup
40 * These functions support exporting a #GActionGroup on D-Bus.
41 * The D-Bus interface that is used is a private implementation
44 * To access an exported #GActionGroup remotely, use
45 * g_dbus_action_group_new() to obtain a #GDBusActionGroup.
48 G_GNUC_INTERNAL GVariant
*
49 g_action_group_describe_action (GActionGroup
*action_group
,
52 const GVariantType
*type
;
53 GVariantBuilder builder
;
57 g_variant_builder_init (&builder
, G_VARIANT_TYPE ("(bgav)"));
59 enabled
= g_action_group_get_action_enabled (action_group
, name
);
60 g_variant_builder_add (&builder
, "b", enabled
);
62 if ((type
= g_action_group_get_action_parameter_type (action_group
, name
)))
64 gchar
*str
= g_variant_type_dup_string (type
);
65 g_variant_builder_add (&builder
, "g", str
);
69 g_variant_builder_add (&builder
, "g", "");
71 g_variant_builder_open (&builder
, G_VARIANT_TYPE ("av"));
72 if ((state
= g_action_group_get_action_state (action_group
, name
)))
74 g_variant_builder_add (&builder
, "v", state
);
75 g_variant_unref (state
);
77 g_variant_builder_close (&builder
);
79 return g_variant_builder_end (&builder
);
82 /* The org.gtk.Actions interface
83 * =============================
85 * This interface describes a group of actions.
88 * - has a unique string name
90 * - optionally has a parameter type that must be given to the activation
91 * - has an enabled state that may be true or false
92 * - optionally has a state which can change value, but not type
99 * Lists the names of the actions exported at this object path.
101 * Describe :: (s) → (bgav)
103 * Describes a single action, or a given name.
105 * The return value has the following components:
106 * b: specifies if the action is currently enabled. This is
107 * a hint that attempting to interact with the action will
109 * g: specifies the optional parameter type. If not "",
110 * the string specifies the type of argument that must
111 * be passed to the activation.
112 * av: specifies the optional state. If not empty, the array
113 * contains the current value of the state as a variant
115 * DescribeAll :: () → (a{s(bgav)})
117 * Describes all actions in a single round-trip.
119 * The dictionary maps action name strings to their descriptions
120 * (in the format discussed above).
122 * Activate :: (sava{sv}) → ()
124 * Requests activation of the named action.
126 * The action is named by the first parameter (s).
128 * If the action activation requires a parameter then this parameter
129 * must be given in the second parameter (av). If there is no parameter
130 * to be specified, the array must be empty.
132 * The final parameter (a{sv}) is a list of "platform data".
134 * This method is not guaranteed to have any particular effect. The
135 * implementation may take some action (including changing the state
136 * of the action, if it is stateful) or it may take none at all. In
137 * particular, callers should expect their request to be completely
138 * ignored when the enabled flag is false (but even this is not
141 * SetState :: (sva{sv}) → ()
143 * Requests the state of an action to be changed to the given value.
145 * The action is named by the first parameter (s).
147 * The requested new state is given in the second parameter (v).
148 * It must be equal in type to the existing state.
150 * The final parameter (a{sv}) is a list of "platform data".
152 * This method is not guaranteed to have any particular effect.
153 * The implementation of an action can choose to ignore the requested
154 * state change, or choose to change its state to something else or
155 * to trigger other side effects. In particular, callers should expect
156 * their request to be completely ignored when the enabled flag is
157 * false (but even this is not guaranteed).
162 * Changed :: (asa{sb}a{sv}a{s(bgav)})
164 * Signals that some change has occured to the action group.
166 * Four separate types of changes are possible, and the 4 parameters
167 * of the change signal reflect these possibilities:
168 * as: a list of removed actions
169 * a{sb}: a list of actions that had their enabled flag changed
170 * a{sv}: a list of actions that had their state changed
171 * a{s(bgav)}: a list of new actions added in the same format as
172 * the return value of the DescribeAll method
175 /* Using XML saves us dozens of relocations vs. using the introspection
176 * structure types. We only need to burn cycles and memory if we
177 * actually use the exporter -- not in every single app using GIO.
179 * It's also a lot easier to read. :)
181 const char org_gtk_Actions_xml
[] =
183 " <interface name='org.gtk.Actions'>"
184 " <method name='List'>"
185 " <arg type='as' name='list' direction='out'/>"
187 " <method name='Describe'>"
188 " <arg type='s' name='action_name' direction='in'/>"
189 " <arg type='(bgav)' name='description' direction='out'/>"
191 " <method name='DescribeAll'>"
192 " <arg type='a{s(bgav)}' name='descriptions' direction='out'/>"
194 " <method name='Activate'>"
195 " <arg type='s' name='action_name' direction='in'/>"
196 " <arg type='av' name='parameter' direction='in'/>"
197 " <arg type='a{sv}' name='platform_data' direction='in'/>"
199 " <method name='SetState'>"
200 " <arg type='s' name='action_name' direction='in'/>"
201 " <arg type='v' name='value' direction='in'/>"
202 " <arg type='a{sv}' name='platform_data' direction='in'/>"
204 " <signal name='Changed'>"
205 " <arg type='as' name='removals'/>"
206 " <arg type='a{sb}' name='enable_changes'/>"
207 " <arg type='a{sv}' name='state_changes'/>"
208 " <arg type='a{s(bgav)}' name='additions'/>"
213 static GDBusInterfaceInfo
*org_gtk_Actions
;
217 GActionGroup
*action_group
;
218 GDBusConnection
*connection
;
220 GHashTable
*pending_changes
;
222 gulong signal_ids
[4];
223 } GActionGroupExporter
;
225 #define ACTION_ADDED_EVENT (1u<<0)
226 #define ACTION_REMOVED_EVENT (1u<<1)
227 #define ACTION_STATE_CHANGED_EVENT (1u<<2)
228 #define ACTION_ENABLED_CHANGED_EVENT (1u<<3)
231 g_action_group_exporter_dispatch_events (gpointer user_data
)
233 GActionGroupExporter
*exporter
= user_data
;
234 GVariantBuilder removes
;
235 GVariantBuilder enabled_changes
;
236 GVariantBuilder state_changes
;
237 GVariantBuilder adds
;
242 g_variant_builder_init (&removes
, G_VARIANT_TYPE_STRING_ARRAY
);
243 g_variant_builder_init (&enabled_changes
, G_VARIANT_TYPE ("a{sb}"));
244 g_variant_builder_init (&state_changes
, G_VARIANT_TYPE ("a{sv}"));
245 g_variant_builder_init (&adds
, G_VARIANT_TYPE ("a{s(bgav)}"));
247 g_hash_table_iter_init (&iter
, exporter
->pending_changes
);
248 while (g_hash_table_iter_next (&iter
, &key
, &value
))
250 guint events
= GPOINTER_TO_INT (value
);
251 const gchar
*name
= key
;
253 /* Adds and removes are incompatible with enabled or state
254 * changes, but we must report at least one event.
256 g_assert (((events
& (ACTION_ENABLED_CHANGED_EVENT
| ACTION_STATE_CHANGED_EVENT
)) == 0) !=
257 ((events
& (ACTION_REMOVED_EVENT
| ACTION_ADDED_EVENT
)) == 0));
259 if (events
& ACTION_REMOVED_EVENT
)
260 g_variant_builder_add (&removes
, "s", name
);
262 if (events
& ACTION_ENABLED_CHANGED_EVENT
)
266 enabled
= g_action_group_get_action_enabled (exporter
->action_group
, name
);
267 g_variant_builder_add (&enabled_changes
, "{sb}", name
, enabled
);
270 if (events
& ACTION_STATE_CHANGED_EVENT
)
274 state
= g_action_group_get_action_state (exporter
->action_group
, name
);
275 g_variant_builder_add (&state_changes
, "{sv}", name
, state
);
276 g_variant_unref (state
);
279 if (events
& ACTION_ADDED_EVENT
)
281 GVariant
*description
;
283 description
= g_action_group_describe_action (exporter
->action_group
, name
);
284 g_variant_builder_add (&adds
, "{s@(bgav)}", name
, description
);
288 g_hash_table_remove_all (exporter
->pending_changes
);
290 g_dbus_connection_emit_signal (exporter
->connection
, NULL
, exporter
->object_path
,
291 "org.gtk.Actions", "Changed",
292 g_variant_new ("(asa{sb}a{sv}a{s(bgav)})",
293 &removes
, &enabled_changes
,
294 &state_changes
, &adds
),
297 exporter
->pending_id
= 0;
303 g_action_group_exporter_get_events (GActionGroupExporter
*exporter
,
306 return (gsize
) g_hash_table_lookup (exporter
->pending_changes
, name
);
310 g_action_group_exporter_set_events (GActionGroupExporter
*exporter
,
314 gboolean have_events
;
318 g_hash_table_insert (exporter
->pending_changes
, g_strdup (name
), GINT_TO_POINTER (events
));
320 g_hash_table_remove (exporter
->pending_changes
, name
);
322 have_events
= g_hash_table_size (exporter
->pending_changes
) > 0;
323 is_queued
= exporter
->pending_id
> 0;
325 if (have_events
&& !is_queued
)
326 exporter
->pending_id
= g_idle_add (g_action_group_exporter_dispatch_events
, exporter
);
328 if (!have_events
&& is_queued
)
330 g_source_remove (exporter
->pending_id
);
331 exporter
->pending_id
= 0;
336 g_action_group_exporter_action_added (GActionGroup
*action_group
,
337 const gchar
*action_name
,
340 GActionGroupExporter
*exporter
= user_data
;
343 event_mask
= g_action_group_exporter_get_events (exporter
, action_name
);
345 /* The action is new, so we should not have any pending
346 * enabled-changed or state-changed signals for it.
348 g_assert (~event_mask
& (ACTION_STATE_CHANGED_EVENT
|
349 ACTION_ENABLED_CHANGED_EVENT
));
351 event_mask
|= ACTION_ADDED_EVENT
;
353 g_action_group_exporter_set_events (exporter
, action_name
, event_mask
);
357 g_action_group_exporter_action_removed (GActionGroup
*action_group
,
358 const gchar
*action_name
,
361 GActionGroupExporter
*exporter
= user_data
;
364 event_mask
= g_action_group_exporter_get_events (exporter
, action_name
);
366 /* If the add event for this is still queued then just cancel it since
369 * If the event was freshly added, there should not have been any
370 * enabled or state changed events.
372 if (event_mask
& ACTION_ADDED_EVENT
)
374 g_assert (~event_mask
& ~(ACTION_STATE_CHANGED_EVENT
| ACTION_ENABLED_CHANGED_EVENT
));
375 event_mask
&= ~ACTION_ADDED_EVENT
;
378 /* Otherwise, queue a remove event. Drop any state or enabled changes
379 * that were queued before the remove. */
382 event_mask
|= ACTION_REMOVED_EVENT
;
383 event_mask
&= ~(ACTION_STATE_CHANGED_EVENT
| ACTION_ENABLED_CHANGED_EVENT
);
386 g_action_group_exporter_set_events (exporter
, action_name
, event_mask
);
390 g_action_group_exporter_action_state_changed (GActionGroup
*action_group
,
391 const gchar
*action_name
,
395 GActionGroupExporter
*exporter
= user_data
;
398 event_mask
= g_action_group_exporter_get_events (exporter
, action_name
);
400 /* If it was removed, it must have been added back. Otherwise, why
401 * are we hearing about changes?
403 g_assert (~event_mask
& ACTION_REMOVED_EVENT
||
404 event_mask
& ACTION_ADDED_EVENT
);
406 /* If it is freshly added, don't also bother with the state change
407 * signal since the updated state will be sent as part of the pending
410 if (~event_mask
& ACTION_ADDED_EVENT
)
411 event_mask
|= ACTION_STATE_CHANGED_EVENT
;
413 g_action_group_exporter_set_events (exporter
, action_name
, event_mask
);
417 g_action_group_exporter_action_enabled_changed (GActionGroup
*action_group
,
418 const gchar
*action_name
,
422 GActionGroupExporter
*exporter
= user_data
;
425 event_mask
= g_action_group_exporter_get_events (exporter
, action_name
);
427 /* Reasoning as above. */
428 g_assert (~event_mask
& ACTION_REMOVED_EVENT
||
429 event_mask
& ACTION_ADDED_EVENT
);
431 if (~event_mask
& ACTION_ADDED_EVENT
)
432 event_mask
|= ACTION_ENABLED_CHANGED_EVENT
;
434 g_action_group_exporter_set_events (exporter
, action_name
, event_mask
);
438 g_action_group_exporter_pre_emit (GActionGroupExporter
*exporter
,
439 GVariant
*platform_data
)
441 if (G_IS_APPLICATION (exporter
->action_group
))
442 G_APPLICATION_GET_CLASS (exporter
->action_group
)
443 ->before_emit (G_APPLICATION (exporter
->action_group
), platform_data
);
447 g_action_group_exporter_post_emit (GActionGroupExporter
*exporter
,
448 GVariant
*platform_data
)
450 if (G_IS_APPLICATION (exporter
->action_group
))
451 G_APPLICATION_GET_CLASS (exporter
->action_group
)
452 ->after_emit (G_APPLICATION (exporter
->action_group
), platform_data
);
456 org_gtk_Actions_method_call (GDBusConnection
*connection
,
458 const gchar
*object_path
,
459 const gchar
*interface_name
,
460 const gchar
*method_name
,
461 GVariant
*parameters
,
462 GDBusMethodInvocation
*invocation
,
465 GActionGroupExporter
*exporter
= user_data
;
466 GVariant
*result
= NULL
;
468 if (g_str_equal (method_name
, "List"))
472 list
= g_action_group_list_actions (exporter
->action_group
);
473 result
= g_variant_new ("(^as)", list
);
477 else if (g_str_equal (method_name
, "Describe"))
482 g_variant_get (parameters
, "(&s)", &name
);
483 desc
= g_action_group_describe_action (exporter
->action_group
, name
);
484 result
= g_variant_new ("(@(bgav))", desc
);
487 else if (g_str_equal (method_name
, "DescribeAll"))
489 GVariantBuilder builder
;
493 list
= g_action_group_list_actions (exporter
->action_group
);
494 g_variant_builder_init (&builder
, G_VARIANT_TYPE ("a{s(bgav)}"));
495 for (i
= 0; list
[i
]; i
++)
497 const gchar
*name
= list
[i
];
498 GVariant
*description
;
500 description
= g_action_group_describe_action (exporter
->action_group
, name
);
501 g_variant_builder_add (&builder
, "{s@(bgav)}", name
, description
);
503 result
= g_variant_new ("(a{s(bgav)})", &builder
);
507 else if (g_str_equal (method_name
, "Activate"))
509 GVariant
*parameter
= NULL
;
510 GVariant
*platform_data
;
514 g_variant_get (parameters
, "(&sav@a{sv})", &name
, &iter
, &platform_data
);
515 g_variant_iter_next (iter
, "v", ¶meter
);
516 g_variant_iter_free (iter
);
518 g_action_group_exporter_pre_emit (exporter
, platform_data
);
519 g_action_group_activate_action (exporter
->action_group
, name
, parameter
);
520 g_action_group_exporter_post_emit (exporter
, platform_data
);
523 g_variant_unref (parameter
);
525 g_variant_unref (platform_data
);
528 else if (g_str_equal (method_name
, "SetState"))
530 GVariant
*platform_data
;
534 g_variant_get (parameters
, "(&sv@a{sv})", &name
, &state
, &platform_data
);
535 g_action_group_exporter_pre_emit (exporter
, platform_data
);
536 g_action_group_change_action_state (exporter
->action_group
, name
, state
);
537 g_action_group_exporter_post_emit (exporter
, platform_data
);
538 g_variant_unref (platform_data
);
539 g_variant_unref (state
);
543 g_assert_not_reached ();
545 g_dbus_method_invocation_return_value (invocation
, result
);
549 g_action_group_exporter_free (gpointer user_data
)
551 GActionGroupExporter
*exporter
= user_data
;
554 for (i
= 0; i
< G_N_ELEMENTS (exporter
->signal_ids
); i
++)
555 g_signal_handler_disconnect (exporter
->action_group
, exporter
->signal_ids
[i
]);
557 g_hash_table_unref (exporter
->pending_changes
);
558 if (exporter
->pending_id
)
559 g_source_remove (exporter
->pending_id
);
561 g_object_unref (exporter
->connection
);
562 g_object_unref (exporter
->action_group
);
563 g_free (exporter
->object_path
);
565 g_slice_free (GActionGroupExporter
, exporter
);
569 * g_dbus_connection_export_action_group:
570 * @connection: a #GDBusConnection
571 * @object_path: a D-Bus object path
572 * @action_group: a #GActionGroup
573 * @error: a pointer to a %NULL #GError, or %NULL
575 * Exports @action_group on @connection at @object_path.
577 * The implemented D-Bus API should be considered private. It is
578 * subject to change in the future.
580 * A given * object path can only have one action group exported on it.
581 * If this constraint is violated, the export will fail and 0 will be
582 * returned (with @error set accordingly).
584 * You can unexport the action group using
585 * g_dbus_connection_unexport_action_group() with the return value of
588 * Returns: the ID of the export (never zero), or 0 in case of failure
593 g_dbus_connection_export_action_group (GDBusConnection
*connection
,
594 const gchar
*object_path
,
595 GActionGroup
*action_group
,
598 const GDBusInterfaceVTable vtable
= {
599 org_gtk_Actions_method_call
601 GActionGroupExporter
*exporter
;
604 if G_UNLIKELY (org_gtk_Actions
== NULL
)
606 GError
*error
= NULL
;
609 info
= g_dbus_node_info_new_for_xml (org_gtk_Actions_xml
, &error
);
610 if G_UNLIKELY (info
== NULL
)
611 g_error ("%s", error
->message
);
612 org_gtk_Actions
= g_dbus_node_info_lookup_interface (info
, "org.gtk.Actions");
613 g_assert (org_gtk_Actions
!= NULL
);
614 g_dbus_interface_info_ref (org_gtk_Actions
);
615 g_dbus_node_info_unref (info
);
618 exporter
= g_slice_new (GActionGroupExporter
);
619 id
= g_dbus_connection_register_object (connection
, object_path
, org_gtk_Actions
, &vtable
,
620 exporter
, g_action_group_exporter_free
, error
);
624 g_slice_free (GActionGroupExporter
, exporter
);
628 exporter
->pending_changes
= g_hash_table_new_full (g_str_hash
, g_str_equal
, g_free
, NULL
);
629 exporter
->pending_id
= 0;
630 exporter
->action_group
= g_object_ref (action_group
);
631 exporter
->connection
= g_object_ref (connection
);
632 exporter
->object_path
= g_strdup (object_path
);
634 exporter
->signal_ids
[0] =
635 g_signal_connect (action_group
, "action-added",
636 G_CALLBACK (g_action_group_exporter_action_added
), exporter
);
637 exporter
->signal_ids
[1] =
638 g_signal_connect (action_group
, "action-removed",
639 G_CALLBACK (g_action_group_exporter_action_removed
), exporter
);
640 exporter
->signal_ids
[2] =
641 g_signal_connect (action_group
, "action-state-changed",
642 G_CALLBACK (g_action_group_exporter_action_state_changed
), exporter
);
643 exporter
->signal_ids
[3] =
644 g_signal_connect (action_group
, "action-enabled-changed",
645 G_CALLBACK (g_action_group_exporter_action_enabled_changed
), exporter
);
651 * g_dbus_connection_unexport_action_group:
652 * @connection: a #GDBusConnection
653 * @export_id: the ID from g_dbus_connection_export_action_group()
655 * Reverses the effect of a previous call to
656 * g_dbus_connection_export_action_group().
658 * It is an error to call this function with an ID that wasn't returned
659 * from g_dbus_connection_export_action_group() or to call it with the
660 * same ID more than once.
665 g_dbus_connection_unexport_action_group (GDBusConnection
*connection
,
668 g_dbus_connection_unregister_object (connection
, export_id
);