# dkim_set_prescreen()

SYNOPSIS |
    #include <dkim.h>
    DKIM_STAT dkim_set_prescreen(
    	DKIM_LIB *libdkim,
            DKIM_CBSTAT (*func)(DKIM *dkim, DKIM_SIGINFO **sigs, int nsigs));
    );
Defines a callback function to be used for pre-scanning and sorting signatures discovered on a message. From within `dkim_eoh()`, an array of `DKIM_SIGINFO` handles is allocated, and an array of pointers is created referring to them. If this callback function is defined, it will be called by `dkim_eoh()` to give the caller a chance to review the signatures and possibly reorder or flag them for special treatment by the library. `sigs` will refer to the array of discovered signatures and `nsigs` will indicate the length of this array. From within the callback you can use `dkim_sig_getcontext()` on any of the `DKIM_SIGINFO` pointers to retrieve the user-allocated context specific to that signature as created earlier by the allocation callback set by `dkim_set_signature_handle()` and make use of the data found there. That context is not used by the library in any way. The callback can also use the function `dkim_sig_ignore()` to indicate to the library that the signature should be completely ignored. The callback should return one of the `DKIM_CBSTAT` return values. Any other value will cause `dkim_eoh()` to abort and return a status of `DKIM_STAT_CBINVALID`.
DESCRIPTION |
Called When | `dkim_set_prescreen()` must be called before `dkim_eoh()` has been called.
ARGUMENTS |
Argument | Description
--- | ---
libdkim | The library instantiation handle, returned by `dkim_init()`.
func | A pointer to a function which takes a `DKIM` handle, a pointer to an array of `DKIM_SIGINFO` handles and an integer indicating the length of that array as parameters. If NULL, no callback will be used.
RETURN VALUES | DKIM_STAT_OK -- success
NOTES | None.

Copyright (c) 2007 Sendmail, Inc. and its suppliers. All rights reserved.
By using this file, you agree to the terms and conditions set forth in the LICENSE.