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