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  * Removes the AtkObject from the reference lookup tables, meaning
 101  * it is no longer exposed over D-Bus.
 102  */
 103 static void
 104 deregister_accessible (guint ref)
 105 {
 106   g_hash_table_remove(ref2ptr, GINT_TO_POINTER(ref));
 107 }
 108
 109 /*
 110  * Callback for when a registered AtkObject is destroyed.
 111  */
 112 static void
 113 deregister_callback (gpointer data, GObject *accessible)
 114 {
 115   guint ref;
 116   g_assert (ATK_IS_OBJECT (accessible));
 117
 118   ref = object_to_ref (ATK_OBJECT(accessible));
 119   if (ref != 0)
 120     {
 121       deregister_accessible (ref);
 122     }
 123 }
 124
 125 /*
 126  * Called to register an AtkObject with AT-SPI and expose it over D-Bus.
 127  */
 128 static void
 129 register_accessible (AtkObject *accessible)
 130 {
 131   guint ref;
 132   g_assert(ATK_IS_OBJECT(accessible));
 133
 134   ref = assign_reference();
 135
 136   g_hash_table_insert (ref2ptr, GINT_TO_POINTER(ref), accessible);
 137   g_object_set_data (G_OBJECT(accessible), "dbus-id", GINT_TO_POINTER(ref));
 138   g_object_weak_ref(G_OBJECT(accessible), deregister_callback, NULL);
 139 }
 140
 141 /*---------------------------------------------------------------------------*/
 142
 143 typedef void     (*ActionFunc) (GList **, AtkObject *);
 144
 145 /* Return true if action should be performed */
 146 typedef gboolean (*FilterFunc) (AtkObject *);
 147
 148 /*
 149  * This function performs a depth first traversal of a tree of AtkObjects.
 150  *
 151  * It uses a FilterFunc to determine if a node needs to have an action
 152  * performed on it.
 153  *
 154  * Nodes that are filtered out become leaves and no recursion is performed on
 155  * them.
 156  */
 157 void
 158 traverse_atk_tree (AtkObject *accessible,
 159                    GList **visited,
 160                    ActionFunc action,
 161                    FilterFunc filter)
 162 {
 163   AtkObject *current, *tmp;
 164   GQueue    *stack;
 165   guint      i;
 166   gboolean   recurse;
 167
 168   if (!filter (accessible))
 169       return;
 170
 171   stack = g_queue_new ();
 172   current = g_object_ref (accessible);
 173   action (visited, current);
 174   g_queue_push_head (stack, GINT_TO_POINTER (0));
 175
 176   /*
 177    * The index held on the stack is the next child node
 178    * that needs processing at the corresponding level in the tree.
 179    */
 180   while (!g_queue_is_empty (stack))
 181     {
 182       /* Find the next child node that needs processing */
 183       i = GPOINTER_TO_INT(g_queue_peek_head (stack));
 184       recurse = FALSE;
 185       while (i < atk_object_get_n_accessible_children (current) &&
 186              recurse == FALSE)
 187         {
 188           tmp = atk_object_ref_accessible_child (current, i);
 189           /* If filter function */
 190           if (filter (tmp))
 191             {
 192               recurse = TRUE;
 193             }
 194           else
 195             {
 196               i++;
 197               g_object_unref (G_OBJECT (tmp));
 198             }
 199         }
 200
 201       if (recurse)
 202         {
 203           /* Push onto stack */
 204           current = tmp;
 205           action (visited, current);
 206           g_queue_peek_head_link (stack)->data = GINT_TO_POINTER (i+1);
 207           g_queue_push_head (stack, GINT_TO_POINTER (0));
 208         }
 209       else
 210         {
 211           /* Pop from stack */
 212           tmp = current;
 213           current = atk_object_get_parent (current);
 214           g_object_unref (G_OBJECT (tmp));
 215           g_queue_pop_head (stack);
 216         }
 217     }
 218 }
 219
 220 /*---------------------------------------------------------------------------*/
 221
 222 /*
 223  * Called when an already registered object is updated in such a
 224  * way that client side cache needs to be updated.
 225  */
 226 static void
 227 update_accessible (AtkObject *accessible)
 228 {
 229   guint  ref = 0;
 230   g_assert(ATK_IS_OBJECT(accessible));
 231
 232   ref = object_to_ref (accessible);
 233   if (ref)
 234     {
 235       spi_emit_cache_update (accessible, atk_adaptor_app_data->bus);
 236     }
 237 }
 238
 239 /*---------------------------------------------------------------------------*/
 240
 241 static gboolean
 242 register_filter (AtkObject *accessible)
 243 {
 244    if (object_to_ref (accessible))
 245        return TRUE;
 246    else
 247        return FALSE;
 248 }
 249
 250 static void
 251 register_action (GList **registered, AtkObject *accessible)
 252 {
 253   register_accessible (accessible);
 254   *registered = g_list_prepend (*registered, accessible);
 255 }
 256
 257 static void
 258 register_foreach (gpointer data, gpointer user_data)
 259 {
 260   spi_emit_cache_update (ATK_OBJECT (data), atk_adaptor_app_data->bus);
 261 }
 262
 263 static void
 264 register_subtree (AtkObject *accessible)
 265 {
 266   GList *registered = NULL;
 267
 268   traverse_atk_tree (accessible,
 269                      &registered,
 270                      (ActionFunc) register_accessible,
 271                      (FilterFunc) register_filter);
 272
 273   g_list_foreach (registered, register_foreach, NULL);
 274 }
 275
 276
 277 static void
 278 register_ancestors (AtkObject *accessible)
 279 {
 280   AtkObject *current;
 281   guint ref;
 282   GList *registered = NULL;
 283
 284   current = atk_object_get_parent (accessible);
 285   while (current)
 286     {
 287       ref = atk_dbus_ref_from_object (current);
 288       if (!ref)
 289           register_action (&registered, current);
 290       current = atk_object_get_parent (accessible);
 291     }
 292
 293   g_list_foreach (registered, register_foreach, NULL);
 294 }
 295
 296 /*---------------------------------------------------------------------------*/
 297
 298 void
 299 atk_dbus_foreach_registered(GHFunc func, gpointer data)
 300 {
 301   g_hash_table_foreach(ref2ptr, func, data);
 302 }
 303
 304 /*
 305  * Used to lookup an AtkObject from its D-Bus path.
 306  */
 307 AtkObject *
 308 atk_dbus_path_to_object (const char *path)
 309 {
 310   guint index;
 311   void *data;
 312
 313   g_assert (path);
 314
 315   if (strncmp(path, ATK_BRIDGE_OBJECT_PATH_PREFIX, ATK_BRIDGE_PATH_PREFIX_LENGTH) != 0)
 316     return NULL;
 317
 318   path += ATK_BRIDGE_PATH_PREFIX_LENGTH; /* Skip over the prefix */
 319
 320   if (path[0] == '\0')
 321      return atk_get_root();
 322   if (path[0] != '/')
 323      return NULL;
 324
 325   path++;
 326   index = atoi (path);
 327   data = g_hash_table_lookup (ref2ptr, GINT_TO_POINTER(index));
 328   if (data)
 329     return ATK_OBJECT (data);
 330   else
 331     return NULL;
 332 }
 333
 334 /*
 335  * Used to lookup a D-Bus path from the AtkObject.
 336  */
 337 gchar *
 338 atk_dbus_object_to_path (AtkObject *accessible)
 339 {
 340   guint ref;
 341   g_assert(ATK_IS_OBJECT(accessible));
 342
 343   ref = object_to_ref (accessible);
 344   if (!ref)
 345       return NULL;
 346   else
 347       return atk_dbus_ref_to_path (ref);
 348 }
 349
 350 /*---------------------------------------------------------------------------*/
 351
 352 /*
 353  * Events are not evaluated for non-registered accessibles.
 354  *
 355  * When a property change is made on a registered accessible
 356  * the client side cache should be updated.
 357  *
 358  * When a parent is changed the subtree is de-registered
 359  * if the parent is not attached to the root accessible.
 360  */
 361 static gboolean
 362 tree_update_listener (GSignalInvocationHint *signal_hint,
 363                       guint                  n_param_values,
 364                       const GValue          *param_values,
 365                       gpointer               data)
 366 {
 367   AtkObject *accessible;
 368   AtkPropertyValues *values;
 369   const gchar *pname = NULL;
 370
 371   accessible = g_value_get_object (&param_values[0]);
 372   values = (AtkPropertyValues*) g_value_get_pointer (&param_values[1]);
 373
 374   pname = values[0].property_name;
 375
 376   if (!object_to_ref (accessible))
 377       return TRUE;
 378
 379   if (strcmp (pname, "accessible-name") == 0 ||
 380       strcmp (pname, "accessible-description"))
 381     {
 382       atk_dbus_update_accessible (accessible);
 383     }
 384   else if (strcmp (pname, "accessible-parent"))
 385     {
 386       register_ancestors (accessible);
 387     }
 388   return TRUE;
 389 }
 390
 391 /*
 392  * Events are not evaluated for non registered accessibles.
 393  *
 394  * When the children of a registered accessible are changed
 395  * the subtree, rooted at the child is registered.
 396  */
 397 static gboolean
 398 tree_update_children_listener (GSignalInvocationHint *signal_hint,
 399                                guint                  n_param_values,
 400                                const GValue          *param_values,
 401                                gpointer               data)
 402 {
 403   AtkObject *accessible;
 404   const gchar *detail = NULL;
 405   AtkObject *child;
 406   gboolean child_needs_unref = FALSE;
 407
 408   if (signal_hint->detail)
 409     detail = g_quark_to_string (signal_hint->detail);
 410
 411   accessible = g_value_get_object (&param_values[0]);
 412   if (!strcmp (detail, "add"))
 413     {
 414       gpointer child;
 415       int index = g_value_get_uint (param_values + 1);
 416       child = g_value_get_pointer (param_values + 2);
 417
 418       if (ATK_IS_OBJECT (child))
 419           g_object_ref (child);
 420       else
 421           child = atk_object_ref_accessible_child (accessible, index);
 422
 423       register_subtree (child);
 424       g_object_unref (child);
 425     }
 426   return TRUE;
 427 }
 428
 429 /*
 430  * Initializes required global data. The update and removal lists
 431  * and the reference lookup tables.
 432  *
 433  * Initializes all of the required D-Bus interfaces.
 434  */
 435 void
 436 atk_dbus_initialize (AtkObject *root)
 437 {
 438   if (!ref2ptr)
 439     ref2ptr = g_hash_table_new(g_direct_hash, g_direct_equal);
 440
 441   register_subtree (root);
 442
 443   atk_add_global_event_listener (tree_update_listener, "Gtk:AtkObject:property-change");
 444   atk_add_global_event_listener (tree_update_children_listener, "Gtk:AtkObject:children-changed");
 445 }
 446
 447 /*END------------------------------------------------------------------------*/
 448