1libdspam(3) libdspam libdspam(3)
2
6 libdspam - Core message processing and classification library for DSPAM
7 DSPAM Core Analyis Engine Functions
9
12 #include <libdspam.h>
13 DSPAM_CTX *dspam_init(const char *username, const char *group,
15 const char *home, int operating_mode, u_int32_t flags);
16 DSPAM_CTX *dspam_create(const char *username, const char *group,
18 const char *home, int operating_mode, u_int32_t flags);
19 int dspam_addattribute(DSPAM_CTX *CTX, const char *key,
21 const char *value);
22 int dspam_clearattributes(DSPAM_CTX *CTX);
24 int dspam_attach(DSPAM_CTX *CTX, void *dbh);
26 int dspam_process(DSPAM_CTX *CTX, const char *message);
28 int dspam_getsource(DSPAM_CTX *CTX, char *buf, size_t size);
30 int dspam_detach(DSPAM_CTX *CTX);
32 int dspam_destroy(DSPAM_CTX *CTX);
34
36 libdspam provides core message processing and classification function‐
37 ality.
38 The dspam_init() function creates and initializes a new classification
40 context and attaches the context to whatever backend storage facility
41 was configured. The user and group arguments provided are used to read
42 and write information stored for the user and group specified. The home
43 argument is used to configure libdspam's storage around the base direc‐
44 tory specified. The mode specifies the operating mode to initialize the
45 classification context with and may be one of:
46 DSM_PROCESS Classify and learn the supplied message using whatever
48 training mode is specified
49 DSM_CLASSIFY Classify the supplied message only; do not learn or
50 update any counters.
51 DSM_TOOLS No processing, attach to storage only
52 The flags provided further tune the classification context for a spe‐
54 cific function. Multiple flags may be OR'd together.
55 DSF_UNLEARN Unlearn the message
57 DSF_BIAS Assign processor bias to unknown tokens
58 DSF_SIGNATURE A binary signature is requested/provided
59 DSF_NOISE Apply Bayesian Noise Reduction logic
60 DSF_WHITELIST Use automatic whitelisting logic
61 DSF_MERGED Merge group metadata with user's in memory
62 Upon successful completion, dspam_init() will return a pointer to a new
64 classification context structure containing a copy of the configuration
65 passed into dspam_init(), a connected storage driver handle, and a set
66 of preliminary user control data read from storage.
67 The dspam_create() function performs in exactly the same manner as the
69 dspam_init() function, but does not attach to storage. Instead, the
70 caller must also call dspam_attach() after setting any storage- spe‐
71 cific attributes using dspam_addattribute(). This is useful for cases
72 where the implementor would prefer to configure storage internally
73 rather than having libdspam read a configuration from a file.
74 The dspam_addattribute() function is called to set attributes within
76 the classification context. Some storage drivers support the use of
77 passing specific attributes such as server connect information. The
78 driver-independent attributes supported by DSPAM include:
79 IgnoreHeader Specify a specific header to ignore
81 LocalMX Specify a local mail exchanger to assist in
82 correct results from dspam_getsource().
83 Only driver-dependent attributes need be set prior to a call to
85 dspam_attach(). Driver-independent attributes may be set both before
86 and after storage has been attached.
87 The dspam_attach() function attaches the storage interface to the clas‐
89 sification context and alternatively established an initial connection
90 with storage if dbh is NULL. Some storage drivers support only a NULL
91 value for dbh, while others (such as mysql_drv, pgsql_drv, and
92 sqlite_drv) allow an open database handle to be attached. This function
93 should only be called after an initial call to dspam_create() and
94 should never be called if using dspam_init(), as storage is automati‐
95 cally attached by a call to dspam_init().
96 The dspam_process() function performs analysis of the message passed
98 into it and will return zero on successful completion. If successful,
99 CTX->result will be set to one of three classification results:
100 DSR_ISSPAM Message was classified as spam
102 DSR_ISINNOCENT Message was classified as nonspam
103 DSR_ISWHITELISTED Recipient was automatically whitelisted
104 Should the call fail, one of the following errors will be returned:
106 EINVAL An invalid call or invalid parameter used.
108 EUNKNOWN Unexpected error, such as malloc() failure
109 EFILE Error opening or writing to a file or file handle
110 ELOCK Locking failure
111 EFAILURE The operation itself has failed
112 The dspam_getsource() function extracts the source sender from the mes‐
114 sage passed in during a call to dspam_process() and writes not more
115 than size bytes to buf.
116 The dspam_detach() function can be called when a detachment from stor‐
118 age is desired, but the context is still needed. The storage driver is
119 closed, leaving the classification context in place. Once the context
120 is no longer needed, another call to dspam_destroy() should be made. If
121 you are closing storage and destroying the context at the same time, it
122 is not necessary to call this function. Instead you may call
123 dspam_destroy() directly.
124 The dspam_clearattributes() function is called to clear any attributes
126 previously set using dspam_addattribute() within the classification
127 context. It is necessary to call this function prior to replacing any
128 attributes already written.
129 The dspam_destroy() function should be called when the context is no
131 longer needed. If a connection was established to storage internally,
132 the connection is closed and all data is flushed and written. If a han‐
133 dle was attached, the handle will remain open.
134
136 Copyright © 2002-2012 DSPAM Project
137 All rights reserved.
138 For more information, see http://dspam.sourceforge.net.
140
143 dspam(1), dspam_admin(1), dspam_clean(1), dspam_crc(1), dspam_dump(1),
144 dspam_logrotate(1), dspam_merge(1), dspam_stats(1), dspam_train(1)
145libdspam Apr 17, 2010 libdspam(3)