atk-adaptor/atk-dbus.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  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include <stdio.h>
  24 #include <stdlib.h>
  25 #include <string.h>
  26
  27 #include "bridge.h"
  28 #include "accessible.h"
  29 #include "atk-dbus.h"
  30
  31 /* TODO
  32  * Need to add concurrency support.
  33  */
  34
  35 #define ATK_BRIDGE_OBJECT_PATH_PREFIX "/org/freedesktop/atspi/accessible"
  36 #define ATK_BRIDGE_OBJECT_REFERENCE_TEMPLATE ATK_BRIDGE_OBJECT_PATH_PREFIX "/%d"
  37 #define ATK_BRIDGE_PATH_PREFIX_LENGTH 33
  38
  39 /*
  40  * This module is responsible for keeping track of all the AtkObjects in
  41  * the application, so that they can be accessed remotely and placed in
  42  * a client side cache.
  43  *
  44  * To access an AtkObject remotely we need to provide a D-Bus object
  45  * path for it. The D-Bus object paths used have a standard prefix
  46  * (ATK_BRIDGE_OBJECT_PATH_PREFIX). Appended to this prefix is a string
  47  * representation of an integer reference. So to access an AtkObject
  48  * remotely we keep a Hashtable that maps the given reference to
  49  * the AtkObject pointer. An object in this hash table is said to be 'registered'.
  50  *
  51  * The architecture of AT-SPI dbus is such that AtkObjects are not
  52  * remotely reference counted. This means that we need to keep track of
  53  * object destruction. When an object is destroyed it must be 'deregistered'
  54  * To do this lookup we keep a dbus-id attribute on each AtkObject.
  55  *
  56  * In addition to accessing the objects remotely we must be able to update
  57  * the client side cache. This is done using the 'update' signal of the
  58  * org.freedesktop.atspi.Tree interface. The update signal should send out
  59  * all of the cacheable data for each AtkObject that has changed since the
  60  * last update. It should also provide a list of objects that have been
  61  * removed since the last update.
  62  */
  63
  64 /* Amazingly the ATK event callbacks dont have a user
  65  * data parameter. Instead, with great sadness, we use
  66  * some global data. Data is declared and initialized
  67  * in bridge.c.
  68  */
  69
  70 GHashTable *ref2ptr = NULL; /* Used for converting a D-Bus path (Reference) to the object pointer */
  71
  72 static guint counter = 1;
  73
  74 extern SpiAppData *atk_adaptor_app_data;
  75
  76 /*---------------------------------------------------------------------------*/
  77
  78 /*
  79  * Each AtkObject must be asssigned a D-Bus path (Reference)
  80  *
  81  * This function provides an integer reference for a new
  82  * AtkObject.
  83  */
  84 static guint
  85 assign_reference(void)
  86 {
  87   counter++;
  88   /* Reference of 0 not allowed as used as direct key in hash table */
  89   if (counter == 0)
  90     counter++;
  91 }
  92
  93 /*---------------------------------------------------------------------------*/
  94
  95 void
  96 atk_dbus_foreach_registered(GHFunc func, gpointer data)
  97 {
  98   g_hash_table_foreach(ref2ptr, func, data);
  99 }
 100
 101 /*---------------------------------------------------------------------------*/
 102
 103 /*
 104  * Called when a registered AtkObject is deleted.
 105  * Removes the AtkObject from the reference lookup tables.
 106  * Sets the client side cache to be updated.
 107  */
 108 static void
 109 deregister_accessible(gpointer data, GObject *accessible)
 110 {
 111   guint ref;
 112   gchar *path;
 113
 114   g_assert(ATK_IS_OBJECT(accessible));
 115
 116
 117   ref = atk_dbus_object_to_ref (ATK_OBJECT(accessible));
 118
 119   if (ref != 0)
 120     {
 121       g_hash_table_remove(ref2ptr, GINT_TO_POINTER(ref));
 122       /*
 123        * TODO
 124        * Pyatspi client side exceptions have occured indicating
 125        * that an object has been removed twice.
 126        * This should not be possible and needs investigation.
 127        */
 128       spi_emit_cache_removal (ref, atk_adaptor_app_data->bus);
 129     }
 130 }
 131
 132 /*---------------------------------------------------------------------------*/
 133
 134 /*
 135  * This function registers the object so that it is exported
 136  * over D-Bus and schedules an update to client side cache.
 137  */
 138 static guint
 139 export (GList **uplist, AtkObject *accessible)
 140 {
 141   guint ref;
 142   gchar *path;
 143
 144   g_assert(ATK_IS_OBJECT(accessible));
 145
 146   ref = assign_reference();
 147
 148   g_hash_table_insert (ref2ptr, GINT_TO_POINTER(ref), accessible);
 149   g_object_set_data (G_OBJECT(accessible), "dbus-id", GINT_TO_POINTER(ref));
 150   g_object_weak_ref(G_OBJECT(accessible), deregister_accessible, NULL);
 151
 152   *uplist = g_list_prepend (*uplist, accessible);
 153
 154   return ref;
 155 }
 156
 157 /*
 158  * This does a depth first traversal of a subtree of AtkObject
 159  * and exports them as Accessible objects if they are not exported
 160  * already.
 161  */
 162 static guint
 163 export_subtree (AtkObject *accessible)
 164 {
 165   AtkObject *current, *tmp;
 166   GQueue    *stack;
 167   GList     *uplist = NULL;
 168   guint      i, ref;
 169   gboolean   recurse;
 170
 171   stack = g_queue_new ();
 172
 173   current = g_object_ref (accessible);
 174   ref = export (&uplist, current);
 175   g_queue_push_head (stack, GINT_TO_POINTER (0));
 176
 177   /*
 178    * The index held on the stack is the next child node
 179    * that needs processing at the corresponding level in the tree.
 180    */
 181   while (!g_queue_is_empty (stack))
 182     {
 183       /* This while loop finds the next node that needs processing,
 184        * if one exists.
 185        */
 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 (!atk_dbus_object_to_ref (tmp))
 193             {
 194               recurse = TRUE;
 195             }
 196           else
 197             {
 198               i++;
 199               g_object_unref (G_OBJECT (tmp));
 200             }
 201         }
 202       if (recurse)
 203         {
 204           /* Still children to process */
 205           current = tmp;
 206           export (&uplist, current);
 207           /* Update parent nodes next child index */
 208           g_queue_peek_head_link (stack)->data = GINT_TO_POINTER (i+1);
 209           /* Push a new child index for the current node */
 210           g_queue_push_head (stack, GINT_TO_POINTER (0));
 211         }
 212       else
 213         {
 214           /* No more children, move to parent */
 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   spi_emit_cache_update (uplist, atk_adaptor_app_data->bus);
 222   g_list_free (uplist);
 223   return ref;
 224 }
 225
 226 /*---------------------------------------------------------------------------*/
 227
 228 /* Called to register an AtkObject with AT-SPI and expose it over D-Bus. */
 229 guint
 230 atk_dbus_register_accessible (AtkObject *accessible)
 231 {
 232   guint ref;
 233   g_assert(ATK_IS_OBJECT(accessible));
 234
 235   ref = atk_dbus_object_to_ref (accessible);
 236   if (!ref)
 237       return export_subtree (accessible);
 238   else
 239       return ref;
 240 }
 241
 242 /* Called when an already registered object is updated in such a
 243  * way that client side cache needs to be updated.
 244  */
 245 guint
 246 atk_dbus_update_accessible (AtkObject *accessible)
 247 {
 248   guint ref = 0;
 249   g_assert(ATK_IS_OBJECT(accessible));
 250
 251   ref = atk_dbus_object_to_ref (accessible);
 252   if (ref)
 253     {
 254       spi_emit_cache_update (accessible, atk_adaptor_app_data->bus);
 255     }
 256   return ref;
 257 }
 258
 259 /*---------------------------------------------------------------------------*/
 260
 261 /*
 262  * Returns the reference of the object, or 0 if it is not exported over D-Bus.
 263  */
 264 guint
 265 atk_dbus_object_to_ref (AtkObject *accessible)
 266 {
 267   return GPOINTER_TO_INT(g_object_get_data (G_OBJECT (accessible), "dbus-id"));
 268 }
 269
 270 /*
 271  * Converts the Accessible object reference to its D-Bus object path
 272  */
 273 gchar *
 274 atk_dbus_ref_to_path (guint ref)
 275 {
 276   return g_strdup_printf(ATK_BRIDGE_OBJECT_REFERENCE_TEMPLATE, ref);
 277 }
 278
 279 /*
 280  * Used to lookup an AtkObject from its D-Bus path.
 281  */
 282 AtkObject *
 283 atk_dbus_path_to_object (const char *path)
 284 {
 285   guint index;
 286   void *data;
 287
 288   g_assert (path);
 289
 290   if (strncmp(path, ATK_BRIDGE_OBJECT_PATH_PREFIX, ATK_BRIDGE_PATH_PREFIX_LENGTH) != 0)
 291     return NULL;
 292
 293   path += ATK_BRIDGE_PATH_PREFIX_LENGTH; /* Skip over the prefix */
 294
 295   if (path[0] == '\0')
 296      return atk_get_root();
 297   if (path[0] != '/')
 298      return NULL;
 299
 300   path++;
 301   index = atoi (path);
 302   data = g_hash_table_lookup (ref2ptr, GINT_TO_POINTER(index));
 303   if (data)
 304     return ATK_OBJECT (data);
 305   else
 306     return NULL;
 307 }
 308
 309
 310 /*
 311  * Used to lookup a D-Bus path from the AtkObject.
 312  */
 313 gchar *
 314 atk_dbus_object_to_path (AtkObject *accessible)
 315 {
 316   guint ref;
 317   g_assert(ATK_IS_OBJECT(accessible));
 318
 319   ref = atk_dbus_object_to_ref (accessible);
 320   if (!ref)
 321       return NULL;
 322   else
 323       return atk_dbus_ref_to_path (ref);
 324 }
 325
 326 /*---------------------------------------------------------------------------*/
 327
 328 /*
 329  * Marshals a single object into a D-Bus message.
 330  *
 331  * Unrefs the AtkObject if unref is true.
 332  */
 333 DBusMessage *
 334 spi_dbus_return_object (DBusMessage *message, AtkObject *obj, gboolean unref)
 335 {
 336   DBusMessage *reply;
 337   gchar *path;
 338
 339   path = atk_dbus_object_to_path (obj);
 340
 341   if (unref)
 342     g_object_unref (obj);
 343
 344   reply = dbus_message_new_method_return (message);
 345   if (reply)
 346     {
 347       dbus_message_append_args (reply, DBUS_TYPE_OBJECT_PATH, path,
 348                                 DBUS_TYPE_INVALID);
 349     }
 350   return reply;
 351 }
 352
 353 /*---------------------------------------------------------------------------*/
 354
 355 /*
 356  * Marshals a variant containing the object reference into the message iter
 357  * provided.
 358  *
 359  * Unrefs the object if unref is true.
 360  */
 361 dbus_bool_t
 362 spi_dbus_return_v_object (DBusMessageIter *iter, AtkObject *obj, int unref)
 363 {
 364   char *path;
 365
 366   path = atk_dbus_object_to_path (obj);
 367
 368   if (unref)
 369     g_object_unref (obj);
 370
 371   return droute_return_v_object (iter, path);
 372 }
 373
 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   /* Get the root accessible and add */
 389   atk_dbus_register_accessible (root);
 390 }
 391
 392 /*END------------------------------------------------------------------------*/
 393