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 "tree-adaptor.h"
  30 #include "accessible-register.h"
  31
  32 /*
  33  * This module is responsible for keeping track of all the AtkObjects in
  34  * the application, so that they can be accessed remotely and placed in
  35  * a client side cache.
  36  *
  37  * To access an AtkObject remotely we need to provide a D-Bus object
  38  * path for it. The D-Bus object paths used have a standard prefix
  39  * (SPI_ATK_OBJECT_PATH_PREFIX). Appended to this prefix is a string
  40  * representation of an integer reference. So to access an AtkObject
  41  * remotely we keep a Hashtable that maps the given reference to
  42  * the AtkObject pointer. An object in this hash table is said to be 'registered'.
  43  *
  44  * The architecture of AT-SPI dbus is such that AtkObjects are not
  45  * remotely reference counted. This means that we need to keep track of
  46  * object destruction. When an object is destroyed it must be 'deregistered'
  47  * To do this lookup we keep a dbus-id attribute on each AtkObject.
  48  *
  49  * In addition to accessing the objects remotely we must be able to update
  50  * the client side cache. This is done using the 'update' signal of the
  51  * org.freedesktop.atspi.Tree interface. The update signal should send out
  52  * all of the cacheable data for an Accessible object.
  53  *
  54  */
  55
  56 /*
  57  * FIXME
  58  *
  59  * This code seems very brittle.
  60  * I would prefer changes to be made to
  61  * gail and the ATK interface so that all Accessible
  62  * objects are registered with an exporting module.
  63  *
  64  * This is the same system as Qt has with the QAccessibleBridge
  65  * and QAccessibleBridgePlugin. It entails some rather
  66  * large structural changes to ATK though:
  67  *
  68  * Removing infinite spaces (Child access no longer references child).
  69  * Removing lazy creation of accessible objects.
  70  */
  71
  72 #define SPI_ATK_OBJECT_PATH_PREFIX  "/org/freedesktop/atspi/accessible"
  73 #define SPI_ATK_OBJECT_PATH_DESKTOP "/root"
  74
  75 #define SPI_ATK_PATH_PREFIX_LENGTH 33
  76 #define SPI_ATK_OBJECT_REFERENCE_TEMPLATE SPI_ATK_OBJECT_PATH_PREFIX "/%d"
  77
  78
  79 static GHashTable *ref2ptr = NULL; /* Used for converting a D-Bus path (Reference) to the object pointer */
  80
  81 static guint reference_counter = 0;
  82
  83 static GStaticRecMutex registration_mutex = G_STATIC_REC_MUTEX_INIT;
  84
  85 /*---------------------------------------------------------------------------*/
  86
  87 static GStaticMutex   recursion_check_guard = G_STATIC_MUTEX_INIT;
  88 static gboolean       recursion_check = FALSE;
  89
  90 static gboolean
  91 recursion_check_and_set ()
  92 {
  93   gboolean ret;
  94   g_static_mutex_lock   (&recursion_check_guard);
  95   ret = recursion_check;
  96   recursion_check = TRUE;
  97   g_static_mutex_unlock (&recursion_check_guard);
  98   return ret;
  99 }
 100
 101 static void
 102 recursion_check_unset ()
 103 {
 104   g_static_mutex_lock   (&recursion_check_guard);
 105   recursion_check = FALSE;
 106   g_static_mutex_unlock (&recursion_check_guard);
 107 }
 108
 109 /*---------------------------------------------------------------------------*/
 110
 111 /*
 112  * Each AtkObject must be asssigned a D-Bus path (Reference)
 113  *
 114  * This function provides an integer reference for a new
 115  * AtkObject.
 116  */
 117 static guint
 118 assign_reference(void)
 119 {
 120   reference_counter++;
 121   /* Reference of 0 not allowed as used as direct key in hash table */
 122   if (reference_counter == 0)
 123     reference_counter++;
 124   return reference_counter;
 125 }
 126
 127 /*
 128  * Returns the reference of the object, or 0 if it is not registered.
 129  */
 130 static guint
 131 object_to_ref (AtkObject *accessible)
 132 {
 133   return GPOINTER_TO_INT(g_object_get_data (G_OBJECT (accessible), "dbus-id"));
 134 }
 135
 136 /*
 137  * Converts the Accessible object reference to its D-Bus object path
 138  */
 139 gchar *
 140 atk_dbus_ref_to_path (guint ref)
 141 {
 142   return g_strdup_printf(SPI_ATK_OBJECT_REFERENCE_TEMPLATE, ref);
 143 }
 144
 145 /*---------------------------------------------------------------------------*/
 146
 147 /*
 148  * Callback for when a registered AtkObject is destroyed.
 149  *
 150  * Removes the AtkObject from the reference lookup tables, meaning
 151  * it is no longer exposed over D-Bus.
 152  */
 153 static void
 154 deregister_accessible (gpointer data, GObject *accessible)
 155 {
 156   guint ref;
 157   g_return_if_fail (ATK_IS_OBJECT (accessible));
 158
 159   ref = object_to_ref (ATK_OBJECT(accessible));
 160   if (ref != 0)
 161     {
 162       spi_emit_cache_removal (ref, atk_adaptor_app_data->bus);
 163       g_hash_table_remove(ref2ptr, GINT_TO_POINTER(ref));
 164     }
 165 }
 166
 167 /*
 168  * Called to register an AtkObject with AT-SPI and expose it over D-Bus.
 169  */
 170 static void
 171 register_accessible (AtkObject *accessible)
 172 {
 173   guint ref;
 174   g_return_if_fail (ATK_IS_OBJECT(accessible));
 175
 176   ref = assign_reference();
 177
 178   g_hash_table_insert (ref2ptr, GINT_TO_POINTER(ref), accessible);
 179   g_object_set_data (G_OBJECT(accessible), "dbus-id", GINT_TO_POINTER(ref));
 180   g_object_weak_ref(G_OBJECT(accessible), deregister_accessible, NULL);
 181 }
 182
 183 /*---------------------------------------------------------------------------*/
 184
 185 #ifdef SPI_ATK_DEBUG
 186 /*
 187  * This function checks that the ref-count of an accessible
 188  * is greater than 1.
 189  *
 190  * There is not currently any remote reference counting
 191  * in AT-SPI D-Bus so objects that are remotely owned are not
 192  * allowed.
 193  *
 194  * TODO Add debug wrapper
 195  */
 196 static gboolean
 197 non_owned_accessible (AtkObject *accessible)
 198 {
 199    if ((G_OBJECT (accessible))->ref_count <= 1)
 200      {
 201        g_warning ("AT-SPI: Child referenced that is not owned by its parent");
 202        return TRUE;
 203      }
 204    else
 205      {
 206        return FALSE;
 207      }
 208 }
 209 #endif /* SPI_ATK_DEBUG */
 210
 211 /*---------------------------------------------------------------------------*/
 212
 213 static gboolean
 214 has_manages_descendants (AtkObject *accessible)
 215 {
 216    AtkStateSet *state;
 217    gboolean result = FALSE;
 218
 219    /* This is dangerous, refing the state set
 220     * seems to do wierd things to the tree & cause recursion
 221     * by modifying the tree alot.
 222     */
 223    state = atk_object_ref_state_set (accessible);
 224    if (atk_state_set_contains_state (state, ATK_STATE_MANAGES_DESCENDANTS))
 225      {
 226 #ifdef SPI_ATK_DEBUG
 227        g_warning ("AT-SPI: Object with 'Manages descendants' states not currently handled by AT-SPI");
 228 #endif
 229        result = TRUE;
 230      }
 231    g_object_unref (state);
 232
 233    return result;
 234 }
 235
 236 static void
 237 append_children (AtkObject *accessible, GQueue *traversal)
 238 {
 239   AtkObject *current;
 240   guint i;
 241   gint count = atk_object_get_n_accessible_children (accessible);
 242
 243   if (count < 0) count = 0;
 244   for (i =0; i < count; i++)
 245     {
 246       current = atk_object_ref_accessible_child (accessible, i);
 247       if (current)
 248         {
 249 #ifdef SPI_ATK_DEBUG
 250           non_owned_accessible (current);
 251 #endif
 252           if (!has_manages_descendants (current))
 253               g_queue_push_tail (traversal, current);
 254           else
 255               g_object_unref (G_OBJECT (current));
 256         }
 257     }
 258 }
 259
 260 /*
 261  * Registers a subtree of accessible objects
 262  * rooted at the accessible object provided.
 263  *
 264  * The leaf nodes do not have their children
 265  * registered. A node is considered a leaf
 266  * if it has the state "manages-descendants"
 267  * or if it has already been registered.
 268  */
 269 void
 270 register_subtree (AtkObject *accessible)
 271 {
 272   AtkObject *current;
 273   GQueue    *traversal;
 274   GQueue    *emit_update;
 275
 276   g_return_if_fail (ATK_IS_OBJECT (accessible));
 277
 278   traversal = g_queue_new ();
 279   emit_update = g_queue_new ();
 280
 281   g_object_ref (accessible);
 282   g_queue_push_tail (traversal, accessible);
 283
 284   while (!g_queue_is_empty (traversal))
 285     {
 286       current = g_queue_pop_head (traversal);
 287       g_queue_push_tail (emit_update, current);
 288       if (!object_to_ref (current))
 289         {
 290           register_accessible (current);
 291 #ifdef SPI_ATK_DEBUG
 292           g_debug ("REG  - %s - %d - %s", atk_object_get_name     (current),
 293                                           atk_object_get_role     (current),
 294                                           atk_dbus_object_to_path (current));
 295 #endif
 296           append_children (current, traversal);
 297         }
 298     }
 299
 300   while (!g_queue_is_empty (emit_update))
 301     {
 302       current = g_queue_pop_head (emit_update);
 303       spi_emit_cache_update (current, atk_adaptor_app_data->bus);
 304       g_object_unref (G_OBJECT (current));
 305     }
 306
 307   g_queue_free (traversal);
 308   g_queue_free (emit_update);
 309 }
 310
 311 /*---------------------------------------------------------------------------*/
 312
 313 /*
 314  * Called when an already registered object is updated in such a
 315  * way that client side cache needs to be updated.
 316  */
 317 static void
 318 update_accessible (AtkObject *accessible)
 319 {
 320   guint  ref = 0;
 321   g_return_if_fail (ATK_IS_OBJECT(accessible));
 322
 323   ref = object_to_ref (accessible);
 324   if (ref)
 325     {
 326       spi_emit_cache_update (accessible, atk_adaptor_app_data->bus);
 327     }
 328 }
 329
 330 /*---------------------------------------------------------------------------*/
 331
 332 void
 333 atk_dbus_foreach_registered(GHFunc func, gpointer data)
 334 {
 335   g_hash_table_foreach(ref2ptr, func, data);
 336 }
 337
 338 /*
 339  * Used to lookup an AtkObject from its D-Bus path.
 340  */
 341 AtkObject *
 342 atk_dbus_path_to_object (const char *path)
 343 {
 344   guint index;
 345   void *data;
 346
 347   g_return_val_if_fail (path, NULL);
 348
 349   if (strncmp(path, SPI_ATK_OBJECT_PATH_PREFIX, SPI_ATK_PATH_PREFIX_LENGTH) != 0)
 350     return NULL;
 351
 352   path += SPI_ATK_PATH_PREFIX_LENGTH; /* Skip over the prefix */
 353
 354   if (!g_strcmp0 (SPI_ATK_OBJECT_PATH_DESKTOP, path))
 355      return atk_get_root();
 356   if (path[0] != '/')
 357      return NULL;
 358
 359   path++;
 360   index = atoi (path);
 361   data = g_hash_table_lookup (ref2ptr, GINT_TO_POINTER(index));
 362   if (data)
 363     return ATK_OBJECT (data);
 364   else
 365     return NULL;
 366 }
 367
 368 /*
 369  * TODO WARNING HACK This function is dangerous.
 370  * It should only be called before sending an event on an
 371  * object that has not already been registered.
 372  */
 373 gchar *
 374 atk_dbus_object_attempt_registration (AtkObject *accessible)
 375 {
 376   guint ref;
 377
 378   ref = object_to_ref (accessible);
 379   if (!ref)
 380     {
 381       /* See if the object is attached to the main tree */
 382       AtkObject *current, *prev = NULL;
 383       guint cref = 0;
 384
 385       /* This should iterate until it hits a NULL or registered parent */
 386       prev = accessible;
 387       current = atk_object_get_parent (accessible);
 388       if (current)
 389           cref = object_to_ref (current);
 390       while (current && !cref)
 391         {
 392           prev = current;
 393           current = atk_object_get_parent (current);
 394           if (current)
 395               cref = object_to_ref (current);
 396         }
 397
 398       /* A registered parent, with non-registered child, has been found */
 399       if (current)
 400         {
 401           register_subtree (prev);
 402         }
 403
 404       /* The object SHOULD be registered now. If it isn't - I give up */
 405       ref = object_to_ref (accessible);
 406       if (ref)
 407         {
 408           return atk_dbus_ref_to_path (ref);
 409         }
 410       else
 411         {
 412 #ifdef SPI_ATK_DEBUG
 413           g_debug ("AT-SPI: Could not register a non-attached accessible object");
 414 #endif
 415           return NULL;
 416         }
 417     }
 418   else
 419     {
 420       return atk_dbus_ref_to_path (ref);
 421     }
 422 }
 423
 424
 425 /*
 426  * Used to lookup a D-Bus path from the AtkObject.
 427  */
 428 gchar *
 429 atk_dbus_object_to_path (AtkObject *accessible)
 430 {
 431   guint ref;
 432
 433   ref = object_to_ref (accessible);
 434   if (!ref)
 435       return NULL;
 436   else
 437       return atk_dbus_ref_to_path (ref);
 438 }
 439
 440 gchar *
 441 atk_dbus_desktop_object_path ()
 442 {
 443   return g_strdup (SPI_ATK_OBJECT_PATH_PREFIX SPI_ATK_OBJECT_PATH_DESKTOP);
 444 }
 445
 446 /*---------------------------------------------------------------------------*/
 447
 448 typedef gboolean (*TreeUpdateAction) (GSignalInvocationHint *signal_hint,
 449                                       guint                  n_param_values,
 450                                       const GValue          *param_values,
 451                                       gpointer               data,
 452                                       AtkObject             *accessible);
 453
 454 /*
 455  * Events are not evaluated for non-registered accessibles.
 456  *
 457  * When a property change is made on a registered accessible
 458  * the client side cache should be updated.
 459  *
 460  * When a parent is changed the subtree is de-registered
 461  * if the parent is not attached to the root accessible.
 462  */
 463 /* TODO Turn this function into a macro? */
 464 static gboolean
 465 tree_update_wrapper (GSignalInvocationHint *signal_hint,
 466                      guint                  n_param_values,
 467                      const GValue          *param_values,
 468                      gpointer               data,
 469                      TreeUpdateAction       action)
 470 {
 471   AtkObject *accessible;
 472
 473   g_static_rec_mutex_lock (&registration_mutex);
 474
 475   /* Ensure that only registered accessibles
 476    * have their signals processed.
 477    */
 478   accessible = ATK_OBJECT(g_value_get_object (&param_values[0]));
 479   g_return_val_if_fail (ATK_IS_OBJECT (accessible), TRUE);
 480
 481   if (object_to_ref (accessible))
 482     {
 483 #ifdef SPI_ATK_DEBUG
 484       if (recursion_check_and_set ())
 485           g_warning ("AT-SPI: Recursive use of registration module");
 486
 487       g_debug ("AT-SPI: Tree update listener");
 488 #endif
 489       action (signal_hint, n_param_values, param_values, data, accessible);
 490
 491       recursion_check_unset ();
 492     }
 493
 494   g_static_rec_mutex_unlock (&registration_mutex);
 495
 496   return TRUE;
 497 }
 498
 499 static gboolean
 500 tree_update_state_action (GSignalInvocationHint *signal_hint,
 501                           guint                  n_param_values,
 502                           const GValue          *param_values,
 503                           gpointer               data,
 504                           AtkObject             *accessible)
 505 {
 506       update_accessible (accessible);
 507   return TRUE;
 508 }
 509
 510 static gboolean
 511 tree_update_state_listener (GSignalInvocationHint *signal_hint,
 512                             guint                  n_param_values,
 513                             const GValue          *param_values,
 514                             gpointer               data)
 515 {
 516       tree_update_wrapper (signal_hint, n_param_values, param_values, data, tree_update_state_action);
 517   return TRUE;
 518 }
 519
 520 static gboolean
 521 tree_update_property_action (GSignalInvocationHint *signal_hint,
 522                              guint                  n_param_values,
 523                              const GValue          *param_values,
 524                              gpointer               data,
 525                              AtkObject             *accessible)
 526 {
 527       AtkPropertyValues *values;
 528       const gchar *pname = NULL;
 529
 530       values = (AtkPropertyValues*) g_value_get_pointer (&param_values[1]);
 531       pname = values[0].property_name;
 532       if (strcmp (pname, "accessible-name") == 0 ||
 533           strcmp (pname, "accessible-description") == 0 ||
 534           strcmp (pname, "accessible-parent") == 0)
 535         {
 536           update_accessible (accessible);
 537         }
 538       /* Parent value us updated by child-add signal of parent object */
 539       return TRUE;
 540 }
 541
 542 static gboolean
 543 tree_update_property_listener (GSignalInvocationHint *signal_hint,
 544                                guint                  n_param_values,
 545                                const GValue          *param_values,
 546                                gpointer               data)
 547 {
 548   tree_update_wrapper (signal_hint, n_param_values, param_values, data, tree_update_property_action);
 549   return TRUE;
 550 }
 551
 552 static gboolean
 553 tree_update_children_action (GSignalInvocationHint *signal_hint,
 554                              guint                  n_param_values,
 555                              const GValue          *param_values,
 556                              gpointer               data,
 557                              AtkObject             *accessible)
 558 {
 559       const gchar *detail = NULL;
 560       AtkObject *child;
 561
 562       if (has_manages_descendants (accessible)) return TRUE;
 563       if (signal_hint->detail)
 564           detail = g_quark_to_string (signal_hint->detail);
 565
 566       if (!strcmp (detail, "add"))
 567         {
 568           gpointer child;
 569           int index = g_value_get_uint (param_values + 1);
 570           child = g_value_get_pointer (param_values + 2);
 571
 572           if (!ATK_IS_OBJECT (child))
 573             {
 574               child = atk_object_ref_accessible_child (accessible, index);
 575 #ifdef SPI_ATK_DEBUG
 576               non_owned_accessible (child);
 577 #endif
 578             }
 579           register_subtree (child);
 580           update_accessible (accessible);
 581         }
 582       return TRUE;
 583 }
 584
 585 static gboolean
 586 tree_update_children_listener (GSignalInvocationHint *signal_hint,
 587                                guint                  n_param_values,
 588                                const GValue          *param_values,
 589                                gpointer               data)
 590 {
 591       tree_update_wrapper (signal_hint, n_param_values, param_values, data, tree_update_children_action);
 592       return TRUE;
 593 }
 594
 595 /*---------------------------------------------------------------------------*/
 596
 597 static void
 598 spi_atk_register_toplevel_added (AtkObject *accessible,
 599                                  guint     index,
 600                                  AtkObject *child)
 601 {
 602   g_static_rec_mutex_lock (&registration_mutex);
 603
 604   g_return_if_fail (ATK_IS_OBJECT (accessible));
 605
 606   if (object_to_ref (accessible))
 607     {
 608 #ifdef SPI_ATK_DEBUG
 609       if (recursion_check_and_set ())
 610           g_warning ("AT-SPI: Recursive use of registration module");
 611
 612       g_debug ("AT-SPI: Toplevel added listener");
 613 #endif
 614       if (!ATK_IS_OBJECT (child))
 615         {
 616           child = atk_object_ref_accessible_child (accessible, index);
 617 #ifdef SPI_ATK_DEBUG
 618           non_owned_accessible (child);
 619 #endif
 620         }
 621       register_subtree (child);
 622       update_accessible (accessible);
 623
 624       recursion_check_unset ();
 625     }
 626
 627   g_static_rec_mutex_unlock (&registration_mutex);
 628 }
 629
 630 static void
 631 spi_atk_register_toplevel_removed (AtkObject *accessible,
 632                                    guint     index,
 633                                    AtkObject *child)
 634 {
 635   g_static_rec_mutex_lock (&registration_mutex);
 636
 637   g_return_if_fail (ATK_IS_OBJECT (accessible));
 638
 639   if (object_to_ref (accessible))
 640     {
 641 #ifdef SPI_ATK_DEBUG
 642       if (recursion_check_and_set ())
 643           g_warning ("AT-SPI: Recursive use of registration module");
 644
 645       g_debug ("AT-SPI: Toplevel removed listener");
 646 #endif
 647       update_accessible (accessible);
 648       recursion_check_unset ();
 649     }
 650
 651   g_static_rec_mutex_unlock (&registration_mutex);
 652 }
 653
 654 /*
 655  * Initializes required global data. The update and removal lists
 656  * and the reference lookup tables.
 657  *
 658  * Initializes all of the required D-Bus interfaces.
 659  */
 660 void
 661 atk_dbus_initialize (AtkObject *root)
 662 {
 663   if (!ref2ptr)
 664     ref2ptr = g_hash_table_new(g_direct_hash, g_direct_equal);
 665
 666 #ifdef SPI_ATK_DEBUG
 667   if (g_thread_supported ())
 668       g_message ("AT-SPI: Threads enabled");
 669
 670   g_debug ("AT-SPI: Initial Atk tree regisration");
 671 #endif
 672
 673   register_subtree (root);
 674
 675   atk_add_global_event_listener (tree_update_property_listener, "Gtk:AtkObject:property-change");
 676   atk_add_global_event_listener (tree_update_children_listener, "Gtk:AtkObject:children-changed");
 677   atk_add_global_event_listener (tree_update_state_listener, "Gtk:AtkObject:state-change");
 678
 679   g_signal_connect (root,
 680                     "children-changed::add",
 681                     (GCallback) spi_atk_register_toplevel_added,
 682                     NULL);
 683   g_signal_connect (root,
 684                     "children-changed::remove",
 685                     (GCallback) spi_atk_register_toplevel_removed,
 686                     NULL);
 687 }
 688
 689 /*END------------------------------------------------------------------------*/