2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2001, 2002 Sun Microsystems Inc.,
6 * Copyright 2001, 2002 Ximian, Inc.
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.
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.
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.
26 * Basic SPI initialization and event loop function prototypes
33 #include <cspi/spi-private.h>
38 static CORBA_Environment ev = { NULL };
39 static Accessibility_Registry registry = CORBA_OBJECT_NIL;
40 static GHashTable *live_refs = NULL;
41 static GQueue *exception_handlers = NULL;
44 cspi_object_hash (gconstpointer key)
46 CORBA_Object object = (CORBA_Object) key;
48 return CORBA_Object_hash (object, 0, &ev);
52 cspi_object_equal (gconstpointer a, gconstpointer b)
54 CORBA_Object objecta = (CORBA_Object) a;
55 CORBA_Object objectb = (CORBA_Object) b;
57 return CORBA_Object_is_equivalent (objecta, objectb, cspi_ev ());
61 cspi_object_release (gpointer value)
63 Accessible *a = (Accessible *) value;
66 g_print ("releasing %p => %p\n", a, a->objref);
71 cspi_release_unref (a->objref);
74 memset (a, 0xaa, sizeof (Accessible));
83 cspi_exception_throw (CORBA_Environment *ev, char *desc_prefix)
85 SPIExceptionHandler *handler = NULL;
87 if (exception_handlers) handler = g_queue_peek_head (exception_handlers);
89 ex.type = SPI_EXCEPTION_SOURCE_UNSPECIFIED;
90 ex.source = CORBA_OBJECT_NIL; /* can we get this from here? */
91 ex.ev = CORBA_exception__copy (ev);
93 case CORBA_SYSTEM_EXCEPTION:
94 ex.code = SPI_EXCEPTION_UNSPECIFIED;
96 case CORBA_USER_EXCEPTION: /* help! how to interpret this? */
97 ex.code = SPI_EXCEPTION_UNSPECIFIED;
100 ex.code = SPI_EXCEPTION_UNSPECIFIED;
105 return (*handler) (&ex, FALSE);
107 return FALSE; /* means exception was not handled */
111 cspi_accessible_is_a (Accessible *accessible,
112 const char *interface_name)
115 Bonobo_Unknown unknown;
117 if (accessible == NULL)
122 unknown = Bonobo_Unknown_queryInterface (CSPI_OBJREF (accessible),
123 interface_name, cspi_ev ());
125 if (ev._major != CORBA_NO_EXCEPTION)
127 g_warning ("Exception '%s' checking if is '%s'",
128 cspi_exception_get_text (),
133 else if (unknown != CORBA_OBJECT_NIL)
136 cspi_release_unref (unknown);
147 cspi_get_live_refs (void)
151 live_refs = g_hash_table_new_full (cspi_object_hash,
154 cspi_object_release);
168 CORBA_exception_init (&ev);
172 Accessibility_Registry
175 if (!cspi_ping (registry))
177 registry = cspi_init ();
183 cspi_exception (void)
187 if (ev._major != CORBA_NO_EXCEPTION)
189 CORBA_exception_free (&ev);
201 * This method swallows the corba_object BonoboUnknown
202 * reference, and returns an Accessible associated with it.
203 * If the reference is loaned, it means it is only valid
204 * between a borrow / return pair.
207 cspi_object_get_ref (CORBA_Object corba_object, gboolean on_loan)
211 if (corba_object == CORBA_OBJECT_NIL)
215 else if (!cspi_check_ev ("pre method check: add"))
221 if ((ref = g_hash_table_lookup (cspi_get_live_refs (), corba_object)))
223 g_assert (ref->ref_count > 0);
227 if (ref->on_loan) /* Convert to a permanant ref */
229 ref->on_loan = FALSE;
233 cspi_release_unref (corba_object);
237 g_print ("returning cached %p => %p\n", ref, ref->objref);
242 ref = malloc (sizeof (Accessible));
243 ref->objref = corba_object;
245 ref->on_loan = on_loan;
247 g_print ("allocated %p => %p\n", ref, corba_object);
249 g_hash_table_insert (cspi_get_live_refs (), ref->objref, ref);
257 cspi_object_add (CORBA_Object corba_object)
259 return cspi_object_get_ref (corba_object, FALSE);
263 cspi_object_borrow (CORBA_Object corba_object)
265 return cspi_object_get_ref (corba_object, TRUE);
269 cspi_object_return (Accessible *accessible)
272 g_return_if_fail (accessible != NULL);
274 if (!accessible->on_loan ||
275 accessible->ref_count == 1)
277 cspi_object_unref (accessible);
279 else /* Convert to a permanant ref */
281 accessible->on_loan = FALSE;
282 old_ref_count = accessible->ref_count;
283 accessible->objref = cspi_dup_ref (accessible->objref);
284 if (old_ref_count != accessible->ref_count &&
285 accessible->ref_count == 1)
287 cspi_object_unref (accessible);
291 accessible->ref_count--;
297 cspi_object_take (CORBA_Object corba_object)
299 Accessible *accessible;
300 accessible = cspi_object_borrow (corba_object);
302 cspi_object_ref (accessible);
304 * if the remote object is dead,
305 * cspi_object_return will throw an exception.
306 * FIXME: what clears that exception context ever ?
308 cspi_object_return (accessible);
309 if (cspi_exception ())
311 cspi_object_unref (accessible);
318 cspi_object_ref (Accessible *accessible)
320 g_return_if_fail (accessible != NULL);
322 accessible->ref_count++;
326 cspi_object_unref (Accessible *accessible)
328 if (accessible == NULL)
333 g_return_if_fail (accessible->ref_count > 0);
334 if (--accessible->ref_count == 0)
336 g_hash_table_remove (cspi_get_live_refs (), accessible->objref);
345 cspi_streams_close_all ();
351 g_hash_table_destroy (refs);
354 if (registry != CORBA_OBJECT_NIL)
356 cspi_release_unref (registry);
357 registry = CORBA_OBJECT_NIL;
361 static gboolean SPI_inited = FALSE;
366 * Connects to the accessibility registry and initializes the SPI.
368 * Returns: 0 on success, otherwise an integer error code.
380 CORBA_exception_init (&ev);
382 registry = cspi_init ();
384 g_atexit (cspi_cleanup);
386 /* fprintf (stderr, "registry=%x\n", (int) registry); */
388 if ((registry != CORBA_OBJECT_NIL) && (cspi_ping (registry)))
397 * Starts/enters the main event loop for the SPI services.
399 * (NOTE: This method does not return control, it is exited via a call to
400 * SPI_event_quit () from within an event handler).
404 SPI_event_main (void)
412 * Quits the last main event loop for the SPI services,
416 SPI_event_quit (void)
424 * Checks to see if an SPI event is waiting in the event queue.
425 * Used by clients that don't wish to use SPI_event_main().
427 * Not Yet Implemented.
429 * Returns: #TRUE if an event is waiting, otherwise #FALSE.
433 SPI_eventIsReady (void)
440 * @waitForEvent: a #SPIBoolean indicating whether to block or not.
442 * Gets the next event in the SPI event queue; blocks if no event
443 * is pending and @waitForEvent is #TRUE.
444 * Used by clients that don't wish to use SPI_event_main().
446 * Not Yet Implemented.
448 * Returns: the next #AccessibleEvent in the SPI event queue.
451 SPI_nextEvent (SPIBoolean waitForEvent)
458 report_leaked_ref (gpointer key, gpointer val, gpointer user_data)
461 Accessible *a = (Accessible *) val;
463 name = Accessible_getName (a);
464 if (cspi_exception ())
469 role = Accessible_getRoleName (a);
470 if (cspi_exception ())
475 fprintf (stderr, "leaked %d references to object %s, role %s %p\n",
476 a->ref_count, name ? name : "<?>", role ? role : "<?>", a);
478 SPI_freeString (name);
485 * Disconnects from the Accessibility Registry and releases
486 * any floating resources. Call only once at exit.
488 * Returns: 0 if there were no leaks, otherwise non zero.
504 leaked = g_hash_table_size (live_refs);
506 fprintf (stderr, "Leaked %d SPI handles\n", leaked);
510 g_hash_table_foreach (live_refs, report_leaked_ref, NULL);
527 * @s: a character string returned from another at-spi call.
529 * Free a character string returned from an at-spi call. Clients of
530 * at-spi should use this function instead of free () or g_free().
531 * A NULL string @s will be silently ignored.
532 * This API should not be used to free strings
533 * from other libraries or allocated by the client.
536 SPI_freeString (char *s)
546 * @r: a pointer to an SPIRect returned from another at-spi call.
548 * Free a SPIRect structure returned from an at-spi call. Clients of
549 * at-spi should use this function instead of free () or g_free().
550 * A NULL rect @r will be silently ignored.
551 * This API should not be used to free data
552 * from other libraries or allocated by the client.
557 SPI_freeRect (SPIRect *r)
561 /* err, okay, in this case the client _could_
562 have called g_free, but we don't want to guarantee it */
569 * @s: a UTF-8 string to be duplicated
573 * Returns: a duplicate of the string passed as a parameter, which should
574 * be freed via SPI_freeString after use.
577 SPI_dupString (char *s)
581 return CORBA_string_dup (s);
588 * SPI_exceptionHandlerPush:
589 * @handler: an #SPIExceptionHandler to install as the first code to deal with exceptions.
591 * Install a client-side handler for #SPIException instances, which can see and handle any
592 * exceptions before chaining them to the next exception handler in the stack.
596 * Returns %TRUE if the result succeeded, %FALSE if @hander could not be registered.
598 SPIBoolean SPI_exceptionHandlerPush (SPIExceptionHandler *handler)
600 if (!exception_handlers)
601 exception_handlers = g_queue_new ();
602 g_queue_push_head (exception_handlers, handler);
607 * SPI_exceptionHandlerPop:
609 * Remove/pop an #SPIExceptionHandler off the error handler stack and return the new handler.
613 * Returns the #SPIExceptionHandler which is now at the top of the error handler stack after the call.
615 SPIExceptionHandler* SPI_exceptionHandlerPop (void)
617 return (SPIExceptionHandler *) g_queue_pop_head (exception_handlers);
621 * SPIException_getSourceType:
622 * @err: the exception being queried
624 * Get the #SPIExceptionType of an exception which has been thrown.
628 * Returns: the #SPIExceptionType corresponding to exception @err.
630 SPIExceptionType SPIException_getSourceType (SPIException *err)
635 return SPI_EXCEPTION_SOURCE_UNSPECIFIED;
639 * SPIException_getExceptionCode:
640 * @err: the #SPIException being queried.
642 * Get the #SPIExceptionCode telling what type of exception condition has occurred.
646 * Returns: the #SPIExceptionCode corresponding to exception @err.
648 SPIExceptionCode SPIException_getExceptionCode (SPIException *err)
654 * SPIAccessibleException_getSource:
655 * @err: the #SPIException being queried.
657 * Get the identity of the object which threw an exception.
661 * Returns: a pointer to the #Accessible object which threw the exception.
663 Accessible* SPIAccessibleException_getSource (SPIException *err)
665 if (err->type == SPI_EXCEPTION_SOURCE_ACCESSIBLE)
666 return cspi_object_get_ref (err->source, FALSE);
671 * SPIException_getDescription:
672 * @err: the #SPIException being queried.
674 * Get a text description of the exception that has been thrown.
675 * Unfortunately these descriptions tend to be terse and limited in
676 * the detail which they can provide.
678 * Returns: a brief character string describing the exception.
680 char* SPIException_getDescription (SPIException *err)
682 /* TODO: friendlier error messages? */
684 return CORBA_exception_id (err->ev);