Back to index

opendkim  2.6.2
rbl.h
Go to the documentation of this file.
00001 /*
00002 **  Copyright (c) 2010, 2011, The OpenDKIM Project.  All rights reserved.
00003 */
00004 
00005 #ifndef _RBL_H_
00006 #define _RBL_H_
00007 
00008 #ifndef lint
00009 static char rbl_h_id[] = "$Id$";
00010 #endif /* !lint */
00011 
00012 /* system includes */
00013 #include <sys/types.h>
00014 #include <sys/time.h>
00015 #ifdef HAVE_STDINT_H
00016 # include <stdint.h>
00017 #endif /* HAVE_STDINT_H */
00018 
00019 /* definitions */
00020 #define       RBL_DEFTIMEOUT              5
00021 #define       RBL_MAXHOSTNAMELEN   256
00022 #define       RBL_MAXERRORSTRING   256
00023 
00024 /* return codes */
00025 typedef int RBL_STAT;
00026 
00027 #define       RBL_STAT_ERROR              (-1)
00028 #define RBL_STAT_OK         0
00029 #define RBL_STAT_INVALID    1
00030 #define RBL_STAT_DNSERROR   2
00031 #define RBL_STAT_NORESOURCE 3
00032 #define RBL_STAT_NOTIMPLEMENT      4
00033 #define RBL_STAT_NOTFOUND   5
00034 #define       RBL_STAT_FOUND              6             /* reply available */
00035 #define       RBL_STAT_NOREPLY     7             /* reply not available (yet) */
00036 #define       RBL_STAT_EXPIRED     8             /* no reply, query expired */
00037 
00038 /* generic DNS error codes */
00039 #define       RBL_DNS_ERROR        (-1)          /* error in transit */
00040 #define       RBL_DNS_SUCCESS             0             /* reply available */
00041 #define       RBL_DNS_NOREPLY             1             /* reply not available (yet) */
00042 #define       RBL_DNS_EXPIRED             2             /* no reply, query expired */
00043 
00044 /* types */
00045 struct rbl_handle;
00046 typedef struct rbl_handle RBL;
00047 
00048 /* prototypes */
00049 
00050 /*
00051 **  RBL_INIT -- initialize an RBL handle
00052 **
00053 **  Parameters:
00054 **     caller_mallocf -- caller-provided memory allocation function
00055 **     caller_freef -- caller-provided memory release function
00056 **     closure -- memory closure to pass to the above when used
00057 **
00058 **  Return value:
00059 **     A new RBL handle suitable for use with other RBL functions, or
00060 **     NULL on failure.
00061 **  
00062 **  Side effects:
00063 **     Strange radar returns at Indianapolis ARTCC.
00064 */
00065 
00066 extern RBL * rbl_init __P((void *(*caller_mallocf)(void *closure,
00067                                                    size_t nbytes),
00068                            void (*caller_freef)(void *closure, void *p),
00069                            void *closure));
00070 
00071 /*
00072 **  RBL_CLOSE -- shut down a RBL instance
00073 **
00074 **  Parameters:
00075 **     rbl -- RBL handle to shut down
00076 **
00077 **  Return value:
00078 **     None.
00079 */
00080 
00081 extern void rbl_close __P((RBL *));
00082 
00083 /*
00084 **  RBL_GETERROR -- return any stored error string from within the RBL
00085 **                  context handle
00086 **
00087 **  Parameters:
00088 **     rbl -- RBL handle from which to retrieve an error string
00089 **
00090 **  Return value:
00091 **     A pointer to the stored string, or NULL if none was stored.
00092 */
00093 
00094 extern const u_char *rbl_geterror __P((RBL *));
00095 
00096 /*
00097 **  RBL_SETDOMAIN -- declare the RBL's domain (the query root)
00098 **
00099 **  Parameters:
00100 **     rbl -- RBL handle, created by rbl_init()
00101 **     qroot-- certifiers string
00102 **
00103 **  Return value:
00104 **     None (yet).
00105 */
00106 
00107 extern void rbl_setdomain __P((RBL *, u_char *));
00108 
00109 /*
00110 **  RBL_QUERY_START -- initiate a query to the RBL for entries
00111 **
00112 **  Parameters:
00113 **     rbl -- RBL handle, created by rbl_init()
00114 **     query -- query string
00115 **     qh -- query handle (returned)
00116 **
00117 **  Return value:
00118 **     RBL_STAT_INVALID -- rbl_setdomain() was not called, or "query" was NULL
00119 **     RBL_STAT_* -- as defined
00120 */
00121 
00122 extern RBL_STAT rbl_query_start __P((RBL *, u_char *, void **));
00123 
00124 /*
00125 **  RBL_QUERY_CHECK -- check for a reply from an active query
00126 **
00127 **  Parameters:
00128 **     rbl -- RBL handle, created by rbl_init()
00129 **     qh -- query handle (returned)
00130 **     timeout -- timeout
00131 **     res -- 32-bit buffer into which to write the result (can be NULL)
00132 **
00133 **  Return value:
00134 **     RBL_STAT_* -- as defined
00135 */
00136 
00137 extern RBL_STAT rbl_query_check __P((RBL *, void *, struct timeval *,
00138                                      uint32_t *));
00139 
00140 /*
00141 **  RBL_QUERY_CANCEL -- cancel an open query to the RBL
00142 **
00143 **  Parameters:
00144 **     rbl -- RBL handle, created by rbl_init()
00145 **     qh -- query handle
00146 **
00147 **  Return value:
00148 **     RBL_STAT_* -- as defined
00149 */
00150 
00151 extern RBL_STAT rbl_query_cancel __P((RBL *, void *));
00152 
00153 /*
00154 **  RBL_SETTIMEOUT -- set the DNS timeout
00155 **
00156 **  Parameters:
00157 **     rbl -- RBL handle, created by rbl_init()
00158 **     timeout -- requested timeout (seconds)
00159 **
00160 **  Return value:
00161 **     None.
00162 */
00163 
00164 extern void rbl_settimeout __P((RBL *, u_int));
00165 
00166 /*
00167 **  RBL_SETCALLBACKINT -- set the DNS callback interval
00168 **
00169 **  Parameters:
00170 **     rbl -- RBL handle, created by rbl_init()
00171 **     cbint -- requested callback interval (seconds)
00172 **
00173 **  Return value:
00174 **     None.
00175 */
00176 
00177 extern void rbl_setcallbackint __P((RBL *, u_int));
00178 
00179 /*
00180 **  RBL_SETCALLBACKCTX -- set the DNS callback context
00181 **
00182 **  Parameters:
00183 **     rbl -- RBL handle, created by rbl_init()
00184 **     ctx -- context to pass to the DNS callback
00185 **
00186 **  Return value:
00187 **     None.
00188 */
00189 
00190 extern void rbl_setcallbackctx __P((RBL *, void *));
00191 
00192 /*
00193 **  RBL_SETDNSCALLBACK -- set the DNS wait callback
00194 **
00195 **  Parameters:
00196 **     rbl -- RBL handle, created by rbl_init()
00197 **     func -- function to call; should take an opaque context pointer
00198 **
00199 **  Return value:
00200 **     None.
00201 */
00202 
00203 extern void rbl_setdnscallback __P((RBL *rbl,
00204                                     void (*func)(const void *context)));
00205 
00206 /*
00207 **  RBL_DNS_SET_QUERY_SERVICE -- stores a handle representing the DNS
00208 **                               query service to be used, returning any
00209 **                               previous handle
00210 **
00211 **  Parameters:
00212 **     rbl -- RBL library handle
00213 **     h -- handle to be used
00214 **
00215 **  Return value:
00216 **     Previously stored handle, or NULL if none.
00217 */
00218 
00219 extern void *rbl_dns_set_query_service __P((RBL *, void *));
00220 
00221 /*
00222 **  RBL_DNS_SET_QUERY_START -- stores a pointer to a query start function
00223 **
00224 **  Parameters:
00225 **     lib -- RBL library handle
00226 **     func -- function to use to start queries
00227 **
00228 **  Return value:
00229 **     None.
00230 **
00231 **  Notes:
00232 **     "func" should match the following prototype:
00233 **            returns int (status)
00234 **            void *dns -- receives handle stored by
00235 **                         rbl_dns_set_query_service()
00236 **            int type -- DNS RR query type (C_IN assumed)
00237 **            char *query -- question to ask
00238 **            char *buf -- buffer into which to write reply
00239 **            size_t buflen -- size of buf
00240 **            void **qh -- returned query handle
00241 */
00242 
00243 extern void rbl_dns_set_query_start __P((RBL *,
00244                                          int (*)(void *, int,
00245                                                  unsigned char *,
00246                                                  unsigned char *,
00247                                                  size_t, void **)));
00248 
00249 /*
00250 **  RBL_DNS_SET_QUERY_CANCEL -- stores a pointer to a query cancel function
00251 **
00252 **  Parameters:
00253 **     lib -- RBL library handle
00254 **     func -- function to use to cancel running queries
00255 **
00256 **  Return value:
00257 **     None.
00258 **
00259 **  Notes:
00260 **     "func" should match the following prototype:
00261 **            returns int (status)
00262 **            void *dns -- DNS service handle
00263 **            void *qh -- query handle to be canceled
00264 */
00265 
00266 extern void rbl_dns_set_query_cancel __P((RBL *,
00267                                           int (*)(void *, void *)));
00268 
00269 /*
00270 **  RBL_DNS_SET_QUERY_WAITREPLY -- stores a pointer to wait for a DNS reply
00271 **
00272 **  Parameters:
00273 **     lib -- RBL library handle
00274 **     func -- function to use to wait for a reply
00275 **
00276 **  Return value:
00277 **     None.
00278 **
00279 **  Notes:
00280 **     "func" should match the following prototype:
00281 **            returns int (status)
00282 **            void *dns -- DNS service handle
00283 **            void *qh -- handle of query that has completed
00284 **            struct timeval *timeout -- how long to wait
00285 **            size_t *bytes -- bytes returned
00286 **            int *error -- error code returned
00287 **            int *dnssec -- DNSSEC status returned
00288 */
00289 
00290 extern void rbl_dns_set_query_waitreply __P((RBL *,
00291                                              int (*)(void *, void *,
00292                                                      struct timeval *,
00293                                                      size_t *, int *,
00294                                                      int *)));
00295 
00296 #endif /* _RBL_H_ */