Index

C/C++ Functions

pdDocSetErrorCallback

DT_SWORD pdDocSetErrorCallback(DT_PDDOC power_doc, void (*user_error_func)(DT_PD_DOCDRAW_CANVAS* canvas, DT_SLONG fn_draw, DT_SWORD error_code))

Short Description: Set document's callback function to be called if critical errors occur while rendering objects

The pdDocSetErrorCallback function registers a callback function to be called whenever critical errors occur while rendering PowerDoc objects.

Parameters

ParameterDescription

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.

Return Value

If the function was successful, the return value is 1. Otherwise, the function returns 0 (bad input).

Note

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.

 

Index