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

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


<!-- ##### SECTION Long_Description ##### -->
<para>
A GConfListeners object is used to store listeners who want notification of changes
in a namespace section. It is a public API shared between gconfd and the GObject 
convenience wrapper.
</para>

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

</para>

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


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


<!-- ##### STRUCT GConfListeners ##### -->
<para>

</para>


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

@listeners: a #GConfListeners.
@all_above_key: the key that has changed.
@cnxn_id: the connection id got from gconf_listeners_add().
@listener_data: the data field associated with each listener.
@user_data: the user data to be passed to the callback.


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

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


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

@listeners: a #GConfListeners.


<!-- ##### FUNCTION gconf_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 #GConfListeners.
@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 gconf_listeners_remove ##### -->
<para>
Removes the listener from the listener table.
</para>

@listeners: a #GConfListeners.
@cnxn_id: the connection id returned during gconf_listeners_add().


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

@listeners: a #GConfListeners.
@all_above: the key that has changed.
@callback: a #GConfListenersCallback to be called.
@user_data: data to be passed to the callback.


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

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


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

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


<!-- ##### FUNCTION gconf_listeners_get_data ##### -->
<para>
Obtains the data particular to a #GConfListener.
</para>

@listeners: a #GConfListeners.
@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 gconf_listeners_remove_if ##### -->
<para>
Remove the listener if a predicate is satisfied.
</para>

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


