# dkim_set_prescreen()

[back to index]

SYNOPSIS

    #include <dkim.h>
    DKIM_STAT dkim_set_prescreen(
    	DKIM_LIB *libopendkim,
            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
--- | ---
libopendkim | 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.
Copyright (c) 2009, 2010, The OpenDKIM Project. All rights reserved.
By using this file, you agree to the terms and conditions set forth in the respective licenses.