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

[Francis Brosnan Blazquez]

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

    Change Id: 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 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 valid 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 while returning the previous handler and modifies the
vortex_connection_remove_on_close_full API to ask for the data used to
install the handler to properly select the handler 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 appropiate "previous" handler).

This change is also connected with the following change 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 inapropriate 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.