mateconf-listeners

## mateconf-listeners mateconf-listeners |

## Synopsis

                        MateConfListeners;
    void                (*MateConfListenersCallback)           (MateConfListeners *listeners,
                                                             const gchar *all_above_key,
                                                             guint cnxn_id,
                                                             gpointer listener_data,
                                                             gpointer user_data);
    MateConfListeners *      mateconf_listeners_new               (void);
    void                mateconf_listeners_free                (MateConfListeners *listeners);
    guint               mateconf_listeners_add                 (MateConfListeners *listeners,
                                                             const gchar *listen_point,
                                                             gpointer listener_data,
                                                             GFreeFunc destroy_notify);
    void                mateconf_listeners_remove              (MateConfListeners *listeners,
                                                             guint cnxn_id);
    void                mateconf_listeners_notify              (MateConfListeners *listeners,
                                                             const gchar *all_above,
                                                             MateConfListenersCallback callback,
                                                             gpointer user_data);
    guint               mateconf_listeners_count               (MateConfListeners *listeners);
    void                mateconf_listeners_foreach             (MateConfListeners *listeners,
                                                             MateConfListenersForeach callback,
                                                             gpointer user_data);
    gboolean            mateconf_listeners_get_data            (MateConfListeners *listeners,
                                                             guint cnxn_id,
                                                             gpointer *listener_data_p,
                                                             const gchar **location_p);
    void                mateconf_listeners_remove_if           (MateConfListeners *listeners,
                                                             MateConfListenersPredicate predicate,
                                                             gpointer user_data);

## Description

A MateConfListeners object is used to store listeners who want notification of changes in a namespace section. It is a public API shared between mateconfd and the GObject convenience wrapper.

## Details

### MateConfListeners

    typedef struct _MateConfListeners MateConfListeners;

The MateConfListeners structure contains nothing other than a dummy pointer. Internally the data about listeners is maintained through a listener table structure, LTable which contains data like the namespace, an array to hold the listeners, count of active listeners,value to be given to the next connection and the list of connection indices to be recycled. There is also a Listener structure maintaining data pertaining to listeners.

### MateConfListenersCallback ()

    void                (*MateConfListenersCallback)           (MateConfListeners *listeners,
                                                             const gchar *all_above_key,
                                                             guint cnxn_id,
                                                             gpointer listener_data,
                                                             gpointer user_data);

This is the signature of a user function added with `mateconf_listeners_notify()`. This function is called whenever the value of a key changes.

`listeners` : | a MateConfListeners.
`all_above_key` : | the key that has changed.
`cnxn_id` : | the connection id got from `mateconf_listeners_add()`.
`listener_data` : | the data field associated with each listener.
`user_data` : | the user data to be passed to the callback.

### mateconf_listeners_new ()

    MateConfListeners *      mateconf_listeners_new               (void);

Creates a new listener table and typecasts it to a MateConfListeners.

Returns : | the newly allocated MateConfListeners.

### mateconf_listeners_free ()

    void                mateconf_listeners_free                (MateConfListeners *listeners);

Destroys the listener table.

`listeners` : | a MateConfListeners.

### mateconf_listeners_add ()

    guint               mateconf_listeners_add                 (MateConfListeners *listeners,
                                                             const gchar *listen_point,
                                                             gpointer listener_data,
                                                             GFreeFunc destroy_notify);

Creates a new Listener with the next available connection id and inserts it into the listener table. The newly created listener listens for changes below and including the `listen_point.Returns` the newly assigned connection id.

`listeners` : | a MateConfListeners.
`listen_point` : | where to listen for changes.
`listener_data` : | data to pass to function.
`destroy_notify` : | pointer to the function to be called when the listener is destroyed.
Returns : | the newly assigned connection id, a guint value.

### mateconf_listeners_remove ()

    void                mateconf_listeners_remove              (MateConfListeners *listeners,
                                                             guint cnxn_id);

Removes the listener from the listener table.

`listeners` : | a MateConfListeners.
`cnxn_id` : | the connection id returned during `mateconf_listeners_add()`.

### mateconf_listeners_notify ()

    void                mateconf_listeners_notify              (MateConfListeners *listeners,
                                                             const gchar *all_above,
                                                             MateConfListenersCallback callback,
                                                             gpointer user_data);

Notifies all the associated listeners that a key has changed.

`listeners` : | a MateConfListeners.
`all_above` : | the key that has changed.
`callback` : | a MateConfListenersCallback to be called.
`user_data` : | data to be passed to the callback.

### mateconf_listeners_count ()

    guint               mateconf_listeners_count               (MateConfListeners *listeners);

Returns the number of alive listeners in the listener table.

`listeners` : | a MateConfListeners
Returns : | the number of active listeners.

### mateconf_listeners_foreach ()

    void                mateconf_listeners_foreach             (MateConfListeners *listeners,
                                                             MateConfListenersForeach callback,
                                                             gpointer user_data);

Execute a function for each of the MateConfListeners.

`listeners` : | a MateConfListeners.
`callback` : | the function to be called.
`user_data` : | a gpointer.

### mateconf_listeners_get_data ()

    gboolean            mateconf_listeners_get_data            (MateConfListeners *listeners,
                                                             guint cnxn_id,
                                                             gpointer *listener_data_p,
                                                             const gchar **location_p);

Obtains the data particular to a MateConfListener.

`listeners` : | a MateConfListeners.
`cnxn_id` : | the connection id, an integer.
`listener_data_p` : | the address for getting the listener data.
`location_p` : | a pointer to the address for getting the name.
Returns : | TRUE if the data could be obtained successfully, FALSE if an error occurs while retrieving the data.

### mateconf_listeners_remove_if ()

    void                mateconf_listeners_remove_if           (MateConfListeners *listeners,
                                                             MateConfListenersPredicate predicate,
                                                             gpointer user_data);

Remove the listener if a predicate is satisfied.

`listeners` : | a MateConfListeners.
`predicate` : | the predicate checked for removal.
`user_data` : | a gpointer.