Back to index

opendkim  2.6.4
dkim-rep.h
Go to the documentation of this file.
00001 /*
00002 **  Copyright (c) 2008 Sendmail, Inc. and its suppliers.
00003 **    All rights reserved.
00004 **
00005 **  Copyright (c) 2009, 2011, The OpenDKIM Project.  All rights reserved.
00006 */
00007 
00008 #ifndef _DKIM_REP_H_
00009 #define _DKIM_REP_H_
00010 
00011 #ifndef lint
00012 static char dkim_rep_h_id[] = "@(#)$Id: dkim-rep.h,v 1.2 2009/07/23 17:40:23 cm-msk Exp $";
00013 #endif /* !lint */
00014 
00015 /* data types */
00016 typedef int DKIM_REP_STAT;
00017 
00018 struct dkim_rep_handle;
00019 typedef struct dkim_rep_handle * DKIM_REP;
00020 
00021 /* macros */
00022 #define       DKIM_REP_STAT_OK     0
00023 #define       DKIM_REP_STAT_SYNTAX 1
00024 #define       DKIM_REP_STAT_NOTFOUND      2
00025 #define       DKIM_REP_STAT_FOUND  3
00026 #define       DKIM_REP_STAT_ERROR  4
00027 #define       DKIM_REP_STAT_EXPIRED       5
00028 #define       DKIM_REP_STAT_NOREPLY       6
00029 
00030 #define       DKIM_REP_DNS_SUCCESS 0
00031 #define       DKIM_REP_DNS_ERROR   1
00032 #define       DKIM_REP_DNS_EXPIRED 2
00033 #define       DKIM_REP_DNS_NOREPLY 3
00034 
00035 #define       DKIM_REP_DEFREJECT   1001
00036 #define       DKIM_REP_DEFROOT     "al.dkim-reputation.org"
00037 
00038 /* prototypes */
00039 
00040 /*
00041 **  DKIM_REP_INIT -- initialize an DKIM_REP handle
00042 **
00043 **  Parameters:
00044 **     caller_mallocf -- caller-provided memory allocation function
00045 **     caller_freef -- caller-provided memory release function
00046 **     closure -- memory closure to pass to the above when used
00047 **
00048 **  Return value:
00049 **     A new DKIM_REP handle suitable for use with other DKIM_REP
00050 **     functions, or NULL on failure.
00051 **  
00052 **  Side effects:
00053 **     Small but detectable movement of the Indian subcontinent.
00054 */
00055 
00056 extern DKIM_REP dkim_rep_init __P((void *(*caller_mallocf)(void *closure,
00057                                                            size_t nbytes),
00058                                    void (*caller_freef)(void *closure,
00059                                                         void *p),
00060                                    void *closure));
00061 
00062 /*
00063 **  DKIM_REP_CLOSE -- shut down a DKIM_REP instance
00064 **
00065 **  Parameters:
00066 **     dkim_rep -- DKIM_REP handle to shut down
00067 **
00068 **  Return value:
00069 **     None.
00070 */
00071 
00072 extern void dkim_rep_close __P((DKIM_REP));
00073 
00074 /*
00075 **  DKIM_REP_GETERROR -- return any stored error string from within the
00076 **                       DKIM_REP context handle
00077 **
00078 **  Parameters:
00079 **     dkim_rep -- DKIM_REP handle from which to retrieve an error string
00080 **
00081 **  Return value:
00082 **     A pointer to the stored string, or NULL if none was stored.
00083 */
00084 
00085 extern const u_char *dkim_rep_geterror __P((DKIM_REP));
00086 
00087 /*
00088 **  DKIM_REP_SETDOMAIN -- declare the DKIM_REP's domain (the query root)
00089 **
00090 **  Parameters:
00091 **     dkim_rep -- DKIM_REP handle, created by dkim_rep_init()
00092 **     qroot-- certifiers string
00093 **
00094 **  Return value:
00095 **     None (yet).
00096 */
00097 
00098 extern void dkim_rep_setdomain __P((DKIM_REP, u_char *));
00099 
00100 /*
00101 **  DKIM_REP_QUERY_START -- initiate a query to the DKIM_REP for entries
00102 **
00103 **  Parameters:
00104 **     dkim_rep -- DKIM_REP handle, created by dkim_rep_init()
00105 **     user -- local-part of From:
00106 **     domain -- domain part of From:
00107 **     signdomain -- signing domain
00108 **     qh -- query handle (returned)
00109 **
00110 **  Return value:
00111 **     DKIM_REP_STAT_INVALID -- dkim_rep_setdomain() was not called,
00112 **                               or "query" was NULL
00113 **     DKIM_REP_STAT_* -- as defined
00114 */
00115 
00116 extern DKIM_REP_STAT dkim_rep_query_start __P((DKIM_REP, u_char *, u_char *,
00117                                                u_char *, void **));
00118 
00119 /*
00120 **  DKIM_REP_QUERY_CHECK -- check for a reply from an active query
00121 **
00122 **  Parameters:
00123 **     dkim_rep -- DKIM_REP handle, created by dkim_rep_init()
00124 **     qh -- query handle (returned)
00125 **     timeout -- timeout
00126 **     res -- integer into which to write the result (can be NULL)
00127 **
00128 **  Return value:
00129 **     DKIM_REP_STAT_* -- as defined
00130 */
00131 
00132 extern DKIM_REP_STAT dkim_rep_query_check __P((DKIM_REP, void *,
00133                                                struct timeval *, int *));
00134 
00135 /*
00136 **  DKIM_REP_QUERY_CANCEL -- cancel an open query to the service
00137 **
00138 **  Parameters:
00139 **     dkim_rep -- DKIM_REP handle, created by dkim_rep_init()
00140 **     qh -- query handle
00141 **
00142 **  Return value:
00143 **     DKIM_REP_STAT_* -- as defined
00144 */
00145 
00146 extern DKIM_REP_STAT dkim_rep_query_cancel __P((DKIM_REP, void *));
00147 
00148 /*
00149 **  DKIM_REP_SETTIMEOUT -- set the DNS timeout
00150 **
00151 **  Parameters:
00152 **     dkim_rep -- DKIM_REP handle, created by dkim_rep_init()
00153 **     timeout -- requested timeout (seconds)
00154 **
00155 **  Return value:
00156 **     None.
00157 */
00158 
00159 extern void dkim_rep_settimeout __P((DKIM_REP, u_int));
00160 
00161 /*
00162 **  DKIM_REP_SETCALLBACKINT -- set the DNS callback interval
00163 **
00164 **  Parameters:
00165 **     dkim_rep -- DKIM_REP handle, created by dkim_rep_init()
00166 **     cbint -- requested callback interval (seconds)
00167 **
00168 **  Return value:
00169 **     None.
00170 */
00171 
00172 extern void dkim_rep_setcallbackint __P((DKIM_REP, u_int));
00173 
00174 /*
00175 **  DKIM_REP_SETCALLBACKCTX -- set the DNS callback context
00176 **
00177 **  Parameters:
00178 **     dkim_rep -- DKIM_REP handle, created by dkim_rep_init()
00179 **     ctx -- context to pass to the DNS callback
00180 **
00181 **  Return value:
00182 **     None.
00183 */
00184 
00185 extern void dkim_rep_setcallbackctx __P((DKIM_REP, void *));
00186 
00187 /*
00188 **  DKIM_REP_SETDNSCALLBACK -- set the DNS wait callback
00189 **
00190 **  Parameters:
00191 **     dkim_rep -- DKIM_REP handle, created by dkim_rep_init()
00192 **     func -- function to call; should take an opaque context pointer
00193 **
00194 **  Return value:
00195 **     None.
00196 */
00197 
00198 extern void dkim_rep_setdnscallback __P((DKIM_REP, void (*)(const void *)));
00199 
00200 /*
00201 **  DKIM_REP_DNS_SET_QUERY_SERVICE -- stores a handle representing the DNS
00202 **                                    query service to be used, returning any
00203 **                                    previous handle
00204 **
00205 **  Parameters:
00206 **     dkim_rep -- DKIM_REP library handle
00207 **     h -- handle to be used
00208 **
00209 **  Return value:
00210 **     Previously stored handle, or NULL if none.
00211 */
00212 
00213 extern void *dkim_rep_dns_set_query_service __P((DKIM_REP, void *));
00214 
00215 /*
00216 **  DKIM_REP_DNS_SET_QUERY_START -- stores a pointer to a query start function
00217 **
00218 **  Parameters:
00219 **     dkim_rep -- DKIM_REP library handle
00220 **     func -- function to use to start queries
00221 **
00222 **  Return value:
00223 **     None.
00224 **
00225 **  Notes:
00226 **     "func" should match the following prototype:
00227 **            returns int (status)
00228 **            void *dns -- receives handle stored by
00229 **                         dkim_rep_dns_set_query_service()
00230 **            int type -- DNS RR query type (C_IN assumed)
00231 **            char *query -- question to ask
00232 **            char *buf -- buffer into which to write reply
00233 **            size_t buflen -- size of buf
00234 **            void **qh -- returned query handle
00235 */
00236 
00237 extern void dkim_rep_dns_set_query_start __P((DKIM_REP,
00238                                               int (*)(void *, int,
00239                                                       unsigned char *,
00240                                                       unsigned char *,
00241                                                       size_t, void **)));
00242 
00243 /*
00244 **  DKIM_REP_DNS_SET_QUERY_CANCEL -- stores a pointer to a query cancel
00245 **                                   function
00246 **
00247 **  Parameters:
00248 **     dkim_rep -- DKIM_REP library handle
00249 **     func -- function to use to cancel running queries
00250 **
00251 **  Return value:
00252 **     None.
00253 **
00254 **  Notes:
00255 **     "func" should match the following prototype:
00256 **            returns int (status)
00257 **            void *dns -- DNS service handle
00258 **            void *qh -- query handle to be canceled
00259 */
00260 
00261 extern void dkim_rep_dns_set_query_cancel __P((DKIM_REP,
00262                                                int (*)(void *, void *)));
00263 
00264 /*
00265 **  DKIM_REP_DNS_SET_QUERY_WAITREPLY -- stores a pointer to wait for a
00266 **                                      DNS reply
00267 **
00268 **  Parameters:
00269 **     dkim_rep -- DKIM_REP library handle
00270 **     func -- function to use to wait for a reply
00271 **
00272 **  Return value:
00273 **     None.
00274 **
00275 **  Notes:
00276 **     "func" should match the following prototype:
00277 **            returns int (status)
00278 **            void *dns -- DNS service handle
00279 **            void *qh -- handle of query that has completed
00280 **            struct timeval *timeout -- how long to wait
00281 **            size_t *bytes -- bytes returned
00282 **            int *error -- error code returned
00283 **            int *dnssec -- DNSSEC status returned
00284 */
00285 
00286 extern void dkim_rep_dns_set_query_waitreply __P((DKIM_REP,
00287                                                   int (*)(void *, void *,
00288                                                           struct timeval *,
00289                                                           size_t *, int *,
00290                                                           int *)));
00291 
00292 #endif /* ! _DKIM_REP_H_ */