Callbacks

The anti-spam engine makes use of callback functions in various places. All callbacks take a void *host as the first parameter. This parameter is not used by the engine at all and is only passed through to allow the hosting application to pass data to the callback. If the hosting application uses multiple instances of the engine simultaneously, the host parameter can be used to identify the corresponding engine object to the callback.

It is always valid to specify NULL for the callback if you do not want to be notified about the corresponding events.

The callbacks of the enumerate_*() methods return a boolean value: if it is 0, then enumeration is aborted immediately. Otherwise enumeration continues until it runs out of values. The enumerate_*() methods return the number of elements enumerated. If the enumeration is aborted this way, then the return value only reflects the number of elements actually visited. If an exception occurs during execution of the enumeration, the enumerator returns a count of -1, even if the callback function has already been called.

Any data passed to a callback function is only valid for the duration of the callback. If you want to preserve the data for later access, then the data must be copied from inside the callback.