New Listener and EventSource interfaces

[Alex Graveley <alex helixcode com>]

Hi,

Just thought I'd present a small description and example usage of the
new Listener and EventSource interfaces...

Files:
=====

idl/Listener.idl - IDL for Listener and EventSource interfaces.
bonobo/bonobo-event-source.c - EventSource implementation
bonobo/bonobo-listener.c - Listener implementation


Quick Intro:
===========

Events are composed of a string event name and a CORBA Any data
argument. This data argument is meant to hold arbitrary information
related to the event.

The Listener interface is meant as generic event reciever. When
recieving an event the default implementation will invoke a callback
(optionally passed at construction time) and emit an "event_notify"
signal. 

The constructor and event callback should conform to the following
signature:

typedef void (*BonoboListenerCallbackFn) (BonoboListener    *listener,
                                          char              *event_name, 
                                          CORBA_any         *any,
                                          CORBA_Environment *ev,
                                          gpointer           user_data);

The EventSource interface is meant as a simple implementation of an
event emitter; Listener objects can be attached to it in order to
receive an event. It uses server-side filtering to ensure Listeners
recieve only the events they are interested in. 

To subscribe a listener to all events emitted by an EventSource, call
Bonobo_EventSource_addListener(), passing the listener you wish to add. 

To recieve only certain events, call 
Bonobo_EventSource_addListenerWithMask(), passing in the Listener you
wish to add, and a comma separated string of event names you are
interested in recieving.

Calling addListener*() with an already registered Listener will simply
redefine which events are sent; it will not cause the listener to
receive two copies of the same event.

Events are emitted by someone calling
bonobo_event_source_notify_listeners() on a BonoboEventSource, passing
in an event name and an Any data argument. The default implementation
will then send this event to any listeners who have registered to
receive events with the supplied event name.

A Listener can be removed from receiving events from an EventSource
using Bonobo_EventSource_removeListener().


Example Useage:
==============

Listener Creation:

guint my_id = 123;

void my_event_callback (BonoboListener *listener,
			char *event_name, 
			CORBA_any *any,
			CORBA_Environment *ev,
			gpointer user_data) {
	g_print("Event Received: %s", event_name);
}

...

BonoboListener *listener1, *listener2;
listener = bonobo_listener_new (my_event_callback,
GUINT_TO_POINTER(my_id));
listener = bonobo_listener_new (NULL, GUINT_TO_POINTER (my_id));


Registering a Listener:

Bonobo_Listener corba_listener1, corba_listener2;
Bonobo_EventSource corba_source;

/* Events: "one-more-beer", "one-less-beer", "out-of-ale",
"not-of-legal-age" */
char *mask = "one-more-beer, one-less-beer, out-of-ale,
not-of-legal-age";

corba_source = ...Get objref to event_source;
corba_listener1 = ...Get objref to listener1;
corba_listener2 = ...Get objref to listener2;

Bonobo_EventSource_addListener(corba_event_source, 
                               corba_listener1, 
                               ev);
Bonobo_EventSource_addListenerWithMask(corba_event_source, 
                                       corba_listener2, 
                                       mask, 
                                       ev);


Sending Events:

CORBA_any *data;

data = CORBA_any_alloc();
data->_type = TC_Foo;
data->_value = afoo;

bonobo_event_source_notify_listeners(event_source, 
                                     "out-of-ale", 
                                     data,
                                     NULL);


Open Questions:
==============

- Convert events to a corba struct to make the interface cleaner?
- Enforce event_mask formatting?


-Alex