(v13) The callback function

This page applies to Harlequin v13.1r0 and later; and to Harlequin MultiRIP but not Harlequin Core

During initialization, the plugin provides a pointer to a callback function of the following type (for more information see (v13) Initializing the PFI ):

TEXT

    void
    CallbackFunction(uint32 nFunction,
                      uint32 nError, PlgFwTextString ptbzError);

This function is called by the PFI if a major error occurs. It is the plugin's responsibility to judge – given the information provided by the callback – how to proceed. In many cases, the plugin should shut itself down gracefully, preferably without making any further PFI calls (with the exception of freeing allocated memory and handles).

As this callback would occur only during a plugin's call to a PFI function, it is imperative that the plugin merely note the parameter values (perhaps also flagging itself to shut down soon) and return as soon as possible, so that the PFI in turn can return from the PFI function back to the plugin.

The value of nFunction is the enumeration for the PFI function in which the error occurred. The nError argument may be one of:

`PFI_CALLBACK_ERR_NOT_LOADED`	A PFI function was called whose enumeration was not included in the list supplied to `PlgPFIInitialise` .
`PFI_CALLBACK_ERR_BAD_ARGUMENT`	A PFI function was called with an invalid argument (for example, a NULL pointer in a situation where this would prevent the call from working properly).
`PFI_CALLBACK_ERR_NO_MEMORY`	During execution of a PFI function for which memory was being allocated invisibly, the memory allocation failed. If a plugin receives this error code from the callback function, it should probably attempt to close down gracefully but quickly.

The ptbzError parameter contains a NULL‐terminated string relevant to the error (which will not have a trailing new line). This string is statically allocated, and the pointer remains valid for as long as the plugin is loaded; consequently, the plugin must not attempt to either alter the contents of the string or free the pointer.

In all cases, the PFI attempts to return from the function in an orderly fashion. For those functions for which a failure can be flagged using PFI methods (for example, returning an invalid handle or NULL pointer, or a PlgFwError condition), the PFI will endeavor to do so. The string may be used in a PluginOutMonitor call; bear in mind that the error may have arisen from a problem which could pre‐ vent use of PFI‐based error reporting.