Re: [g-a-devel] AT-SPI caching and D-Bus usage

[Mike Gorse <mgorse alum wpi edu>]

Hi all,

Here is what I have for API additions right now (still haven't committed 
or fully tested the code). Of course this isn't necessarily final; just 
posting it here should people have feedback on it.

--

/**
 * atspi_event_listener_register_full:
 * @listener: The #AtspiEventListener to register against an event type.
 * @event_type: a character string indicating the type of events for which
 *            notification is requested.  See #atspi_event_listener_register
 * for a description of the format and legal event types.
* @properties: (element-type gchar*) (transfer none) (allow-none): a list of
 *             properties that should be sent along with the event. The
 *             properties are valued for the duration of the event callback.k
 *             TODO: Document.
 *
 * Adds an in-process callback function to an existing #AtspiEventListener.
 *
 * Returns: #TRUE if successful, otherwise #FALSE.
 **/


/**
 * atspi_collection_get_tree:
 * @collection: the #AtspiCollection to query.
 * @properties: (element-type gchar*) (transfer none) (allow-none): The
 * properties to fetch, or %NULL to fetch all supported properties.
 * @rule_start: (allow-none): a match rule specifying the ancestor from which
 * to start, or %NULL to use the object specified in @collection itself.
 * @allow_sync: Specifies whether synchronous calls will be allowed during
 * the execution of @callback. If this is set to %FALSE, then an exception
 * will be thrown if the callback calls an AT-SPI function which would
 * otherwise make a synchronous D-Bus call. Set to %FALSE in cases where a
 * synchrous D-Bus call has the potential to cause deadlock (for instance, if
 * the application needs to be able to respond to non-AT-SPI D-Bus calls from
 * other applications). Otherwise set to %TRUE.
 * @callback: (scope async): The callback to be invoked when data is available.
 * @user_data: Data to pass to @callback.
 *
 * Asynchronously fetches data for an object and all of its descendants.
 * The data is cached for the duration of @callback.
 */