1.. _rfc-37:
2
3=========================================================================
4RFC 37: User data callbacks in CPLError
5=========================================================================
6
7:Date:  2011/10/25
8:Author: Howard Butler
9:Contact: hobu.inc at gmail dot com
10:Status: Implemented
11:Version: GDAL 1.9
12:Voting: +1 Frank, Howard, Tamas, Daniel, Even
13
14
15Description: This RFC proposes to implement user context data in
16CPLErrorHandler callback functions. It does so without disrupting existing
17callback patterns already in use, and provides completely auxiliary
18functionality to CPLErrorHandler.
19
20Rationale
21------------------------------------------------------------------------------
22
23It could be argued that users could already manage user context of error
24handling functions with application-level globals that control its
25interaction. While this sentiment is technically true, this approach adds a
26ton of complication for library users. A scenario that has error callbacks
27pass back user context data means simpler code for users wishing to have the
28state of their application be returned along with errors from inside of GDAL.
29
30The case for user data be passed in callbacks:
31
32* It is a common idiom for signal-based APIs (of which CPLErrorHandler is one)
33* It is simpler than requiring library users to manage the state of internal
34  library error handling externally in their own applications
35
36
37Implementation Concerns
38------------------------------------------------------------------------------
39
40GDAL's (and OGR and OSR's) error handling callback mechanisms are in wide use
41and changes to the base library that were to break either the callback
42signatures *or* the behavior of existing callback operations should be
43rejected. Adding support for user data in the call back is to be provided
44in addition to existing functionality that already exists in the error
45handling, and an approach that mimics and looks similar to the existing
46operations is likely the best approach for GDAL -- if not the cleanest
47approach in general.
48
49Planned Changes
50------------------------------------------------------------------------------
51
52The first change will add a void* to CPLErrorHandlerNode:
53
54::
55
56    typedef struct errHandler
57    {
58        struct errHandler   *psNext;
59        void                *pUserData;
60        CPLErrorHandler     pfnHandler;
61    } CPLErrorHandlerNode;
62
63and to methods to add error handlers with user data will be provided:
64
65::
66
67    CPLErrorHandler CPL_DLL CPL_STDCALL CPLSetErrorHandlerEx(CPLErrorHandler, void*);
68    void CPL_DLL CPL_STDCALL CPLPushErrorHandlerEx( CPLErrorHandler, void* );
69
70``CPLSetErrorHandler`` and ``CPLPushErrorHandler`` will simply use the ``Ex``
71functions and pass NULL in for the pUserData member.
72
73Finally, similar to ``CPLGetLastErrorType`` and ``CPLGetLastErrorMsg`` methods,
74a ``CPLGetErrorHandlerUserData``
75
76::
77
78    void* CPL_STDCALL CPLGetErrorHandlerUserData(void);
79
80SWIG bindings consideration
81..............................................................................
82
83The SWIG bindings will *not* be updated to provide access to user data for the
84currently active error handler for implementation of this RFC. SWIG bindings
85maintainers can take advantage of this new functionality at their discretion,
86however.
87
88Ticket History
89------------------------------------------------------------------------------
90
91`http://trac.osgeo.org/gdal/ticket/4295 <http://trac.osgeo.org/gdal/ticket/4295>`_ contains a patch that implements the proposed solution and
92provides context and discussion about this feature.  http://trac.osgeo.org/gdal/attachment/ticket/4295/4295-hobu-rfc.patch
93contains the current patch to implemented the proposed functionality.
94
95Documentation
96------------------------------------------------------------------------------
97
98Documentation of the added functions is provided as part of the patch.
99
100Implementation
101------------------------------------------------------------------------------
102
103All code will be implemented in trunk by Howard Butler after passage of the
104RFC.
105