{{{
#!rst

=========================================================================
RFC 37: User data callbacks in CPLError
=========================================================================

:Date:  2011/10/25
:Author: Howard Butler
:Contact: hobu.inc at gmail dot com
:Status: Proposed
:Version: GDAL 1.9


Description: This RFC proposes to implement user context data in
CPLErrorHandler callback functions. It does so without disrupting existing
callback patterns already in use, and provides completely auxiliary
functionality to CPLErrorHandler.

Rationale
------------------------------------------------------------------------------

It could be argued that users could already manage user context of error
handling functions with application-level globals that control its
interaction. While this sentiment is technically true, this approach adds a
ton of complication for library users. A scenario that has error callbacks
pass back user context data means simpler code for users wishing to have the
state of their application be returned along with errors from inside of GDAL.

The case for user data be passed in callbacks:

* It is a common idiom for signal-based APIs (of which CPLErrorHandler is one)
* It is simpler than requiring library users to manage the state of internal 
  library error handling externally in their own applications


Implementation Concerns
------------------------------------------------------------------------------

GDAL's (and OGR and OSR's) error handling callback mechanisms are in wide use
and changes to the base library that were to break either the callback
signatures *or* the behavior of existing callback operations should be
rejected. Adding support for user data in the call back is to be provided
in addition to existing functionality that already exists in the error
handling, and an approach that mimics and looks similar to the existing
operations is likely the best approach for GDAL -- if not the cleanest
approach in general.

Planned Changes
------------------------------------------------------------------------------

The first change will add a void* to CPLErrorHandlerNode:

::

    typedef struct errHandler
    {
        struct errHandler   *psNext;
        void                *pUserData;
        CPLErrorHandler     pfnHandler;
    } CPLErrorHandlerNode;

and to methods to add error handlers with user data will be provided:

::

    CPLErrorHandler CPL_DLL CPL_STDCALL CPLSetErrorHandlerEx(CPLErrorHandler, void*);
    void CPL_DLL CPL_STDCALL CPLPushErrorHandlerEx( CPLErrorHandler, void* );

``CPLSetErrorHandler`` and ``CPLPushErrorHandler`` will simply use the ``Ex``
functions and pass NULL in for the pUserData member.

Finally, similar to ``CPLGetLastErrorType`` and ``CPLGetLastErrorMsg`` methods, 
a ``CPLGetLastErrorUserData``

::

    void* CPL_STDCALL CPLGetLastErrorUserData(void);
    
Ticket History
------------------------------------------------------------------------------

`#4295`:trac: contains a patch that implements the proposed solution and 
provides context and discussion about this feature.  http://trac.osgeo.org/gdal/attachment/ticket/4295/4295-hobu-rfc.patch 
contains the current patch to implemented the proposed functionality.

Documentation
------------------------------------------------------------------------------

Documentation of the added functions is provided as part of the patch.

Implementation
------------------------------------------------------------------------------

All code will be implemented in trunk by Howard Butler after passage of the 
RFC.



}}}