2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2008 Novell, Inc.
6 * Copyright 2008, 2009 Codethink Ltd.
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 * Boston, MA 02111-1307, USA.
29 #include "tree-adaptor.h"
30 #include "accessible-register.h"
33 * This module is responsible for keeping track of all the AtkObjects in
34 * the application, so that they can be accessed remotely and placed in
35 * a client side cache.
37 * To access an AtkObject remotely we need to provide a D-Bus object
38 * path for it. The D-Bus object paths used have a standard prefix
39 * (SPI_ATK_OBJECT_PATH_PREFIX). Appended to this prefix is a string
40 * representation of an integer reference. So to access an AtkObject
41 * remotely we keep a Hashtable that maps the given reference to
42 * the AtkObject pointer. An object in this hash table is said to be 'registered'.
44 * The architecture of AT-SPI dbus is such that AtkObjects are not
45 * remotely reference counted. This means that we need to keep track of
46 * object destruction. When an object is destroyed it must be 'deregistered'
47 * To do this lookup we keep a dbus-id attribute on each AtkObject.
49 * In addition to accessing the objects remotely we must be able to update
50 * the client side cache. This is done using the 'update' signal of the
51 * org.freedesktop.atspi.Tree interface. The update signal should send out
52 * all of the cacheable data for an Accessible object.
59 * This code seems very brittle.
60 * I would prefer changes to be made to
61 * gail and the ATK interface so that all Accessible
62 * objects are registered with an exporting module.
64 * This is the same system as Qt has with the QAccessibleBridge
65 * and QAccessibleBridgePlugin. It entails some rather
66 * large structural changes to ATK though:
68 * Removing infinite spaces (Child access no longer references child).
69 * Removing lazy creation of accessible objects.
72 #define SPI_ATK_OBJECT_PATH_PREFIX "/org/freedesktop/atspi/accessible"
73 #define SPI_ATK_OBJECT_PATH_DESKTOP "/root"
75 #define SPI_ATK_PATH_PREFIX_LENGTH 33
76 #define SPI_ATK_OBJECT_REFERENCE_TEMPLATE SPI_ATK_OBJECT_PATH_PREFIX "/%d"
79 static GHashTable *ref2ptr = NULL; /* Used for converting a D-Bus path (Reference) to the object pointer */
81 static guint reference_counter = 0;
83 static GStaticRecMutex registration_mutex = G_STATIC_REC_MUTEX_INIT;
85 /*---------------------------------------------------------------------------*/
87 static GStaticMutex recursion_check_guard = G_STATIC_MUTEX_INIT;
88 static gboolean recursion_check = FALSE;
91 recursion_check_and_set ()
94 g_static_mutex_lock (&recursion_check_guard);
95 ret = recursion_check;
96 recursion_check = TRUE;
97 g_static_mutex_unlock (&recursion_check_guard);
102 recursion_check_unset ()
104 g_static_mutex_lock (&recursion_check_guard);
105 recursion_check = FALSE;
106 g_static_mutex_unlock (&recursion_check_guard);
109 /*---------------------------------------------------------------------------*/
112 * Each AtkObject must be asssigned a D-Bus path (Reference)
114 * This function provides an integer reference for a new
118 assign_reference(void)
121 /* Reference of 0 not allowed as used as direct key in hash table */
122 if (reference_counter == 0)
124 return reference_counter;
128 * Returns the reference of the object, or 0 if it is not registered.
131 gobject_to_ref (GObject *gobj)
133 return GPOINTER_TO_INT(g_object_get_data (gobj, "dbus-id"));
137 object_to_ref (AtkObject *accessible)
139 return gobject_to_ref (G_OBJECT (accessible));
143 hyperlink_to_ref (AtkHyperlink *accessible)
145 return GPOINTER_TO_INT(g_object_get_data (G_OBJECT (accessible), "dbus-id"));
149 * Converts the Accessible object reference to its D-Bus object path
152 atk_dbus_ref_to_path (guint ref)
154 return g_strdup_printf(SPI_ATK_OBJECT_REFERENCE_TEMPLATE, ref);
157 /*---------------------------------------------------------------------------*/
160 deregister_sub_accessible (gpointer key, gpointer obj_data, gpointer iter);
163 deregister_sub_hyperlink (gpointer key, gpointer obj_data, gpointer iter);
166 * Callback for when a registered AtkObject is destroyed.
168 * Removes the AtkObject from the reference lookup tables, meaning
169 * it is no longer exposed over D-Bus.
172 deregister_object (gpointer data, GObject *gobj)
175 GHashTable *subrefs_atk;
176 GHashTable *subrefs_hyperlink;
177 g_return_if_fail (ATK_IS_OBJECT (gobj) || ATK_IS_HYPERLINK (gobj));
179 subrefs_atk = (GHashTable *) g_object_get_data (gobj, "dbus-subrefs-atk");
181 g_hash_table_foreach (subrefs_atk, deregister_sub_accessible, data);
183 subrefs_hyperlink = (GHashTable *) g_object_get_data (gobj, "dbus-subrefs-hyperlink");
184 if (subrefs_hyperlink)
185 g_hash_table_foreach (subrefs_hyperlink, deregister_sub_hyperlink, data);
187 if (ATK_IS_OBJECT (gobj))
189 ref = object_to_ref (ATK_OBJECT (gobj));
192 spi_emit_cache_removal (ref, atk_adaptor_app_data->bus);
193 g_hash_table_remove(ref2ptr, GINT_TO_POINTER(ref));
199 deregister_sub_accessible (gpointer key, gpointer obj_data, gpointer iter)
201 GObject *obj = G_OBJECT (obj_data);
202 deregister_object (NULL, obj);
203 g_object_unref (obj);
207 deregister_sub_hyperlink (gpointer key, gpointer obj_data, gpointer iter)
210 GObject *ghyperlink = G_OBJECT (obj_data);
212 g_return_if_fail (ATK_IS_HYPERLINK (ghyperlink));
214 ref = gobject_to_ref (ghyperlink);
217 g_hash_table_remove(ref2ptr, GINT_TO_POINTER(ref));
219 g_object_unref (ghyperlink);
223 register_gobject (GObject *gobj, GObject *container)
226 g_return_if_fail (G_IS_OBJECT(gobj));
228 ref = assign_reference();
230 g_hash_table_insert (ref2ptr, GINT_TO_POINTER(ref), gobj);
231 g_object_set_data (G_OBJECT(gobj), "dbus-id", GINT_TO_POINTER(ref));
232 g_object_weak_ref(G_OBJECT(gobj), deregister_object, NULL);
236 GHashTable *subrefs = (GHashTable *) g_object_get_data (G_OBJECT (container), "dbus-subrefs-atk");
239 subrefs = g_hash_table_new(g_direct_hash, g_direct_equal);
240 g_object_set_data (G_OBJECT (container), "dbus-subrefs-atk", subrefs);
242 g_hash_table_insert (subrefs, GINT_TO_POINTER(ref), gobj);
245 if (ATK_IS_HYPERLINK (gobj))
247 else if (ATK_IS_OBJECT (gobj))
249 AtkObject *accessible = ATK_OBJECT (gobj);
250 AtkStateSet *state = atk_object_ref_state_set (accessible);
251 if (atk_state_set_contains_state (state, ATK_STATE_TRANSIENT) &&
252 atk_state_set_contains_state (state, ATK_STATE_SHOWING))
256 g_object_unref (state);
261 * Called to register an AtkObject with AT-SPI and expose it over D-Bus.
264 register_accessible (AtkObject *accessible, AtkObject *container)
266 g_return_if_fail (ATK_IS_OBJECT(accessible));
268 register_gobject (G_OBJECT (accessible), G_OBJECT (container));
272 register_hyperlink (AtkHyperlink *hyperlink, AtkObject *container)
275 g_return_if_fail (ATK_IS_HYPERLINK (hyperlink));
276 g_return_if_fail (container);
278 ref = assign_reference();
280 g_hash_table_insert (ref2ptr, GINT_TO_POINTER(ref), hyperlink);
281 g_object_set_data (G_OBJECT(hyperlink), "dbus-id", GINT_TO_POINTER(ref));
282 g_object_ref (G_OBJECT (hyperlink));
284 GHashTable *subrefs = (GHashTable *) g_object_get_data (G_OBJECT (container), "dbus-subrefs-hyperlink");
287 subrefs = g_hash_table_new(g_direct_hash, g_direct_equal);
288 g_object_set_data (G_OBJECT (container), "dbus-subrefs-hyperlink", GINT_TO_POINTER(ref));
290 g_hash_table_insert (subrefs, GINT_TO_POINTER(ref), hyperlink);
293 /*---------------------------------------------------------------------------*/
297 * This function checks that the ref-count of an accessible
300 * There is not currently any remote reference counting
301 * in AT-SPI D-Bus so objects that are remotely owned are not
304 * TODO Add debug wrapper
307 non_owned_accessible (AtkObject *accessible)
309 if ((G_OBJECT (accessible))->ref_count <= 1)
311 g_warning ("AT-SPI: Child referenced that is not owned by its parent");
319 #endif /* SPI_ATK_DEBUG */
321 /*---------------------------------------------------------------------------*/
323 /* TRUE if we should not keep this object / tell the AT about it
324 * Currently true if TRANSIENT and not SHOWING
327 object_is_moot (AtkObject *accessible)
330 gboolean result = FALSE;
332 /* This is dangerous, refing the state set
333 * seems to do wierd things to the tree & cause recursion
334 * by modifying the tree alot.
336 state = atk_object_ref_state_set (accessible);
337 if ( atk_state_set_contains_state (state, ATK_STATE_TRANSIENT) &&
338 !atk_state_set_contains_state (state, ATK_STATE_SHOWING))
342 g_object_unref (state);
348 append_children (AtkObject *accessible, GQueue *traversal)
352 gint count = atk_object_get_n_accessible_children (accessible);
354 if (count < 0) count = 0;
355 for (i =0; i < count; i++)
357 current = atk_object_ref_accessible_child (accessible, i);
361 non_owned_accessible (current);
363 if (!object_is_moot (current))
364 g_queue_push_tail (traversal, current);
366 g_object_unref (G_OBJECT (current));
372 * Registers a subtree of accessible objects
373 * rooted at the accessible object provided.
375 * The leaf nodes do not have their children
376 * registered. A node is considered a leaf
377 * if it has the state "manages-descendants"
378 * or if it has already been registered.
381 register_subtree (AtkObject *accessible)
387 g_return_if_fail (ATK_IS_OBJECT (accessible));
389 traversal = g_queue_new ();
390 emit_update = g_queue_new ();
392 g_object_ref (accessible);
393 g_queue_push_tail (traversal, accessible);
395 while (!g_queue_is_empty (traversal))
397 current = g_queue_pop_head (traversal);
398 g_queue_push_tail (emit_update, current);
399 if (!object_to_ref (current))
401 register_accessible (current, NULL);
403 g_debug ("REG - %s - %d - %s", atk_object_get_name (current),
404 atk_object_get_role (current),
405 atk_dbus_object_to_path (current));
407 append_children (current, traversal);
411 while (!g_queue_is_empty (emit_update))
413 current = g_queue_pop_head (emit_update);
414 spi_emit_cache_update (current, atk_adaptor_app_data->bus);
415 g_object_unref (G_OBJECT (current));
418 g_queue_free (traversal);
419 g_queue_free (emit_update);
422 /*---------------------------------------------------------------------------*/
425 * Called when an already registered object is updated in such a
426 * way that client side cache needs to be updated.
429 update_accessible (AtkObject *accessible)
432 g_return_if_fail (ATK_IS_OBJECT(accessible));
434 ref = object_to_ref (accessible);
437 spi_emit_cache_update (accessible, atk_adaptor_app_data->bus);
441 /*---------------------------------------------------------------------------*/
444 atk_dbus_foreach_registered(GHFunc func, gpointer data)
446 g_hash_table_foreach(ref2ptr, func, data);
450 * Used to lookup an AtkObject from its D-Bus path.
453 atk_dbus_path_to_gobject (const char *path)
458 g_return_val_if_fail (path, NULL);
460 if (strncmp(path, SPI_ATK_OBJECT_PATH_PREFIX, SPI_ATK_PATH_PREFIX_LENGTH) != 0)
463 path += SPI_ATK_PATH_PREFIX_LENGTH; /* Skip over the prefix */
465 if (!g_strcmp0 (SPI_ATK_OBJECT_PATH_DESKTOP, path))
466 return G_OBJECT (atk_get_root());
472 data = g_hash_table_lookup (ref2ptr, GINT_TO_POINTER(index));
474 return G_OBJECT (data);
480 atk_dbus_path_to_object (const char *path)
482 return ATK_OBJECT (atk_dbus_path_to_gobject (path));
486 * TODO WARNING HACK This function is dangerous.
487 * It should only be called before sending an event on an
488 * object that has not already been registered.
491 atk_dbus_object_attempt_registration (AtkObject *accessible)
495 ref = object_to_ref (accessible);
498 /* See if the object is attached to the main tree */
499 AtkObject *current, *prev = NULL;
502 /* This should iterate until it hits a NULL or registered parent */
504 current = atk_object_get_parent (accessible);
506 cref = object_to_ref (current);
507 while (current && !cref)
510 current = atk_object_get_parent (current);
512 cref = object_to_ref (current);
515 /* A registered parent, with non-registered child, has been found */
518 register_subtree (prev);
521 /* The object SHOULD be registered now. If it isn't - I give up */
522 ref = object_to_ref (accessible);
525 return atk_dbus_ref_to_path (ref);
530 g_debug ("AT-SPI: Could not register a non-attached accessible object");
537 return atk_dbus_ref_to_path (ref);
543 * Used to lookup a D-Bus path from the AtkObject.
546 atk_dbus_gobject_to_path_internal (GObject *gobj, gboolean do_register, GObject *container)
550 ref = gobject_to_ref (gobj);
551 if (!ref && do_register)
553 register_gobject (gobj, container);
554 ref = gobject_to_ref (gobj);
560 return atk_dbus_ref_to_path (ref);
564 atk_dbus_object_to_path (AtkObject *accessible, gboolean do_register)
566 AtkObject *container = (accessible && do_register? atk_object_get_parent (accessible): NULL);
567 return atk_dbus_gobject_to_path_internal (G_OBJECT (accessible), do_register, G_OBJECT (container));
571 atk_dbus_sub_object_to_path (GObject *gobj, GObject *container)
573 return atk_dbus_gobject_to_path_internal (gobj, TRUE, container);
577 atk_dbus_hyperlink_to_path (AtkHyperlink *hyperlink, AtkObject *container)
581 ref = gobject_to_ref (G_OBJECT (hyperlink));
582 if (!ref && container)
584 register_hyperlink (hyperlink, container);
585 ref = hyperlink_to_ref (hyperlink);
591 return atk_dbus_ref_to_path (ref);
595 atk_dbus_desktop_object_path ()
597 return g_strdup (SPI_ATK_OBJECT_PATH_PREFIX SPI_ATK_OBJECT_PATH_DESKTOP);
600 /*---------------------------------------------------------------------------*/
602 typedef gboolean (*TreeUpdateAction) (GSignalInvocationHint *signal_hint,
603 guint n_param_values,
604 const GValue *param_values,
606 AtkObject *accessible);
609 * Events are not evaluated for non-registered accessibles.
611 * When a property change is made on a registered accessible
612 * the client side cache should be updated.
614 * When a parent is changed the subtree is de-registered
615 * if the parent is not attached to the root accessible.
617 /* TODO Turn this function into a macro? */
619 tree_update_wrapper (GSignalInvocationHint *signal_hint,
620 guint n_param_values,
621 const GValue *param_values,
623 TreeUpdateAction action)
625 AtkObject *accessible;
627 g_static_rec_mutex_lock (®istration_mutex);
629 /* Ensure that only registered accessibles
630 * have their signals processed.
632 accessible = ATK_OBJECT(g_value_get_object (¶m_values[0]));
633 g_return_val_if_fail (ATK_IS_OBJECT (accessible), TRUE);
635 if (object_to_ref (accessible))
638 if (recursion_check_and_set ())
639 g_warning ("AT-SPI: Recursive use of registration module");
641 g_debug ("AT-SPI: Tree update listener");
643 action (signal_hint, n_param_values, param_values, data, accessible);
645 recursion_check_unset ();
648 g_static_rec_mutex_unlock (®istration_mutex);
654 tree_update_state_action (GSignalInvocationHint *signal_hint,
655 guint n_param_values,
656 const GValue *param_values,
658 AtkObject *accessible)
663 if (n_param_values < 3)
665 g_warning ("at-spi: Not enough params in state-changed signal");
669 name = g_value_get_string (param_values + 1);
670 state = g_value_get_boolean (param_values + 2);
671 if (!strcmp (name, "visible") && state == 0)
673 if (object_is_moot (accessible))
675 int ref_count = G_OBJECT(accessible)->ref_count;
676 g_object_unref (accessible);
677 /* If the ref count was >1, then someone else is still holding a ref,
678 but our ref is gone, so remove from the cache */
680 deregister_object (NULL, G_OBJECT (accessible));
685 update_accessible (accessible);
690 tree_update_state_listener (GSignalInvocationHint *signal_hint,
691 guint n_param_values,
692 const GValue *param_values,
695 tree_update_wrapper (signal_hint, n_param_values, param_values, data, tree_update_state_action);
700 tree_update_property_action (GSignalInvocationHint *signal_hint,
701 guint n_param_values,
702 const GValue *param_values,
704 AtkObject *accessible)
706 AtkPropertyValues *values;
707 const gchar *pname = NULL;
709 values = (AtkPropertyValues*) g_value_get_pointer (¶m_values[1]);
710 pname = values[0].property_name;
711 if (strcmp (pname, "accessible-name") == 0 ||
712 strcmp (pname, "accessible-description") == 0 ||
713 strcmp (pname, "accessible-parent") == 0)
715 update_accessible (accessible);
717 /* Parent value us updated by child-add signal of parent object */
722 tree_update_property_listener (GSignalInvocationHint *signal_hint,
723 guint n_param_values,
724 const GValue *param_values,
727 tree_update_wrapper (signal_hint, n_param_values, param_values, data, tree_update_property_action);
732 tree_update_children_action (GSignalInvocationHint *signal_hint,
733 guint n_param_values,
734 const GValue *param_values,
736 AtkObject *accessible)
738 const gchar *detail = NULL;
741 if (signal_hint->detail)
742 detail = g_quark_to_string (signal_hint->detail);
744 if (!strcmp (detail, "add"))
747 int index = g_value_get_uint (param_values + 1);
748 child = g_value_get_pointer (param_values + 2);
750 if (!ATK_IS_OBJECT (child))
752 child = atk_object_ref_accessible_child (accessible, index);
754 non_owned_accessible (child);
757 register_subtree (child);
758 update_accessible (accessible);
764 tree_update_children_listener (GSignalInvocationHint *signal_hint,
765 guint n_param_values,
766 const GValue *param_values,
769 tree_update_wrapper (signal_hint, n_param_values, param_values, data, tree_update_children_action);
773 /*---------------------------------------------------------------------------*/
776 spi_atk_register_toplevel_added (AtkObject *accessible,
780 g_static_rec_mutex_lock (®istration_mutex);
782 g_return_if_fail (ATK_IS_OBJECT (accessible));
784 if (object_to_ref (accessible))
787 if (recursion_check_and_set ())
788 g_warning ("AT-SPI: Recursive use of registration module");
790 g_debug ("AT-SPI: Toplevel added listener");
792 if (!ATK_IS_OBJECT (child))
794 child = atk_object_ref_accessible_child (accessible, index);
796 non_owned_accessible (child);
799 register_subtree (child);
800 update_accessible (accessible);
802 recursion_check_unset ();
805 g_static_rec_mutex_unlock (®istration_mutex);
809 spi_atk_register_toplevel_removed (AtkObject *accessible,
813 g_static_rec_mutex_lock (®istration_mutex);
815 g_return_if_fail (ATK_IS_OBJECT (accessible));
817 if (object_to_ref (accessible))
820 if (recursion_check_and_set ())
821 g_warning ("AT-SPI: Recursive use of registration module");
823 g_debug ("AT-SPI: Toplevel removed listener");
825 update_accessible (accessible);
826 recursion_check_unset ();
829 g_static_rec_mutex_unlock (®istration_mutex);
833 * Initializes required global data. The update and removal lists
834 * and the reference lookup tables.
836 * Initializes all of the required D-Bus interfaces.
839 atk_dbus_initialize (AtkObject *root)
842 ref2ptr = g_hash_table_new(g_direct_hash, g_direct_equal);
845 if (g_thread_supported ())
846 g_message ("AT-SPI: Threads enabled");
848 g_debug ("AT-SPI: Initial Atk tree regisration");
851 register_subtree (root);
853 atk_add_global_event_listener (tree_update_property_listener, "Gtk:AtkObject:property-change");
854 atk_add_global_event_listener (tree_update_children_listener, "Gtk:AtkObject:children-changed");
855 atk_add_global_event_listener (tree_update_state_listener, "Gtk:AtkObject:state-change");
857 g_signal_connect (root,
858 "children-changed::add",
859 (GCallback) spi_atk_register_toplevel_added,
861 g_signal_connect (root,
862 "children-changed::remove",
863 (GCallback) spi_atk_register_toplevel_removed,
867 /*END------------------------------------------------------------------------*/