<!-- ##### SECTION Title ##### -->
mateconf-listeners

<!-- ##### SECTION Short_Description ##### -->


<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### SECTION Image ##### -->


<!-- ##### STRUCT MateConfListeners ##### -->
<para>

</para>


<!-- ##### USER_FUNCTION MateConfListenersCallback ##### -->
<para>
This is the signature of a user function added with mateconf_listeners_notify(). This function
is called whenever the value of a key changes. 
</para>

@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.


<!-- ##### FUNCTION mateconf_listeners_new ##### -->
<para>
Creates a new listener table and typecasts it to a #MateConfListeners.
</para>

@void: 
@Returns: the newly allocated #MateConfListeners.


<!-- ##### FUNCTION mateconf_listeners_free ##### -->
<para>
Destroys the listener table.
</para>

@listeners: a #MateConfListeners.


<!-- ##### FUNCTION mateconf_listeners_add ##### -->
<para>
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.
</para>

@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.


<!-- ##### FUNCTION mateconf_listeners_remove ##### -->
<para>
Removes the listener from the listener table.
</para>

@listeners: a #MateConfListeners.
@cnxn_id: the connection id returned during mateconf_listeners_add().


<!-- ##### FUNCTION mateconf_listeners_notify ##### -->
<para>
Notifies all the associated listeners that a key has changed.
</para>

@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.


<!-- ##### FUNCTION mateconf_listeners_count ##### -->
<para>
Returns the number of alive listeners in the listener table.
</para>

@listeners: a #MateConfListeners
@Returns: the number of active listeners.


<!-- ##### FUNCTION mateconf_listeners_foreach ##### -->
<para>
Execute a function for each of the #MateConfListeners.
</para>

@listeners: a #MateConfListeners.
@callback: the function to be called.
@user_data: a gpointer.


<!-- ##### FUNCTION mateconf_listeners_get_data ##### -->
<para>
Obtains the data particular to a #MateConfListener.
</para>

@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: <symbol>TRUE</symbol> if the data could be obtained successfully, <symbol>FALSE</symbol> 
if an error occurs while retrieving the data.


<!-- ##### FUNCTION mateconf_listeners_remove_if ##### -->
<para>
Remove the listener if a predicate is satisfied.
</para>

@listeners: a #MateConfListeners.
@predicate: the predicate checked for removal.
@user_data: a #gpointer.


