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 /*
  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.
  35  *
  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'.
  42  *
  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.
  47  *
  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.
  52  *
  53  */
  54
  55 /*
  56  * FIXME
  57  *
  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.
  62  *
  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:
  66  *
  67  * Removing infinite spaces (Child access no longer references child).
  68  * Removing lazy creation of accessible objects.
  69  */
  70
  71 #define SPI_ATK_OBJECT_PATH_PREFIX  "/org/freedesktop/atspi/accessible"
  72 #define SPI_ATK_OBJECT_PATH_DESKTOP "/root"
  73
  74 #define SPI_ATK_PATH_PREFIX_LENGTH 33
  75 #define SPI_ATK_OBJECT_REFERENCE_TEMPLATE SPI_ATK_OBJECT_PATH_PREFIX "/%d"
  76
  77
  78 static GHashTable *ref2ptr = NULL; /* Used for converting a D-Bus path (Reference) to the object pointer */
  79
  80 static guint counter = 1;
  81
  82 static GStaticRecMutex registration_mutex = G_STATIC_REC_MUTEX_INIT;
  83
  84 /*---------------------------------------------------------------------------*/
  85
  86 static GStaticMutex   recursion_check_guard = G_STATIC_MUTEX_INIT;
  87 static gboolean       recursion_check = FALSE;
  88
  89 static gboolean
  90 recursion_check_and_set ()
  91 {
  92   gboolean ret;
  93   g_static_mutex_lock   (&recursion_check_guard);
  94   ret = recursion_check;
  95   recursion_check = TRUE;
  96   g_static_mutex_unlock (&recursion_check_guard);
  97   return ret;
  98 }
  99
 100 static void
 101 recursion_check_unset ()
 102 {
 103   g_static_mutex_lock   (&recursion_check_guard);
 104   recursion_check = FALSE;
 105   g_static_mutex_unlock (&recursion_check_guard);
 106 }
 107
 108 /*---------------------------------------------------------------------------*/
 109
 110 /*
 111  * Each AtkObject must be asssigned a D-Bus path (Reference)
 112  *
 113  * This function provides an integer reference for a new
 114  * AtkObject.
 115  */
 116 static guint
 117 assign_reference(void)
 118 {
 119   counter++;
 120   /* Reference of 0 not allowed as used as direct key in hash table */
 121   if (counter == 0)
 122     counter++;
 123   return counter;
 124 }
 125
 126 /*
 127  * Returns the reference of the object, or 0 if it is not registered.
 128  */
 129 static guint
 130 object_to_ref (AtkObject *accessible)
 131 {
 132   return GPOINTER_TO_INT(g_object_get_data (G_OBJECT (accessible), "dbus-id"));
 133 }
 134
 135 /*
 136  * Converts the Accessible object reference to its D-Bus object path
 137  */
 138 static gchar *
 139 ref_to_path (guint ref)
 140 {
 141   return g_strdup_printf(SPI_ATK_OBJECT_REFERENCE_TEMPLATE, ref);
 142 }
 143
 144 /*---------------------------------------------------------------------------*/
 145
 146 /*
 147  * Callback for when a registered AtkObject is destroyed.
 148  *
 149  * Removes the AtkObject from the reference lookup tables, meaning
 150  * it is no longer exposed over D-Bus.
 151  */
 152 static void
 153 deregister_accessible (gpointer data, GObject *accessible)
 154 {
 155   guint ref;
 156   g_assert (ATK_IS_OBJECT (accessible));
 157
 158   ref = object_to_ref (ATK_OBJECT(accessible));
 159   if (ref != 0)
 160     {
 161       g_hash_table_remove(ref2ptr, GINT_TO_POINTER(ref));
 162     }
 163 }
 164
 165 /*
 166  * Called to register an AtkObject with AT-SPI and expose it over D-Bus.
 167  */
 168 static void
 169 register_accessible (AtkObject *accessible)
 170 {
 171   guint ref;
 172   g_assert(ATK_IS_OBJECT(accessible));
 173
 174   ref = assign_reference();
 175
 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);
 179 }
 180
 181 /*---------------------------------------------------------------------------*/
 182
 183 #ifdef SPI_ATK_DEBUG
 184 /*
 185  * This function checks that the ref-count of an accessible
 186  * is greater than 1.
 187  *
 188  * There is not currently any remote reference counting
 189  * in AT-SPI D-Bus so objects that are remotely owned are not
 190  * allowed.
 191  *
 192  * TODO Add debug wrapper
 193  */
 194 static gboolean
 195 non_owned_accessible (AtkObject *accessible)
 196 {
 197    if ((G_OBJECT (accessible))->ref_count <= 1)
 198      {
 199        g_warning ("AT-SPI: Child referenced that is not owned by its parent");
 200        return TRUE;
 201      }
 202    else
 203      {
 204        return FALSE;
 205      }
 206 }
 207 #endif /* SPI_ATK_DEBUG */
 208
 209 /*---------------------------------------------------------------------------*/
 210
 211 static gboolean
 212 has_manages_descendants (AtkObject *accessible)
 213 {
 214    AtkStateSet *state;
 215    gboolean result = FALSE;
 216
 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.
 220     */
 221    state = atk_object_ref_state_set (accessible);
 222    if (atk_state_set_contains_state (state, ATK_STATE_MANAGES_DESCENDANTS))
 223      {
 224 #ifdef SPI_ATK_DEBUG
 225        g_warning ("AT-SPI: Object with 'Manages descendants' states not currently handled by AT-SPI");
 226 #endif
 227        result = TRUE;
 228      }
 229    g_object_unref (state);
 230
 231    return result;
 232 }
 233
 234 /*
 235  * Registers a subtree of accessible objects
 236  * rooted at the accessible object provided.
 237  *
 238  * The leaf nodes do not have their children
 239  * registered. A node is considered a leaf
 240  * if it has the state "manages-descendants"
 241  * or if it has already been registered.
 242  */
 243 void
 244 register_subtree (AtkObject *accessible)
 245 {
 246   AtkObject *current, *tmp;
 247   GQueue    *stack;
 248   guint      i;
 249   gboolean   recurse;
 250
 251
 252   current = g_object_ref (accessible);
 253   if (has_manages_descendants (current))
 254     {
 255       g_object_unref (current);
 256       return;
 257     }
 258
 259   stack = g_queue_new ();
 260
 261   register_accessible (current);
 262   g_queue_push_head (stack, GINT_TO_POINTER (0));
 263
 264   /*
 265    * The index held on the stack is the next child node
 266    * that needs processing at the corresponding level in the tree.
 267    */
 268   while (!g_queue_is_empty (stack))
 269     {
 270       /* Find the next child node that needs processing */
 271
 272       i = GPOINTER_TO_INT(g_queue_peek_head (stack));
 273       recurse = FALSE;
 274
 275       while (i < atk_object_get_n_accessible_children (current) &&
 276              recurse == FALSE)
 277         {
 278           tmp = atk_object_ref_accessible_child (current, i);
 279
 280 #ifdef SPI_ATK_DEBUG
 281           non_owned_accessible (tmp);
 282 #endif
 283
 284           if (object_to_ref (tmp))
 285             {
 286               /* If its already registered, just update */
 287               spi_emit_cache_update (tmp, atk_adaptor_app_data->bus);
 288             }
 289           else if (has_manages_descendants (tmp))
 290             {
 291               /* If it has manages descendants, just register and update */
 292               register_accessible (tmp);
 293               spi_emit_cache_update (tmp, atk_adaptor_app_data->bus);
 294             }
 295           else
 296             {
 297               recurse = TRUE;
 298             }
 299
 300           if (!recurse)
 301             {
 302               g_object_unref (G_OBJECT (tmp));
 303             }
 304
 305           i++;
 306         }
 307
 308       if (recurse)
 309         {
 310           /* Push onto stack */
 311           current = tmp;
 312           register_accessible (current);
 313
 314           g_queue_peek_head_link (stack)->data = GINT_TO_POINTER (i);
 315           g_queue_push_head (stack, GINT_TO_POINTER (0));
 316         }
 317       else
 318         {
 319           /* Pop from stack */
 320           spi_emit_cache_update (current, atk_adaptor_app_data->bus);
 321           tmp = current;
 322           current = atk_object_get_parent (current);
 323           g_object_unref (G_OBJECT (tmp));
 324           g_queue_pop_head (stack);
 325         }
 326     }
 327     g_queue_free (stack);
 328 }
 329
 330 /*---------------------------------------------------------------------------*/
 331
 332 /*
 333  * Called when an already registered object is updated in such a
 334  * way that client side cache needs to be updated.
 335  */
 336 static void
 337 update_accessible (AtkObject *accessible)
 338 {
 339   guint  ref = 0;
 340   g_assert(ATK_IS_OBJECT(accessible));
 341
 342   ref = object_to_ref (accessible);
 343   if (ref)
 344     {
 345       spi_emit_cache_update (accessible, atk_adaptor_app_data->bus);
 346     }
 347 }
 348
 349 /*---------------------------------------------------------------------------*/
 350
 351 void
 352 atk_dbus_foreach_registered(GHFunc func, gpointer data)
 353 {
 354   g_hash_table_foreach(ref2ptr, func, data);
 355 }
 356
 357 /*
 358  * Used to lookup an AtkObject from its D-Bus path.
 359  */
 360 AtkObject *
 361 atk_dbus_path_to_object (const char *path)
 362 {
 363   guint index;
 364   void *data;
 365
 366   g_assert (path);
 367
 368   if (strncmp(path, SPI_ATK_OBJECT_PATH_PREFIX, SPI_ATK_PATH_PREFIX_LENGTH) != 0)
 369     return NULL;
 370
 371   path += SPI_ATK_PATH_PREFIX_LENGTH; /* Skip over the prefix */
 372
 373   if (!g_strcmp0 (SPI_ATK_OBJECT_PATH_DESKTOP, path))
 374      return atk_get_root();
 375   if (path[0] != '/')
 376      return NULL;
 377
 378   path++;
 379   index = atoi (path);
 380   data = g_hash_table_lookup (ref2ptr, GINT_TO_POINTER(index));
 381   if (data)
 382     return ATK_OBJECT (data);
 383   else
 384     return NULL;
 385 }
 386
 387 /*
 388  * Used to lookup a D-Bus path from the AtkObject.
 389  */
 390 gchar *
 391 atk_dbus_object_to_path (AtkObject *accessible)
 392 {
 393   guint ref;
 394
 395   ref = object_to_ref (accessible);
 396   if (!ref)
 397       return NULL;
 398   else
 399       return ref_to_path (ref);
 400 }
 401
 402 gchar *
 403 atk_dbus_desktop_object_path ()
 404 {
 405   return g_strdup (SPI_ATK_OBJECT_PATH_PREFIX SPI_ATK_OBJECT_PATH_DESKTOP);
 406 }
 407
 408 /*---------------------------------------------------------------------------*/
 409
 410 /*
 411  * Events are not evaluated for non-registered accessibles.
 412  *
 413  * When a property change is made on a registered accessible
 414  * the client side cache should be updated.
 415  *
 416  * When a parent is changed the subtree is de-registered
 417  * if the parent is not attached to the root accessible.
 418  */
 419 static gboolean
 420 tree_update_listener (GSignalInvocationHint *signal_hint,
 421                       guint                  n_param_values,
 422                       const GValue          *param_values,
 423                       gpointer               data)
 424 {
 425   AtkObject *accessible;
 426   AtkPropertyValues *values;
 427   const gchar *pname = NULL;
 428
 429   g_static_rec_mutex_lock (&registration_mutex);
 430
 431   /* Ensure that only registered accessibles
 432    * have their signals processed.
 433    */
 434   accessible = g_value_get_object (&param_values[0]);
 435   g_assert (ATK_IS_OBJECT (accessible));
 436
 437   if (object_to_ref (accessible))
 438     {
 439 #ifdef SPI_ATK_DEBUG
 440       if (recursion_check_and_set ())
 441           g_warning ("AT-SPI: Recursive use of registration module");
 442 #endif
 443
 444       values = (AtkPropertyValues*) g_value_get_pointer (&param_values[1]);
 445       pname = values[0].property_name;
 446       if (strcmp (pname, "accessible-name") == 0 ||
 447           strcmp (pname, "accessible-description") == 0)
 448         {
 449           update_accessible (accessible);
 450         }
 451       /* Parent value us updated by child-add signal of parent object */
 452
 453       recursion_check_unset ();
 454     }
 455
 456   g_static_rec_mutex_unlock (&registration_mutex);
 457
 458   return TRUE;
 459 }
 460
 461 /*
 462  * Events are not evaluated for non registered accessibles.
 463  *
 464  * When the children of a registered accessible are changed
 465  * the subtree, rooted at the child is registered.
 466  */
 467 static gboolean
 468 tree_update_children_listener (GSignalInvocationHint *signal_hint,
 469                                guint                  n_param_values,
 470                                const GValue          *param_values,
 471                                gpointer               data)
 472 {
 473   AtkObject *accessible;
 474   const gchar *detail = NULL;
 475   AtkObject *child;
 476
 477   g_static_rec_mutex_lock (&registration_mutex);
 478
 479   /* Ensure that only registered accessibles
 480    * have their signals processed.
 481    */
 482   accessible = g_value_get_object (&param_values[0]);
 483   g_assert (ATK_IS_OBJECT (accessible));
 484
 485   if (object_to_ref (accessible))
 486     {
 487 #ifdef SPI_ATK_DEBUG
 488       if (recursion_check_and_set ())
 489           g_warning ("AT-SPI: Recursive use of registration module");
 490 #endif
 491
 492       if (signal_hint->detail)
 493           detail = g_quark_to_string (signal_hint->detail);
 494
 495       if (!strcmp (detail, "add"))
 496         {
 497           gpointer child;
 498           int index = g_value_get_uint (param_values + 1);
 499           child = g_value_get_pointer (param_values + 2);
 500
 501           if (!ATK_IS_OBJECT (child))
 502             {
 503               child = atk_object_ref_accessible_child (accessible, index);
 504 #ifdef SPI_ATK_DEBUG
 505               non_owned_accessible (child);
 506 #endif
 507             }
 508           register_subtree (child);
 509         }
 510
 511       recursion_check_unset ();
 512     }
 513
 514   g_static_rec_mutex_unlock (&registration_mutex);
 515
 516   return TRUE;
 517 }
 518
 519 /*
 520  * Initializes required global data. The update and removal lists
 521  * and the reference lookup tables.
 522  *
 523  * Initializes all of the required D-Bus interfaces.
 524  */
 525 void
 526 atk_dbus_initialize (AtkObject *root)
 527 {
 528   if (!ref2ptr)
 529     ref2ptr = g_hash_table_new(g_direct_hash, g_direct_equal);
 530
 531 #ifdef SPI_ATK_DEBUG
 532   if (g_thread_supported ())
 533       g_message ("AT-SPI: Threads enabled");
 534 #endif
 535
 536   register_subtree (root);
 537
 538   atk_add_global_event_listener (tree_update_listener, "Gtk:AtkObject:property-change");
 539   atk_add_global_event_listener (tree_update_children_listener, "Gtk:AtkObject:children-changed");
 540 }
 541
 542 /*END------------------------------------------------------------------------*/
 543