1libdspam(3)                        libdspam                        libdspam(3)
2
3
4

NAME

6       libdspam - Core message processing and classification library for DSPAM
7
8       DSPAM Core Analyis Engine Functions
9
10

SYNOPSIS

12       #include <libdspam.h>
13
14       DSPAM_CTX *dspam_init(const char *username, const char *group,
15         const char *home, int operating_mode, u_int32_t flags);
16
17       DSPAM_CTX *dspam_create(const char *username, const char *group,
18         const char *home, int operating_mode, u_int32_t flags);
19
20       int dspam_addattribute(DSPAM_CTX *CTX, const char *key,
21         const char *value);
22
23       int dspam_clearattributes(DSPAM_CTX *CTX);
24
25       int dspam_attach(DSPAM_CTX *CTX, void *dbh);
26
27       int dspam_process(DSPAM_CTX *CTX, const char *message);
28
29       int dspam_getsource(DSPAM_CTX *CTX, char *buf, size_t size);
30
31       int dspam_detach(DSPAM_CTX *CTX);
32
33       int dspam_destroy(DSPAM_CTX *CTX);
34

DESCRIPTION

36       libdspam  provides core message processing and classification function‐
37       ality.
38
39       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
47        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
53       The flags provided further tune the classification context for  a  spe‐
54       cific function. Multiple flags may be OR'd together.
55
56        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
63       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
68       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
75       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
80        IgnoreHeader   Specify a specific header to ignore
81        LocalMX        Specify a local mail exchanger to assist in
82                       correct results from dspam_getsource().
83
84       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
88       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
97       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
101        DSR_ISSPAM        Message was classified as spam
102        DSR_ISINNOCENT    Message was classified as nonspam
103        DSR_ISWHITELISTED Recipient was automatically whitelisted
104
105       Should the call fail, one of the following errors will be returned:
106
107        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
113       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
117       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
125       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
130       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-2011 DSPAM Project
137       All rights reserved.
138
139       For more information, see http://dspam.sourceforge.net.
140
141

SEE ALSO

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)
145
146
147
148libdspam                         Apr 17, 2010                      libdspam(3)
Impressum