2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2008 Novell, Inc.
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
27 #include "accessible.h"
30 * Need to add concurrency support.
33 #define ATK_BRIDGE_OBJECT_PATH_PREFIX "/org/freedesktop/atspi/accessible"
34 #define ATK_BRIDGE_OBJECT_REFERENCE_TEMPLATE ATK_BRIDGE_OBJECT_PATH_PREFIX "/%d"
35 #define ATK_BRIDGE_PATH_PREFIX_LENGTH 33
38 * This module is responsible for keeping track of all the AtkObjects in
39 * the application, so that they can be accessed remotely and placed in
40 * a client side cache.
42 * To access an AtkObject remotely we need to provide a D-Bus object
43 * path for it. The D-Bus object paths used have a standard prefix
44 * (ATK_BRIDGE_OBJECT_PATH_PREFIX). Appended to this prefix is a string
45 * representation of an integer reference. So to access an AtkObject
46 * remotely we keep a Hashtable that maps the given reference to
47 * the AtkObject pointer. An object in this hash table is said to be 'registered'.
49 * The architecture of AT-SPI dbus is such that AtkObjects are not
50 * remotely reference counted. This means that we need to keep track of
51 * object destruction. When an object is destroyed it must be 'deregistered'
52 * To do this lookup we keep a dbus-id attribute on each AtkObject.
54 * In addition to accessing the objects remotely we must be able to update
55 * the client side cache. This is done using the 'update' signal of the
56 * org.freedesktop.atspi.Tree interface. The update signal should send out
57 * all of the cacheable data for each AtkObject that has changed since the
58 * last update. It should also provide a list of objects that have been
59 * removed since the last update.
61 * To enbale this two hash tables are kept. One keeps a list of AtkObjects
62 * that have been updated. The other a list of objects that have been
63 * removed since the last 'update' signal. The reason they are
64 * stored as hash tables is to ensure that if an AtkObject is removed
65 * and then added between update signals then the object is easy to delete
66 * from the 'update' list without doing a costly lookup.
68 * The mappings will be called 'reference lookup tables'
69 * The hashtable containing AtkObjects that need updating in the client side
70 * cache will be called the 'update list'
71 * The hashtable containing the AtkObjects that need removing from the client
72 * side cache will be called the 'removal list'
75 GHashTable *ref2ptr = NULL; /* Used for converting a D-Bus path (Reference) to the object pointer */
77 GHashTable *update_list = NULL; /* Stores the objects that need a client side cache update */
78 GHashTable *remove_list = NULL; /* Stores the objects that need to be removed from the client side cache */
80 static guint counter = 1;
82 /*---------------------------------------------------------------------------*/
85 * Each AtkObject must be asssigned a D-Bus path (Reference)
87 * This function provides an integer reference for a new
91 assign_reference(void)
94 /* Reference of 0 not allowed as used as direct key in hash table */
99 /*---------------------------------------------------------------------------*/
102 * Called when a registered AtkObject is deleted.
104 * Removes the AtkObject from the reference lookup tables.
105 * Adds the reference of the object to the removal list.
108 deregister_accessible(gpointer data, GObject *accessible)
112 g_assert(ATK_IS_OBJECT(accessible));
115 ref = GPOINTER_TO_INT(g_object_get_data (accessible, "dbus-id"));
117 /* Remove from update list */
118 g_hash_table_remove(update_list, GINT_TO_POINTER(ref));
122 g_hash_table_remove(ref2ptr, GINT_TO_POINTER(ref));
123 /* Add to removal list */
126 * Pyatspi client side exceptions have occured indicating
127 * that an object has been removed twice.
128 * This should not be possible and needs investigation.
130 g_hash_table_insert(remove_list, GINT_TO_POINTER(ref), NULL);
133 atk_tree_cache_needs_update();
136 /*---------------------------------------------------------------------------*/
139 * Registers a new AtkObject.
141 * Adds the AtkObject to the reference lookup tables.
142 * Adds the AtkObject to the update list.
145 register_accessible (AtkObject *accessible)
149 g_assert(ATK_IS_OBJECT(accessible));
151 reference = assign_reference();
153 g_hash_table_insert (ref2ptr, GINT_TO_POINTER(reference), accessible);
154 g_object_set_data (G_OBJECT(accessible), "dbus-id", GINT_TO_POINTER(reference));
155 g_object_weak_ref(G_OBJECT(accessible), deregister_accessible, NULL);
157 /* Add to update list */
158 g_hash_table_insert (update_list, GINT_TO_POINTER(reference), accessible);
160 atk_tree_cache_needs_update();
165 /*---------------------------------------------------------------------------*/
167 /* TODO Turn these into an iterator API - Think about the locking */
170 atk_dbus_foreach_registered(GHFunc func, gpointer data)
172 g_hash_table_foreach(ref2ptr, func, data);
175 /*---------------------------------------------------------------------------*/
178 atk_dbus_foreach_update_list(GHFunc func, gpointer data)
180 g_hash_table_foreach(update_list, func, data);
181 g_hash_table_remove_all(update_list);
184 /*---------------------------------------------------------------------------*/
187 atk_dbus_foreach_remove_list(GHFunc func, gpointer data)
189 g_hash_table_foreach(remove_list, func, data);
190 g_hash_table_remove_all(remove_list);
193 /*---------------------------------------------------------------------------*/
196 * Called on an AtkObject when it has changed in such a way
197 * that the client side cache of the object will need updating.
200 atk_dbus_notify_change(AtkObject *accessible)
203 g_assert(ATK_IS_OBJECT(accessible));
205 if (!g_object_get_data (G_OBJECT (accessible), "dbus-id"))
207 register_accessible(accessible);
211 ref = g_object_get_data (G_OBJECT (accessible), "dbus-id");
212 g_hash_table_insert (update_list, ref, accessible);
213 atk_tree_cache_needs_update();
217 /*---------------------------------------------------------------------------*/
220 * Used to lookup an AtkObject from its D-Bus path.
223 atk_dbus_get_object (const char *path)
230 if (strncmp(path, ATK_BRIDGE_OBJECT_PATH_PREFIX, ATK_BRIDGE_PATH_PREFIX_LENGTH) != 0)
233 path += ATK_BRIDGE_PATH_PREFIX_LENGTH; /* Skip over the prefix */
236 return atk_get_root();
242 data = g_hash_table_lookup (ref2ptr, GINT_TO_POINTER(index));
244 return ATK_OBJECT (data);
249 /*---------------------------------------------------------------------------*/
252 atk_dbus_get_path_from_ref(guint ref)
254 return g_strdup_printf(ATK_BRIDGE_OBJECT_REFERENCE_TEMPLATE, ref);
257 /*---------------------------------------------------------------------------*/
260 * Used to lookup a D-Bus path from the AtkObject.
262 * Objects without a path are registered and provided with one.
265 atk_dbus_get_path (AtkObject *accessible)
269 g_assert (accessible);
271 index = GPOINTER_TO_INT(g_object_get_data (G_OBJECT (accessible), "dbus-id"));
273 index = register_accessible(G_OBJECT(accessible));
275 return g_strdup_printf(ATK_BRIDGE_OBJECT_REFERENCE_TEMPLATE, index);
278 /*---------------------------------------------------------------------------*/
281 * Used to recursively register accessibles.
283 * When children are added to an accessible we need to
284 * iterate over the new subtree provided to register new accessibles.
287 atk_dbus_register_subtree(AtkObject *accessible)
293 ref = GPOINTER_TO_INT(g_object_get_data (G_OBJECT (accessible), "dbus-id"));
295 ref = register_accessible(accessible);
297 n_children = atk_object_get_n_accessible_children(accessible);
298 for (i=0; i < n_children; i++)
300 child = atk_object_ref_accessible_child(accessible, i);
301 atk_dbus_register_subtree(child);
306 /*---------------------------------------------------------------------------*/
309 * Marshals a single object into a D-Bus message.
311 * Unrefs the AtkObject if unref is true.
314 spi_dbus_return_object (DBusMessage *message, AtkObject *obj, gboolean unref)
319 path = atk_dbus_get_path (obj);
322 g_object_unref (obj);
324 reply = dbus_message_new_method_return (message);
327 dbus_message_append_args (reply, DBUS_TYPE_OBJECT_PATH, path,
333 /*---------------------------------------------------------------------------*/
336 * Marshals a variant containing the object reference into the message iter
339 * Unrefs the object if unref is true.
342 spi_dbus_return_v_object (DBusMessageIter *iter, AtkObject *obj, int unref)
346 path = atk_dbus_get_path (obj);
349 g_object_unref (obj);
351 return droute_return_v_object (iter, path);
354 /*---------------------------------------------------------------------------*/
357 * Initializes required global data. The update and removal lists
358 * and the reference lookup tables.
360 * Initializes all of the required D-Bus interfaces.
363 atk_dbus_initialize (DRouteData * data)
366 ref2ptr = g_hash_table_new(g_direct_hash, g_direct_equal);
368 update_list = g_hash_table_new(g_direct_hash, g_direct_equal);
370 remove_list = g_hash_table_new(g_direct_hash, g_direct_equal);
372 /* Get the root accessible and add */
373 atk_dbus_register_subtree(atk_get_root());
375 spi_initialize_accessible (data);
376 spi_initialize_action(data);
377 spi_initialize_collection (data);
378 spi_initialize_component (data);
379 spi_initialize_document (data);
380 spi_initialize_editabletext (data);
381 spi_initialize_hyperlink (data);
382 spi_initialize_hypertext (data);
383 spi_initialize_image (data);
384 spi_initialize_selection (data);
385 spi_initialize_table (data);
386 spi_initialize_text (data);
387 spi_initialize_value (data);
388 spi_initialize_introspectable(data, (DRouteGetDatumFunction) atk_dbus_get_object);
391 /*END------------------------------------------------------------------------*/