RFC 37:CPLError中的用户数据回调

日期: 2011年10月25日
作者: 霍华德巴特勒
联系: gmail.com上的hobu.inc
状态: 实施
版本: 杏仁体1.9
投票: +弗兰克，霍华德，塔玛斯，丹尼尔，甚至

描述：此RFC建议在CPLErrorHandler回调函数中实现用户上下文数据。它这样做不会中断已经在使用的现有回调模式，并为cplerorhandler提供完全辅助的功能。

理论基础

可以说，用户已经可以使用控制其交互的应用程序级全局变量来管理错误处理函数的用户上下文。虽然这种观点在技术上是正确的，但这种方法为类库用户增加了大量的复杂性。有错误回调传递回用户上下文数据的场景意味着对于希望从GDAL内部返回其应用程序状态和错误的用户来说，更简单的代码。

在回调中传递用户数据的情况：

它是基于信号的api（CPLErrorHandler是其中之一）的一个常用用法
它比要求库用户在自己的应用程序中管理外部处理内部库错误的状态更简单

实施问题

GDAL（以及OGR和OSR）的错误处理回调机制被广泛使用，并对基本库进行了更改，这些更改将破坏回调签名 or 应拒绝现有回调操作的行为。除了在错误处理中已经存在的现有功能之外，还将在回调中添加对用户数据的支持，并且一种模拟并看起来类似于现有操作的方法可能是GDAL的最佳方法——如果不是一般最干净的方法的话。

计划变更

第一个更改将向CPLErrorHandlerNode添加void*：

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

以及添加带有用户数据的错误处理程序的方法：

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

CPLSetErrorHandler 和 CPLPushErrorHandler 只需使用 Ex 函数并为pUserData成员传入NULL。

最后，类似于 CPLGetLastErrorType 和 CPLGetLastErrorMsg 方法，A CPLGetErrorHandlerUserData

void* CPL_STDCALL CPLGetErrorHandlerUserData(void);

SWIG绑定考虑

SWIG绑定将 not 更新以提供对当前活动的错误处理程序的用户数据的访问，以实现此RFC。不过，SWIG绑定维护者可以根据自己的判断利用这一新功能。

票证历史记录

http://trac.osgeo.org/gdal/ticket/4295 包含实现建议的解决方案的修补程序，并提供有关此功能的上下文和讨论。http://trac.osgeo.org/gdal/attachment/ticket/4295/4295-hobu-rfc.patch包含实现建议功能的当前修补程序。

文档

附加功能的文档作为补丁程序的一部分提供。

实施

所有代码将在通过RFC后由Howard Butler在trunk中实现。