atk-adaptor/accessible-register.c

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2008 Novell, Inc.
   6  * Copyright 2008, 2009 Codethink Ltd.
   7  *
   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.
  12  *
  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.
  17  *
  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.
  22  */
  23
  24 #include <stdio.h>
  25 #include <stdlib.h>
  26 #include <string.h>
  27
  28 #include "bridge.h"
  29 #include "accessible-register.h"
  30
  31 #define ATK_BRIDGE_OBJECT_PATH_PREFIX "/org/freedesktop/atspi/accessible"
  32 #define ATK_BRIDGE_OBJECT_REFERENCE_TEMPLATE ATK_BRIDGE_OBJECT_PATH_PREFIX "/%d"
  33 #define ATK_BRIDGE_PATH_PREFIX_LENGTH 33
  34
  35 /*
  36  * This module is responsible for keeping track of all the AtkObjects in
  37  * the application, so that they can be accessed remotely and placed in
  38  * a client side cache.
  39  *
  40  * To access an AtkObject remotely we need to provide a D-Bus object
  41  * path for it. The D-Bus object paths used have a standard prefix
  42  * (ATK_BRIDGE_OBJECT_PATH_PREFIX). Appended to this prefix is a string
  43  * representation of an integer reference. So to access an AtkObject
  44  * remotely we keep a Hashtable that maps the given reference to
  45  * the AtkObject pointer. An object in this hash table is said to be 'registered'.
  46  *
  47  * The architecture of AT-SPI dbus is such that AtkObjects are not
  48  * remotely reference counted. This means that we need to keep track of
  49  * object destruction. When an object is destroyed it must be 'deregistered'
  50  * To do this lookup we keep a dbus-id attribute on each AtkObject.
  51  *
  52  * In addition to accessing the objects remotely we must be able to update
  53  * the client side cache. This is done using the 'update' signal of the
  54  * org.freedesktop.atspi.Tree interface. The update signal should send out
  55  * all of the cacheable data for an Accessible object.
  56  */
  57
  58 GHashTable *ref2ptr = NULL; /* Used for converting a D-Bus path (Reference) to the object pointer */
  59
  60 static guint counter = 1;
  61
  62 /*---------------------------------------------------------------------------*/
  63
  64 /*
  65  * Each AtkObject must be asssigned a D-Bus path (Reference)
  66  *
  67  * This function provides an integer reference for a new
  68  * AtkObject.
  69  */
  70 static guint
  71 assign_reference(void)
  72 {
  73   counter++;
  74   /* Reference of 0 not allowed as used as direct key in hash table */
  75   if (counter == 0)
  76     counter++;
  77 }
  78
  79 /*
  80  * Returns the reference of the object, or 0 if it is not registered.
  81  */
  82 static guint
  83 object_to_ref (AtkObject *accessible)
  84 {
  85   return GPOINTER_TO_INT(g_object_get_data (G_OBJECT (accessible), "dbus-id"));
  86 }
  87
  88 /*
  89  * Converts the Accessible object reference to its D-Bus object path
  90  */
  91 static gchar *
  92 ref_to_path (guint ref)
  93 {
  94   return g_strdup_printf(ATK_BRIDGE_OBJECT_REFERENCE_TEMPLATE, ref);
  95 }
  96
  97 /*---------------------------------------------------------------------------*/
  98
  99 /*
 100  * Called when a registered AtkObject is deleted.
 101  * Removes the AtkObject from the reference lookup tables.
 102  */
 103 static void
 104 deregister_accessible(gpointer data, GObject *accessible)
 105 {
 106   guint ref;
 107   gchar *path;
 108
 109   g_assert(ATK_IS_OBJECT(accessible));
 110
 111   ref = atk_dbus_object_to_ref (ATK_OBJECT(accessible));
 112
 113   if (ref != 0)
 114     {
 115       g_hash_table_remove(ref2ptr, GINT_TO_POINTER(ref));
 116     }
 117 }
 118
 119 /*
 120  * Called to register an AtkObject with AT-SPI and expose it over D-Bus.
 121  */
 122 static void
 123 register_accessible (AtkObject *accessible)
 124 {
 125   guint ref;
 126   g_assert(ATK_IS_OBJECT(accessible));
 127
 128   ref = assign_reference();
 129
 130   g_hash_table_insert (ref2ptr, GINT_TO_POINTER(ref), accessible);
 131   g_object_set_data (G_OBJECT(accessible), "dbus-id", GINT_TO_POINTER(ref));
 132   g_object_weak_ref(G_OBJECT(accessible), deregister_accessible, NULL);
 133 }
 134
 135 /*---------------------------------------------------------------------------*/
 136
 137 typedef void     (*ActionFunc) (AtkObject *);
 138
 139 /* Return true if action should be performed */
 140 typedef gboolean (*FilterFunc) (AtkObject *);
 141
 142 /*
 143  * This function performs a depth first traversal of a tree of AtkObjects.
 144  *
 145  * It uses a FilterFunc to determine if a node needs to have an action
 146  * performed on it.
 147  *
 148  * Nodes that are filtered out become leaves and no recursion is performed on
 149  * them.
 150  *
 151  * Nodes where an action was performed are returned in a GList.
 152  */
 153 void
 154 traverse_atk_tree (AtkObject *accessible,
 155                    GList **visited,
 156                    ActionFunc action,
 157                    FilterFunc filter)
 158 {
 159   AtkObject *current, *tmp;
 160   GQueue    *stack;
 161   GList     *uplist = NULL;
 162   guint      i, ref;
 163   gboolean   recurse;
 164
 165   if (!filter (accessible))
 166       return;
 167
 168   stack = g_queue_new ();
 169   current = g_object_ref (accessible);
 170   action (current)
 171   *visited = g_list_prepend (*visited, current);
 172   g_queue_push_head (stack, GINT_TO_POINTER (0));
 173
 174   /*
 175    * The index held on the stack is the next child node
 176    * that needs processing at the corresponding level in the tree.
 177    */
 178   while (!g_queue_is_empty (stack))
 179     {
 180       /* Find the next child node that needs processing */
 181       i = GPOINTER_TO_INT(g_queue_peek_head (stack));
 182       recurse = FALSE;
 183       while (i < atk_object_get_n_accessible_children (current) &&
 184              recurse == FALSE)
 185         {
 186           tmp = atk_object_ref_accessible_child (current, i);
 187           /* If filter function */
 188           if (filter (tmp))
 189             {
 190               recurse = TRUE;
 191             }
 192           else
 193             {
 194               i++;
 195               g_object_unref (G_OBJECT (tmp));
 196             }
 197         }
 198
 199       if (recurse)
 200         {
 201           /* Push onto stack */
 202           current = tmp;
 203           action (current);
 204           *visited = g_list_prepend (*visited, current);
 205           g_queue_peek_head_link (stack)->data = GINT_TO_POINTER (i+1);
 206           g_queue_push_head (stack, GINT_TO_POINTER (0));
 207         }
 208       else
 209         {
 210           /* Pop from stack */
 211           tmp = current;
 212           current = atk_object_get_parent (current);
 213           g_object_unref (G_OBJECT (tmp));
 214           g_queue_pop_head (stack);
 215         }
 216     }
 217
 218   return ref;
 219 }
 220
 221 /*---------------------------------------------------------------------------*/
 222
 223 /*
 224  * Called when an already registered object is updated in such a
 225  * way that client side cache needs to be updated.
 226  */
 227 static void
 228 update_accessible (AtkObject *accessible)
 229 {
 230   guint  ref = 0;
 231   g_assert(ATK_IS_OBJECT(accessible));
 232
 233   ref = atk_dbus_object_to_ref (accessible);
 234   if (ref)
 235     {
 236       spi_emit_cache_update (accessible, atk_adaptor_app_data->bus);
 237     }
 238 }
 239
 240 /*---------------------------------------------------------------------------*/
 241
 242 void
 243 atk_dbus_foreach_registered(GHFunc func, gpointer data)
 244 {
 245   g_hash_table_foreach(ref2ptr, func, data);
 246 }
 247
 248 /*
 249  * Used to lookup an AtkObject from its D-Bus path.
 250  */
 251 AtkObject *
 252 atk_dbus_path_to_object (const char *path)
 253 {
 254   guint index;
 255   void *data;
 256
 257   g_assert (path);
 258
 259   if (strncmp(path, ATK_BRIDGE_OBJECT_PATH_PREFIX, ATK_BRIDGE_PATH_PREFIX_LENGTH) != 0)
 260     return NULL;
 261
 262   path += ATK_BRIDGE_PATH_PREFIX_LENGTH; /* Skip over the prefix */
 263
 264   if (path[0] == '\0')
 265      return atk_get_root();
 266   if (path[0] != '/')
 267      return NULL;
 268
 269   path++;
 270   index = atoi (path);
 271   data = g_hash_table_lookup (ref2ptr, GINT_TO_POINTER(index));
 272   if (data)
 273     return ATK_OBJECT (data);
 274   else
 275     return NULL;
 276 }
 277
 278 /*
 279  * Used to lookup a D-Bus path from the AtkObject.
 280  */
 281 gchar *
 282 atk_dbus_object_to_path (AtkObject *accessible)
 283 {
 284   guint ref;
 285   g_assert(ATK_IS_OBJECT(accessible));
 286
 287   ref = atk_dbus_object_to_ref (accessible);
 288   if (!ref)
 289       return NULL;
 290   else
 291       return atk_dbus_ref_to_path (ref);
 292 }
 293
 294 /*---------------------------------------------------------------------------*/
 295
 296 /*
 297  * Events are not evaluated for non-registered accessibles.
 298  *
 299  * When a property change is made on a registered accessible
 300  * the client side cache should be updated.
 301  *
 302  * When a parent is changed the subtree is de-registered
 303  * if the parent is not attached to the root accessible.
 304  */
 305 static gboolean
 306 tree_update_listener (GSignalInvocationHint *signal_hint,
 307                       guint                  n_param_values,
 308                       const GValue          *param_values,
 309                       gpointer               data)
 310 {
 311   AtkObject *accessible;
 312   AtkPropertyValues *values;
 313   const gchar *pname = NULL;
 314
 315   accessible = g_value_get_object (&param_values[0]);
 316   values = (AtkPropertyValues*) g_value_get_pointer (&param_values[1]);
 317
 318   pname = values[0].property_name;
 319
 320   if (!atk_dbus_object_to_ref (accessible))
 321       return TRUE;
 322
 323   if (strcmp (pname, "accessible-name") == 0 ||
 324       strcmp (pname, "accessible-description"))
 325     {
 326       atk_dbus_update_accessible (accessible);
 327     }
 328   else if (strcmp (pname, "accessible-parent"))
 329     {
 330       guint ref;
 331
 332       ref = atk_dbus_object_to_ref;
 333       if (!ref)
 334     }
 335   return TRUE;
 336 }
 337
 338 /*
 339  * Events are not evaluated for non registered accessibles.
 340  *
 341  * When the children of a registered accessible are changed
 342  * the subtree, rooted at the child is registered.
 343  */
 344 static gboolean
 345 tree_update_children_listener (GSignalInvocationHint *signal_hint,
 346                                guint                  n_param_values,
 347                                const GValue          *param_values,
 348                                gpointer               data)
 349 {
 350   AtkObject *accessible;
 351   const gchar *detail = NULL;
 352   AtkObject *child;
 353   gboolean child_needs_unref = FALSE;
 354
 355   if (signal_hint->detail)
 356     detail = g_quark_to_string (signal_hint->detail);
 357
 358   accessible = g_value_get_object (&param_values[0]);
 359   if (!strcmp (detail, "add"))
 360     {
 361       gpointer child;
 362       int index = g_value_get_uint (param_values + 1);
 363       child = g_value_get_pointer (param_values + 2);
 364
 365       if (ATK_IS_OBJECT (child))
 366           g_object_ref (child);
 367       else
 368           child = atk_object_ref_accessible_child (accessible, index);
 369
 370       atk_dbus_register_subtree (child);
 371       g_object_unref (child);
 372     }
 373   return TRUE;
 374 }
 375
 376 /*
 377  * Initializes required global data. The update and removal lists
 378  * and the reference lookup tables.
 379  *
 380  * Initializes all of the required D-Bus interfaces.
 381  */
 382 void
 383 atk_dbus_initialize (AtkObject *root)
 384 {
 385   if (!ref2ptr)
 386     ref2ptr = g_hash_table_new(g_direct_hash, g_direct_equal);
 387
 388   atk_dbus_register_accessible (root);
 389
 390   atk_add_global_event_listener (tree_update_listener, "Gtk:AtkObject:property-change");
 391   atk_add_global_event_listener (tree_update_children_listener, "Gtk:AtkObject:children-changed");
 392 }
 393
 394 /*END------------------------------------------------------------------------*/
 395