matecomponent-event-source

## matecomponent-event-source matecomponent-event-source — An Event Source where clients can connect to listen to events. |

## Synopsis

    MateComponentEventSource * matecomponent_event_source_new             (void);
    void                matecomponent_event_source_notify_listeners
                                                            (MateComponentEventSource *event_source,
                                                             const char *event_name,
                                                             const CORBA_any *opt_value,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_event_source_notify_listeners_full
                                                            (MateComponentEventSource *event_source,
                                                             const char *path,
                                                             const char *type,
                                                             const char *subtype,
                                                             const CORBA_any *opt_value,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_event_source_client_remove_listener
                                                            (MateComponent_Unknown object,
                                                             MateComponent_Listener listener,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_event_source_client_add_listener
                                                            (MateComponent_Unknown object,
                                                             MateComponentListenerCallbackFn event_callback,
                                                             const char *opt_mask,
                                                             CORBA_Environment *opt_ev,
                                                             gpointer user_data);
    gboolean            matecomponent_event_source_has_listener    (MateComponentEventSource *event_source,
                                                             const char *event_name);
    void                matecomponent_event_source_client_add_listener_closure
                                                            (MateComponent_Unknown object,
                                                             GClosure *callback,
                                                             const char *opt_mask,
                                                             CORBA_Environment *opt_ev);
    MateComponent_Listener     matecomponent_event_source_client_add_listener_full
                                                            (MateComponent_Unknown object,
                                                             GClosure *callback,
                                                             const char *opt_mask,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_event_source_ignore_listeners
                                                            (MateComponentEventSource *event_source);

## Description

An event source object is responsible for channeling the emission of signals on an object to the appropriate attached listeners. The API is extremely simple and allows implementations to notify their listeners of a new event occuring.

To notify a listener, you need to construct a textual string, this is done by the `matecomponent_event` functions ( see MateComponentListener ) ':' delimiting the fields. It is reccommended that the IDL module path of the interface be used as the first part of the string. This is because many interfaces can be aggregated together and need to share the same event namespace without conflicts. So for example the matecomponent property bag notification code uses the IDL path "MateComponent/Property" the "change" kind and sets the sub-type to the property name:

Example 9. An example event source notification

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    static void
    notify_listeners (MateComponentPropertyBag *pb,
              MateComponentProperty    *prop,
              const MateComponentArg   *new_value,
              CORBA_Environment *opt_ev)
    {
        if (prop->flags & MATECOMPONENT_PROPERTY_NO_LISTENING)
            return;
        matecomponent_event_source_notify_listeners_full (pb->es,
                               "MateComponent/Property",
                               "change", prop->name,
                               new_value, opt_ev);
    }

Of course, you need to notify the listener with a valid MateComponentArg containing the event data, this could easily contain a structure. eg.

Example 10. Passing a structure in an event

    module MATE {
    	module Foo {
    		struct BaaEvent {
    			double a;
    			string b;
    			long   c;
    		};
    	};
    };

    static void
    fire_event (MateComponentEventSource *on_source,
                double             a_double,
    	    char              *a_string,
    	    long               a_float,
    	    CORBA_Environment *opt_ev)
    {
    	CORBA_any any;
    	MATE_Foo_BaaEvent e;
    	e.a = a_double;
    	e.b = a_string;
    	e.c = a_float;
    	any->_type = TC_MATE_Foo_BaaEvent;
    	any->_data = &e;
    	matecomponent_event_source_notify_listeners_full (
    	   on_source, "MATE/Foo", "event", NULL,
    	   &any, opt_ev);
    }

NB. it is reccommended that you make it clear that the event structure is intended for use with the MateComponentEventSource / MateComponentListener by naming it XYZEvent, ie. with the 'Event' suffix.

## Details

### matecomponent_event_source_new ()

    MateComponentEventSource * matecomponent_event_source_new             (void);

Creates a new MateComponentEventSource object. Typically this object will be exposed to clients through CORBA and they will register and unregister functions to be notified of events that this EventSource generates.

To notify clients of an event, use the `matecomponent_event_source_notify_listeners()` function.

Returns : | A new MateComponentEventSource server object.

### matecomponent_event_source_notify_listeners ()

    void                matecomponent_event_source_notify_listeners
                                                            (MateComponentEventSource *event_source,
                                                             const char *event_name,
                                                             const CORBA_any *opt_value,
                                                             CORBA_Environment *opt_ev);

This will notify all clients that have registered with this EventSource (through the addListener or addListenerWithMask methods) of the availability of the event named `event_name`. The `value` CORBA::any value is passed to all listeners.

`event_name` can not contain comma separators, as commas are used to separate the various event names.

`event_source` : | the Event Source that will emit the event.
`event_name` : | Name of the event being emitted
`opt_value` : | A CORBA_any value that contains the data that is passed to interested clients, or NULL for an empty value
`opt_ev` : | A CORBA_Environment where a failure code can be returned, can be NULL.

### matecomponent_event_source_notify_listeners_full ()

    void                matecomponent_event_source_notify_listeners_full
                                                            (MateComponentEventSource *event_source,
                                                             const char *path,
                                                             const char *type,
                                                             const char *subtype,
                                                             const CORBA_any *opt_value,
                                                             CORBA_Environment *opt_ev);

`event_source` : |
`path` : |
`type` : |
`subtype` : |
`opt_value` : |
`opt_ev` : |

### matecomponent_event_source_client_remove_listener ()

    void                matecomponent_event_source_client_remove_listener
                                                            (MateComponent_Unknown object,
                                                             MateComponent_Listener listener,
                                                             CORBA_Environment *opt_ev);

`object` : |
`listener` : |
`opt_ev` : |

### matecomponent_event_source_client_add_listener ()

    void                matecomponent_event_source_client_add_listener
                                                            (MateComponent_Unknown object,
                                                             MateComponentListenerCallbackFn event_callback,
                                                             const char *opt_mask,
                                                             CORBA_Environment *opt_ev,
                                                             gpointer user_data);

`object` : |
`event_callback` : |
`opt_mask` : |
`opt_ev` : |
`user_data` : |

### matecomponent_event_source_has_listener ()

    gboolean            matecomponent_event_source_has_listener    (MateComponentEventSource *event_source,
                                                             const char *event_name);

This method determines if there are any listeners for the event to be broadcast. This can be used to detect whether it is worth constructing a potentialy expensive state update, before sending it to no-one.

`event_source` : | the Event Source that will emit the event.
`event_name` : | Name of the event being emitted
Returns : | TRUE if it's worth sending, else FALSE

### matecomponent_event_source_client_add_listener_closure ()

    void                matecomponent_event_source_client_add_listener_closure
                                                            (MateComponent_Unknown object,
                                                             GClosure *callback,
                                                             const char *opt_mask,
                                                             CORBA_Environment *opt_ev);

`object` : |
`callback` : |
`opt_mask` : |
`opt_ev` : |

### matecomponent_event_source_client_add_listener_full ()

    MateComponent_Listener     matecomponent_event_source_client_add_listener_full
                                                            (MateComponent_Unknown object,
                                                             GClosure *callback,
                                                             const char *opt_mask,
                                                             CORBA_Environment *opt_ev);

`object` : |
`callback` : |
`opt_mask` : |
`opt_ev` : |
Returns : |

### matecomponent_event_source_ignore_listeners ()

    void                matecomponent_event_source_ignore_listeners
                                                            (MateComponentEventSource *event_source);

Instructs the event source to de-register any listeners that are added from the global running context.

## See Also

MateComponentListener MateComponentArg