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