The pdDocSetErrorCallback function registers a callback function to be called whenever critical errors occur while rendering PowerDoc objects.
Parameter | Description |
---|---|
power_doc |
Handle of the associated Power Engine document. |
user_prop_func |
A pointer to your own callback function that will be called whenever critical errors occur while rendering PowerDoc objects. Your function must be declared as follows: void user_error_func(DT_PD_DOCDRAW_CANVAS* canvas, DT_SLONG fn_draw, DT_SWORD error_code) where user_error_func is the name of your own C function, canvas a pointer to the DT_PD_DOCDRAW_CANVAS structure that supplies all the information necessary to identify the PowerDoc object that generated the critical error and fn_draw a numerical value of the rendering function associated with this object. The error_code parameter identifies the type of object-specific error that was encountered and can be one of the following: PD_RET_OBJ_ERR_MDC -8 /* memory surface not supported by object */ PD_RET_OBJ_ERR_PATTERN -7 /* pattern file access error */ PD_RET_OBJ_ERR_BITMAP -6 /* bitmap file access error */ PD_RET_OBJ_ERR_VECTOR -5 /* vector file access error */ PD_RET_OBJ_ERR_FONT -4 /* font file access error */ PD_RET_OBJ_ERR_MEMORY -3 /* not enough memory to process the object */ PD_RET_OBJ_ERR_DEFINITION -2 /* object not properly defined */ Your function is called any time D-Type Power Engine encounters a critical error while rendering a PowerDoc object. If your callback function is called, you should assume that the document will not be rendered completely and/or correctly. Note that a callback is initiated only if an object-specific error is classified as critical (meaning that it has a severe impact on the rendering outcome). Minor object-specific errors or inconsistencies will not initiate any callbacks. Setting the user_error_func parameter to DV_NULL when calling pdDocSetErrorCallback will permanently unregister a previously registered callback function. Once this is done, pdDocDraw will no longer initiate any callbacks when encountering critical object-specific errors. |
If the function was successful, the return value is 1. Otherwise, the function returns 0 (bad input).
Important Note for MS Windows Users: When passing D-Type a pointer to your own callback function, beware of the calling convention of your C/C++ environment. On MS Windows, all D-Type API functions that accept a pointer to your own callback function assume that your function uses the _cdecl convention. For example, in dtype.h on MS Windows the dtFontSetErrorCallback function is defined as follows:
DT_SWORD _stdcall dtFontSetErrorCallback(DT_DTENGINE engine, void (_cdecl *font_error_func)(const DT_CHAR* error_message, void* user_param), void* user_param);
Therefore, your own callback function must be defined as follows:
void _cdecl your_font_error_function(const DT_CHAR* error_message, void* your_param)
This note applies to any D-Type functions that expect a pointer to your own callback function (e.g. dtFontSetErrorCallback, pdDocSetDrawCallback, pdDocSetGlyphCallback, pdDocSetVectorCallback, txTextSetScriptCallback and possibly others in the future). Failing to add the _cdecl keyword may result in crashes and other undefined behavior, or your code may simply fail to compile.