[Vortex] CHANGE-NOTIFICATION: vortex-conn-on-close-02

[Francis Brosnan Blazquez]

       #####################################
       ####     Change notification     ####
       #####################################

    Change Id: vortex-conn-on-close-02
     Replaces: vortex-conn-on-close-01
 Project name: Vortex Library 1.0/1.1
  Included in: already included and to be shipped with next stable
               release
               1.0.16 (also updated 1.1 branch)
       Status: NOTIFY
       Author: Francis Brosnan Blázquez

Motivation
~~~~~~~~~~

The intention is to fix a bug caused by removing handlers wrongly
configured at vortex_connection_set_on_close_full and
vortex_connection_set_on_close. 

Because those functions allows to configure several handlers at the
same time, using the handler address to remove it is not a valid option.
This because the same handler can be used several times but with
different data (maybe contexts).

The change updates vortex_connection_set_on_close_full and
vortex_connection_set_on_close API to clearly state its current
function: returning NULL.

The change also modifies the vortex_connection_remove_on_close_full API
to also ask for the data used to install the handler to properly select
the right item to remove.

Change Description
~~~~~~~~~~~~~~~~~~

The following functions have been updated to return no value (void)
rather a pointer that always returns NULL (since Vortex Library 0.9.0
released on 2006/07/07):

   - vortex_connection_set_on_close_full 
   - vortex_connection_set_on_close

These functions are used to register a handler called on connection
close condition. On its initial design, the function was only
accepting one handler at time.

However, this showed to be not enough extensible to several modules
that were interested in getting notifications without uninstalling
other's handler. 

Due to this, the function was internally updated to accept several
handlers to be configured and to return always NULL (because there is
no way to return the appropriate "previous" handler).

The following change is also introduced:

   - vortex_connection_remove_on_close_full

Now, this function requires the user data pointer used to install the
on close handler before doing the removal. 

The intention is to avoid removing the inappropriate handler under
contexts where the same handler is installed several times but with
different data. 

This function now returns true or false (to signal if the handler was
removed or not) rather the handler removed as done until now.

Solution to incompatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~~

In the case vortex_connection_set_on_close_full and
vortex_connection_set_on_close function are used, no modification is
required because the function is returning NULL since Vortex Library
0.9.0 (2006/07/07). 

For the case of vortex_connection_remove_on_close_full it is now
required to provide a reference to the data that was used to configure
the on close handler.

References
~~~~~~~~~~
[1] Project link: 
    http://www.aspl.es/vortex/

[2] Change notification published by the project:
    http://other-change-notifications.com

[3] Change notification definition
    http://www.aspl.es/change/change-notification.txt

-- 
Francis Brosnan Blazquez <francis at aspl.es>
Advanced Software Production Line, S.L.