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 "accessible-register.h"
32 * This module is responsible for keeping track of all the AtkObjects in
33 * the application, so that they can be accessed remotely and placed in
34 * a client side cache.
36 * To access an AtkObject remotely we need to provide a D-Bus object
37 * path for it. The D-Bus object paths used have a standard prefix
38 * (SPI_ATK_OBJECT_PATH_PREFIX). Appended to this prefix is a string
39 * representation of an integer reference. So to access an AtkObject
40 * remotely we keep a Hashtable that maps the given reference to
41 * the AtkObject pointer. An object in this hash table is said to be 'registered'.
43 * The architecture of AT-SPI dbus is such that AtkObjects are not
44 * remotely reference counted. This means that we need to keep track of
45 * object destruction. When an object is destroyed it must be 'deregistered'
46 * To do this lookup we keep a dbus-id attribute on each AtkObject.
48 * In addition to accessing the objects remotely we must be able to update
49 * the client side cache. This is done using the 'update' signal of the
50 * org.freedesktop.atspi.Tree interface. The update signal should send out
51 * all of the cacheable data for an Accessible object.
58 * This code seems very brittle.
59 * I would prefer changes to be made to
60 * gail and the ATK interface so that all Accessible
61 * objects are registered with an exporting module.
63 * This is the same system as Qt has with the QAccessibleBridge
64 * and QAccessibleBridgePlugin. It entails some rather
65 * large structural changes to ATK though:
67 * Removing infinite spaces (Child access no longer references child).
68 * Removing lazy creation of accessible objects.
71 #define SPI_ATK_OBJECT_PATH_PREFIX "/org/freedesktop/atspi/accessible"
72 #define SPI_ATK_OBJECT_PATH_DESKTOP "/root"
74 #define SPI_ATK_PATH_PREFIX_LENGTH 33
75 #define SPI_ATK_OBJECT_REFERENCE_TEMPLATE SPI_ATK_OBJECT_PATH_PREFIX "/%d"
78 static GHashTable *ref2ptr = NULL; /* Used for converting a D-Bus path (Reference) to the object pointer */
80 static guint reference_counter = 0;
82 static GStaticRecMutex registration_mutex = G_STATIC_REC_MUTEX_INIT;
84 /*---------------------------------------------------------------------------*/
86 static GStaticMutex recursion_check_guard = G_STATIC_MUTEX_INIT;
87 static gboolean recursion_check = FALSE;
90 recursion_check_and_set ()
93 g_static_mutex_lock (&recursion_check_guard);
94 ret = recursion_check;
95 recursion_check = TRUE;
96 g_static_mutex_unlock (&recursion_check_guard);
101 recursion_check_unset ()
103 g_static_mutex_lock (&recursion_check_guard);
104 recursion_check = FALSE;
105 g_static_mutex_unlock (&recursion_check_guard);
108 /*---------------------------------------------------------------------------*/
111 * Each AtkObject must be asssigned a D-Bus path (Reference)
113 * This function provides an integer reference for a new
117 assign_reference(void)
120 /* Reference of 0 not allowed as used as direct key in hash table */
121 if (reference_counter == 0)
123 return reference_counter;
127 * Returns the reference of the object, or 0 if it is not registered.
130 object_to_ref (AtkObject *accessible)
132 return GPOINTER_TO_INT(g_object_get_data (G_OBJECT (accessible), "dbus-id"));
136 * Converts the Accessible object reference to its D-Bus object path
139 atk_dbus_ref_to_path (guint ref)
141 return g_strdup_printf(SPI_ATK_OBJECT_REFERENCE_TEMPLATE, ref);
144 /*---------------------------------------------------------------------------*/
147 * Callback for when a registered AtkObject is destroyed.
149 * Removes the AtkObject from the reference lookup tables, meaning
150 * it is no longer exposed over D-Bus.
153 deregister_accessible (gpointer data, GObject *accessible)
156 g_return_if_fail (ATK_IS_OBJECT (accessible));
158 ref = object_to_ref (ATK_OBJECT(accessible));
161 g_hash_table_remove(ref2ptr, GINT_TO_POINTER(ref));
166 * Called to register an AtkObject with AT-SPI and expose it over D-Bus.
169 register_accessible (AtkObject *accessible)
172 g_return_if_fail (ATK_IS_OBJECT(accessible));
174 ref = assign_reference();
176 g_hash_table_insert (ref2ptr, GINT_TO_POINTER(ref), accessible);
177 g_object_set_data (G_OBJECT(accessible), "dbus-id", GINT_TO_POINTER(ref));
178 g_object_weak_ref(G_OBJECT(accessible), deregister_accessible, NULL);
181 /*---------------------------------------------------------------------------*/
185 * This function checks that the ref-count of an accessible
188 * There is not currently any remote reference counting
189 * in AT-SPI D-Bus so objects that are remotely owned are not
192 * TODO Add debug wrapper
195 non_owned_accessible (AtkObject *accessible)
197 if ((G_OBJECT (accessible))->ref_count <= 1)
199 g_warning ("AT-SPI: Child referenced that is not owned by its parent");
207 #endif /* SPI_ATK_DEBUG */
209 /*---------------------------------------------------------------------------*/
212 has_manages_descendants (AtkObject *accessible)
215 gboolean result = FALSE;
217 /* This is dangerous, refing the state set
218 * seems to do wierd things to the tree & cause recursion
219 * by modifying the tree alot.
221 state = atk_object_ref_state_set (accessible);
222 if (atk_state_set_contains_state (state, ATK_STATE_MANAGES_DESCENDANTS))
225 g_warning ("AT-SPI: Object with 'Manages descendants' states not currently handled by AT-SPI");
229 g_object_unref (state);
235 append_children (AtkObject *accessible, GQueue *traversal)
239 gint count = atk_object_get_n_accessible_children (accessible);
241 if (count < 0) count = 0;
242 for (i =0; i < count; i++)
244 current = atk_object_ref_accessible_child (accessible, i);
248 non_owned_accessible (current);
250 if (!has_manages_descendants (current))
251 g_queue_push_tail (traversal, current);
253 g_object_unref (G_OBJECT (current));
259 * Registers a subtree of accessible objects
260 * rooted at the accessible object provided.
262 * The leaf nodes do not have their children
263 * registered. A node is considered a leaf
264 * if it has the state "manages-descendants"
265 * or if it has already been registered.
268 register_subtree (AtkObject *accessible)
274 g_return_if_fail (ATK_IS_OBJECT (accessible));
276 traversal = g_queue_new ();
277 emit_update = g_queue_new ();
279 g_object_ref (accessible);
280 g_queue_push_tail (traversal, accessible);
282 while (!g_queue_is_empty (traversal))
284 current = g_queue_pop_head (traversal);
285 g_queue_push_tail (emit_update, current);
286 if (!object_to_ref (current))
288 register_accessible (current);
290 g_debug ("REG - %s - %d - %s", atk_object_get_name (current),
291 atk_object_get_role (current),
292 atk_dbus_object_to_path (current));
294 append_children (current, traversal);
298 while (!g_queue_is_empty (emit_update))
300 current = g_queue_pop_head (emit_update);
301 spi_emit_cache_update (current, atk_adaptor_app_data->bus);
302 g_object_unref (G_OBJECT (current));
305 g_queue_free (traversal);
306 g_queue_free (emit_update);
309 /*---------------------------------------------------------------------------*/
312 * Called when an already registered object is updated in such a
313 * way that client side cache needs to be updated.
316 update_accessible (AtkObject *accessible)
319 g_return_if_fail (ATK_IS_OBJECT(accessible));
321 ref = object_to_ref (accessible);
324 spi_emit_cache_update (accessible, atk_adaptor_app_data->bus);
328 /*---------------------------------------------------------------------------*/
331 atk_dbus_foreach_registered(GHFunc func, gpointer data)
333 g_hash_table_foreach(ref2ptr, func, data);
337 * Used to lookup an AtkObject from its D-Bus path.
340 atk_dbus_path_to_object (const char *path)
345 g_return_val_if_fail (path, NULL);
347 if (strncmp(path, SPI_ATK_OBJECT_PATH_PREFIX, SPI_ATK_PATH_PREFIX_LENGTH) != 0)
350 path += SPI_ATK_PATH_PREFIX_LENGTH; /* Skip over the prefix */
352 if (!g_strcmp0 (SPI_ATK_OBJECT_PATH_DESKTOP, path))
353 return atk_get_root();
359 data = g_hash_table_lookup (ref2ptr, GINT_TO_POINTER(index));
361 return ATK_OBJECT (data);
367 * TODO WARNING HACK This function is dangerous.
368 * It should only be called before sending an event on an
369 * object that has not already been registered.
372 atk_dbus_object_attempt_registration (AtkObject *accessible)
376 ref = object_to_ref (accessible);
379 /* See if the object is attached to the main tree */
380 AtkObject *current, *prev = NULL;
383 /* This should iterate until it hits a NULL or registered parent */
385 current = atk_object_get_parent (accessible);
387 cref = object_to_ref (current);
388 while (current && !cref)
391 current = atk_object_get_parent (current);
393 cref = object_to_ref (current);
396 /* A registered parent, with non-registered child, has been found */
399 register_subtree (prev);
402 /* The object SHOULD be registered now. If it isn't - I give up */
403 ref = object_to_ref (accessible);
406 return atk_dbus_ref_to_path (ref);
411 g_debug ("AT-SPI: Could not register a non-attached accessible object");
418 return atk_dbus_ref_to_path (ref);
424 * Used to lookup a D-Bus path from the AtkObject.
427 atk_dbus_object_to_path (AtkObject *accessible)
431 ref = object_to_ref (accessible);
435 return atk_dbus_ref_to_path (ref);
439 atk_dbus_desktop_object_path ()
441 return g_strdup (SPI_ATK_OBJECT_PATH_PREFIX SPI_ATK_OBJECT_PATH_DESKTOP);
444 /*---------------------------------------------------------------------------*/
446 typedef gboolean (*TreeUpdateAction) (GSignalInvocationHint *signal_hint,
447 guint n_param_values,
448 const GValue *param_values,
450 AtkObject *accessible);
453 * Events are not evaluated for non-registered accessibles.
455 * When a property change is made on a registered accessible
456 * the client side cache should be updated.
458 * When a parent is changed the subtree is de-registered
459 * if the parent is not attached to the root accessible.
461 /* TODO Turn this function into a macro? */
463 tree_update_wrapper (GSignalInvocationHint *signal_hint,
464 guint n_param_values,
465 const GValue *param_values,
467 TreeUpdateAction action)
469 AtkObject *accessible;
471 g_static_rec_mutex_lock (®istration_mutex);
473 /* Ensure that only registered accessibles
474 * have their signals processed.
476 accessible = ATK_OBJECT(g_value_get_object (¶m_values[0]));
477 g_return_val_if_fail (ATK_IS_OBJECT (accessible), TRUE);
479 if (object_to_ref (accessible))
482 if (recursion_check_and_set ())
483 g_warning ("AT-SPI: Recursive use of registration module");
485 g_debug ("AT-SPI: Tree update listener");
487 action (signal_hint, n_param_values, param_values, data, accessible);
489 recursion_check_unset ();
492 g_static_rec_mutex_unlock (®istration_mutex);
498 tree_update_state_action (GSignalInvocationHint *signal_hint,
499 guint n_param_values,
500 const GValue *param_values,
502 AtkObject *accessible)
504 update_accessible (accessible);
509 tree_update_state_listener (GSignalInvocationHint *signal_hint,
510 guint n_param_values,
511 const GValue *param_values,
514 tree_update_wrapper (signal_hint, n_param_values, param_values, data, tree_update_state_action);
519 tree_update_property_action (GSignalInvocationHint *signal_hint,
520 guint n_param_values,
521 const GValue *param_values,
523 AtkObject *accessible)
525 AtkPropertyValues *values;
526 const gchar *pname = NULL;
528 values = (AtkPropertyValues*) g_value_get_pointer (¶m_values[1]);
529 pname = values[0].property_name;
530 if (strcmp (pname, "accessible-name") == 0 ||
531 strcmp (pname, "accessible-description") == 0 ||
532 strcmp (pname, "accessible-parent") == 0)
534 update_accessible (accessible);
536 /* Parent value us updated by child-add signal of parent object */
541 tree_update_property_listener (GSignalInvocationHint *signal_hint,
542 guint n_param_values,
543 const GValue *param_values,
546 tree_update_wrapper (signal_hint, n_param_values, param_values, data, tree_update_property_action);
551 tree_update_children_action (GSignalInvocationHint *signal_hint,
552 guint n_param_values,
553 const GValue *param_values,
555 AtkObject *accessible)
557 const gchar *detail = NULL;
560 if (has_manages_descendants (accessible)) return TRUE;
561 if (signal_hint->detail)
562 detail = g_quark_to_string (signal_hint->detail);
564 if (!strcmp (detail, "add"))
567 int index = g_value_get_uint (param_values + 1);
568 child = g_value_get_pointer (param_values + 2);
570 if (!ATK_IS_OBJECT (child))
572 child = atk_object_ref_accessible_child (accessible, index);
574 non_owned_accessible (child);
577 register_subtree (child);
578 update_accessible (accessible);
584 tree_update_children_listener (GSignalInvocationHint *signal_hint,
585 guint n_param_values,
586 const GValue *param_values,
589 tree_update_wrapper (signal_hint, n_param_values, param_values, data, tree_update_children_action);
593 /*---------------------------------------------------------------------------*/
596 spi_atk_register_toplevel_added (AtkObject *accessible,
600 g_static_rec_mutex_lock (®istration_mutex);
602 g_return_if_fail (ATK_IS_OBJECT (accessible));
604 if (object_to_ref (accessible))
607 if (recursion_check_and_set ())
608 g_warning ("AT-SPI: Recursive use of registration module");
610 g_debug ("AT-SPI: Toplevel added listener");
612 if (!ATK_IS_OBJECT (child))
614 child = atk_object_ref_accessible_child (accessible, index);
616 non_owned_accessible (child);
619 register_subtree (child);
620 update_accessible (accessible);
622 recursion_check_unset ();
625 g_static_rec_mutex_unlock (®istration_mutex);
629 spi_atk_register_toplevel_removed (AtkObject *accessible,
633 g_static_rec_mutex_lock (®istration_mutex);
635 g_return_if_fail (ATK_IS_OBJECT (accessible));
637 if (object_to_ref (accessible))
640 if (recursion_check_and_set ())
641 g_warning ("AT-SPI: Recursive use of registration module");
643 g_debug ("AT-SPI: Toplevel removed listener");
645 update_accessible (accessible);
646 recursion_check_unset ();
649 g_static_rec_mutex_unlock (®istration_mutex);
653 * Initializes required global data. The update and removal lists
654 * and the reference lookup tables.
656 * Initializes all of the required D-Bus interfaces.
659 atk_dbus_initialize (AtkObject *root)
662 ref2ptr = g_hash_table_new(g_direct_hash, g_direct_equal);
665 if (g_thread_supported ())
666 g_message ("AT-SPI: Threads enabled");
668 g_debug ("AT-SPI: Initial Atk tree regisration");
671 register_subtree (root);
673 atk_add_global_event_listener (tree_update_property_listener, "Gtk:AtkObject:property-change");
674 atk_add_global_event_listener (tree_update_children_listener, "Gtk:AtkObject:children-changed");
675 atk_add_global_event_listener (tree_update_state_listener, "Gtk:AtkObject:state-change");
677 g_signal_connect (root,
678 "children-changed::add",
679 (GCallback) spi_atk_register_toplevel_added,
681 g_signal_connect (root,
682 "children-changed::remove",
683 (GCallback) spi_atk_register_toplevel_removed,
687 /*END------------------------------------------------------------------------*/