<html>
<head><title>dkim_policy()</title></head>
<body>
<!--
$Id: dkim_policy.html,v 1.3 2010/07/24 04:58:44 cm-msk Exp $
-->
<h1>dkim_policy()</h1>
<p align="right"><a href="index.html">[back to index]</a></p>
<table border="0" cellspacing=4 cellpadding=4>
<!---------- Synopsis ----------->
<tr><th valign="top" align=left width=150>SYNOPSIS</th><td>
<pre>
#include <dkim.h>
<a href="dkim_stat.html">DKIM_STAT</a> dkim_policy(
<a href="dkim.html">DKIM</a> *dkim,
<a href="dkim_policy_t.html">dkim_policy_t</a> *pcode,
unsigned int *pflags,
<a href="dkim_pstate.html">DKIM_PSTATE *</a> pstate
);
</pre>
Retrieve and evaluate the author domain signing practices (ADSP) for a message.
</td></tr>
<!----------- Description ---------->
<tr><th valign="top" align=left>DESCRIPTION</th><td>
<table border="1" cellspacing=1 cellpadding=4>
<tr align="left" valign=top>
<th width="80">Called When</th>
<td><tt>dkim_policy()</tt> is called after
<a href="dkim_eom.html"><tt>dkim_eom()</tt></a> when <tt>dkim</tt> is a
verifying handle, i.e. one returned by an earlier call to
<a href="dkim_verify.html"><tt>dkim_verify()</tt></a>. </td>
</tr>
</table>
<!----------- Arguments ---------->
<tr><th valign="top" align=left>ARGUMENTS</th><td>
<table border="1" cellspacing=0>
<tr bgcolor="#dddddd"><th>Argument</th><th>Description</th></tr>
<tr valign="top"><td>dkim</td>
<td>Message-specific handle, returned by <a href="dkim_verify.html">
<tt>dkim_verify()</tt></a>.
</td></tr>
<tr valign="top"><td>pcode</td>
<td>A pointer to a <tt>dkim_policy_t</tt> which is updated to contain
the policy type retrieved from the sender. This can be NULL if that
information is not of interest to the caller.
</td></tr>
<tr valign="top"><td>pflags</td>
<td>A pointer to an unsigned integer which is updated to contain
policy flags retrieved from the sender. This can be NULL if that
information is not of interest to the caller. Valid flags are:
<ul>
<li> <tt>DKIM_PFLAG_ATSP</tt> -- policy shows ATSP enabled
</td></tr>
<tr valign="top"><td>pstate</td>
<td>A caller may wish to use this function in a re-entrant manner,
such as when using a policy lookup callback that may return
<tt>DKIM_CBSTAT_TRYAGAIN</tt>. In that case, the caller should
allocate a <tt><a href="dkim_pstate.html">DKIM_PSTATE</a></tt> and
initialize it using <tt>memset()</tt> to fill it with all-zeroes, then
pass a pointer to it to this function. If the callback does return
<tt>DKIM_CBSTAT_TRYAGAIN</tt>, <tt>pstate</tt> will be updated to
contain internal state information so that subsequent calls to
this function will simply re-attempt the lookup that could not
be completed on the previous attempt, essentially picking up where
it left off (avoiding repeated lookups). Instead, if <tt>pstate</tt>
is NULL, the entire policy process will be repeated on each call.
</td></tr>
</table>
</td></tr>
<!----------- Notes ---------->
<tr>
<th valign="top" align=left>NOTES</th>
<td>
<ul>
<li>ADSP (Author Domain Signing Practices) is defined in RFC5617.
<li>ATPS (Authorized Third Party Signers) is an experimental protocol
defined in draft-kucherawy-dkim-atps.
<li>It is an error to call this function with a handle that was created
using <a href="dkim_sign.html"><tt>dkim_sign()</tt></a>.
<li>This function will return <tt>DKIM_STAT_SYNTAX</tt> if the sender's
domain could not be determined or if the ADSP record retrieved is not
syntactically valid.
</ul>
</td>
</tr>
</table>
<hr size="1">
<font size="-1">
Copyright (c) 2005, 2007 Sendmail, Inc. and its suppliers.
All rights reserved.
<br>
Copyright (c) 2009, 2010, The OpenDKIM Project. All rights reserved.
<br>
By using this file, you agree to the terms and conditions set
forth in the respective licenses.
</font>
</body>
</html>
