Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_ArchiveIterator.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_ArchiveIterator.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_ArchiveIterator.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_ArchiveIterator.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,186 @@
+NAME
+ Mail::SpamAssassin::ArchiveIterator - find and process messages one at a
+ time
+
+SYNOPSIS
+ my $iter = Mail::SpamAssassin::ArchiveIterator->new(
+ {
+ 'opt_max_size' => 500 * 1024, # 0 implies no limit
+ 'opt_cache' => 1,
+ }
+ );
+
+ $iter->set_functions( \&wanted, sub { } );
+
+ eval { $iter->run(@ARGV); };
+
+ sub wanted {
+ my($class, $filename, $recv_date, $msg_array) = @_;
+
+
+ ...
+ }
+
+DESCRIPTION
+ The Mail::SpamAssassin::ArchiveIterator module will go through a set of
+ mbox files, mbx files, and directories (with a single message per file)
+ and generate a list of messages. It will then call the "wanted_sub" and
+ "result_sub" functions appropriately per message.
+
+METHODS
+ $item = Mail::SpamAssassin::ArchiveIterator->new( [ { opt => val, ... }
+ ] )
+ Constructs a new "Mail::SpamAssassin::ArchiveIterator" object. You
+ may pass the following attribute-value pairs to the constructor. The
+ pairs are optional unless otherwise noted.
+
+ opt_max_size
+ A value of option *opt_max_size* determines a limit (number of
+ bytes) beyond which a message is considered large and is skipped
+ by ArchiveIterator.
+
+ A value 0 implies no size limit, all messages are examined. An
+ undefined value implies a default limit of 500 KiB.
+
+ opt_all
+ Setting this option to true implicitly sets *opt_max_size* to 0,
+ i.e. no limit of a message size, all messages are processes by
+ ArchiveIterator. For compatibility with SpamAssassin versions
+ older than 3.4.0 which lacked option *opt_max_size*.
+
+ opt_scanprob
+ Randomly select messages to scan, with a probability of N, where
+ N ranges from 0.0 (no messages scanned) to 1.0 (all messages
+ scanned). Default is 1.0.
+
+ This setting can be specified separately for each target.
+
+ opt_before
+ Only use messages which are received after the given time_t
+ value. Negative values are an offset from the current time, e.g.
+ -86400 = last 24 hours; or as parsed by Time::ParseDate (e.g.
+ '-6 months')
+
+ This setting can be specified separately for each target.
+
+ opt_after
+ Same as opt_before, except the messages are only used if after
+ the given time_t value.
+
+ This setting can be specified separately for each target.
+
+ opt_want_date
+ Set to 1 (default) if you want the received date to be filled in
+ in the "wanted_sub" callback below. Set this to 0 to avoid this;
+ it's a good idea to set this to 0 if you can, as it imposes a
+ performance hit.
+
+ opt_skip_empty_messages
+ Set to 1 if you want to skip corrupt, 0-byte messages. The
+ default is 0.
+
+ opt_cache
+ Set to 0 (default) if you don't want to use cached information
+ to help speed up ArchiveIterator. Set to 1 to enable. This
+ setting requires "opt_cachedir" also be set.
+
+ opt_cachedir
+ Set to the path of a directory where you wish to store cached
+ information for "opt_cache", if you don't want to mix them with
+ the input files (as is the default). The directory must be both
+ readable and writable.
+
+ wanted_sub
+ Reference to a subroutine which will process message data.
+ Usually set via set_functions(). The routine will be passed 5
+ values: class (scalar), filename (scalar), received date
+ (scalar), message content (array reference, one message line per
+ element), and the message format key ('f' for file, 'm' for
+ mbox, 'b' for mbx).
+
+ Note that if "opt_want_date" is set to 0, the received date
+ scalar will be undefined.
+
+ result_sub
+ Reference to a subroutine which will process the results of the
+ wanted_sub for each message processed. Usually set via
+ set_functions(). The routine will be passed 3 values: class
+ (scalar), result (scalar, returned from wanted_sub), and
+ received date (scalar).
+
+ Note that if "opt_want_date" is set to 0, the received date
+ scalar will be undefined.
+
+ scan_progress_sub
+ Reference to a subroutine which will be called intermittently
+ during the 'scan' phase of the mass-check. No guarantees are
+ made as to how frequently this may happen, mind you.
+
+ opt_from_regex
+ This setting allows for flexibility in specifying the mbox
+ format From separator.
+
+ It defaults to the regular expression:
+
+ /^From \S+ ?(\S\S\S \S\S\S .?\d .?\d:\d\d:\d\d
+ \d{4}|.?\d-\d\d-\d{4}_\d\d:\d\d:\d\d_)/
+
+ Some SpamAssassin programs such as sa-learn will use the
+ configuration option 'mbox_format_from_regex' to override the
+ default regular expression.
+
+ set_functions( \&wanted_sub, \&result_sub )
+ Sets the subroutines used for message processing (wanted_sub), and
+ result reporting. For more information, see *new()* above.
+
+ run ( @target_paths )
+ Generates the list of messages to process, then runs each message
+ through the configured wanted subroutine.
+
+ Compressed files are detected and uncompressed automatically
+ regardless of file extension. Supported formats are "gzip", "bzip2",
+ "xz", "lz4", "lzip", "lzo". Gzip is uncompressed via IO::Zlib
+ module, others use their specific command line tool
+ (bzip2/xz/lz4/lzip/lzop). Compressed mailbox/mbox files are not
+ supported.
+
+ The target_paths array is expected to be either one element per path
+ in the following format: "class:format:raw_location", or a hash
+ reference containing key-value option pairs and a 'target' key with
+ a value in that format.
+
+ The key-value option pairs that can be used are: opt_scanprob,
+ opt_after, opt_before. See the constructor method's documentation
+ for more information on their effects.
+
+ run() returns 0 if there was an error (can't open a file, etc,) and
+ 1 if there were no errors.
+
+ class
+ Either 'h' for ham or 's' for spam. If the class is longer than
+ 1 character, it will be truncated. If blank, 'h' is default.
+
+ format
+ Specifies the format of the raw_location. "dir" is a directory
+ whose files are individual messages, "file" a file with a single
+ message, "mbox" an mbox formatted file, or "mbx" for an mbx
+ formatted directory.
+
+ "detect" can also be used. This assumes "mbox" for any file
+ whose path contains the pattern "/\.mbox/i", "file" anything
+ that is not a directory, or "directory" otherwise.
+
+ raw_location
+ Path to file or directory. File globbing is allowed using the
+ standard csh-style globbing (see "perldoc -f glob"). "~" at the
+ front of the value will be replaced by the "HOME" environment
+ variable. Escaped whitespace is protected as well.
+
+ NOTE: "~user" is not allowed.
+
+ NOTE 2: "-" is not allowed as a raw location. To have
+ ArchiveIterator deal with STDIN, generate a temp file.
+
+SEE ALSO
+ Mail::SpamAssassin(3) spamassassin(1) mass-check(1)
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,197 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+ <li><a href="#METHODS">METHODS</a></li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop</p>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>An asynchronous event loop used for long-running operations, performed "in the background" during the Mail::SpamAssassin::check() scan operation, such as DNS blocklist lookups.</p>
+
+<h1 id="METHODS">METHODS</h1>
+
+<dl>
+
+<dt id="ent-async-bgsend_and_start_lookup-name-type-class-ent-cb-options">$ent = $async->bgsend_and_start_lookup($name, $type, $class, $ent, $cb, %options)</dt>
+<dd>
+
+<p>Launch async DNS lookups. This is the only official method supported for plugins since version 4.0.0. Do not use bgsend and start_lookup separately.</p>
+
+<p>Merges duplicate queries automatically, only launches one and calls all related callbacks on answer.</p>
+
+<dl>
+
+<dt id="name-required">$name (required)</dt>
+<dd>
+
+<p>Name to query.</p>
+
+</dd>
+<dt id="type-required">$type (required)</dt>
+<dd>
+
+<p>Type to query, A, TXT, NS, etc.</p>
+
+</dd>
+<dt id="class-required-deprecated">$class (required/deprecated)</dt>
+<dd>
+
+<p>Deprecated, ignored, set as undef.</p>
+
+</dd>
+<dt id="ent-is-a-required-hash-reference-containing-the-following-items"><code>$ent</code> is a required hash reference containing the following items:</dt>
+<dd>
+
+<dl>
+
+<dt id="ent--rulename-required">$ent->{rulename} (required)</dt>
+<dd>
+
+<p>The rulename that started and/or depends on this query. Required for rule dependencies to work correctly. Can be a single rulename, or array of multiple rulenames.</p>
+
+</dd>
+<dt id="ent--type-optional">$ent->{type} (optional)</dt>
+<dd>
+
+<p>A string, typically one word, used to describe the type of lookup in log messages, such as <code>DNSBL</code>, <code>URIBL-A</code>. If not defined, default is value of $type.</p>
+
+</dd>
+<dt id="ent--zone-optional">$ent->{zone} (optional)</dt>
+<dd>
+
+<p>A zone specification (typically a DNS zone name - e.g. host, domain, or RBL) which may be used as a key to look up per-zone settings. No semantics on this parameter is imposed by this module. Currently used to fetch by-zone timeouts (from rbl_timeout setting). Defaults to $name.</p>
+
+</dd>
+<dt id="ent--timeout_initial-optional">$ent->{timeout_initial} (optional)</dt>
+<dd>
+
+<p>An initial value of elapsed time for which we are willing to wait for a response (time in seconds, floating point value is allowed). When elapsed time since a query started exceeds the timeout value and there are no other queries to wait for, the query is aborted. The actual timeout value ranges from timeout_initial and gradually approaches timeout_min (see next parameter) as the number of already completed queries approaches the number of all queries started.</p>
+
+<p>If a caller does not explicitly provide this parameter or its value is undefined, a default initial timeout value is settable by a configuration variable rbl_timeout.</p>
+
+<p>If a value of the timeout_initial parameter is below timeout_min, the initial timeout is set to timeout_min.</p>
+
+</dd>
+<dt id="ent--timeout_min-optional">$ent->{timeout_min} (optional)</dt>
+<dd>
+
+<p>A lower bound (in seconds) to which the actual timeout approaches as the number of queries completed approaches the number of all queries started. Defaults to 0.2 * timeout_initial.</p>
+
+</dd>
+<dt id="ent--key-ent--id-deprecated">$ent->{key}, $ent->{id} (deprecated)</dt>
+<dd>
+
+<p>Deprecated, ignored, automatically generated since 4.0.0.</p>
+
+</dd>
+<dt id="ent--YOUR_OWN_ITEM">$ent->{YOUR_OWN_ITEM}</dt>
+<dd>
+
+<p>Any other custom values/objects that you want to pass on to the answer callback.</p>
+
+</dd>
+</dl>
+
+</dd>
+<dt id="cb-required">$cb (required)</dt>
+<dd>
+
+<p>Callback function for answer, called as $cb->($ent, $pkt). <code>$ent</code> is the same object that bgsend_and_start_lookup was called with. <code>$pkt</code> is the packet object for the response, Net::DNS:RR objects can be found from $pkt->answer.</p>
+
+</dd>
+<dt id="options-required">%options (required)</dt>
+<dd>
+
+<p>Hash of options. Only supported and required option is master_deadline:</p>
+
+<pre><code>master_deadline => $pms->{master_deadline}</code></pre>
+
+</dd>
+</dl>
+
+</dd>
+<dt id="ent-async-start_lookup-ent-master_deadline">$ent = $async->start_lookup($ent, $master_deadline)</dt>
+<dd>
+
+<p>DIRECT USE DEPRECATED since 4.0.0, please use bgsend_and_start_lookup.</p>
+
+</dd>
+<dt id="ent-async-get_lookup-key">$ent = $async->get_lookup($key)</dt>
+<dd>
+
+<p>DEPRECATED since 4.0.0. Do not use.</p>
+
+</dd>
+<dt id="async-log_lookups_timing">$async->log_lookups_timing()</dt>
+<dd>
+
+<p>Log sorted timing for all completed lookups.</p>
+
+</dd>
+<dt id="alldone-async-complete_lookups">$alldone = $async->complete_lookups()</dt>
+<dd>
+
+<p>Perform a poll of the pending lookups, to see if any are completed. Callbacks on completed queries will be called from poll_responses().</p>
+
+<p>If there are no lookups remaining, or if too much time has elapsed since any results were returned, <code>1</code> is returned, otherwise <code>0</code>.</p>
+
+</dd>
+<dt id="async-abort_remaining_lookups">$async->abort_remaining_lookups()</dt>
+<dd>
+
+<p>Abort any remaining lookups.</p>
+
+</dd>
+<dt id="async-set_response_packet-id-pkt-key-timestamp">$async->set_response_packet($id, $pkt, $key, $timestamp)</dt>
+<dd>
+
+<p>For internal use, do not call from plugins.</p>
+
+<p>Register a "response packet" for a given query. <code>$id</code> is the ID for the query, and must match the <code>id</code> supplied in <code>start_lookup()</code>. <code>$pkt</code> is the packet object for the response. A parameter <code>$key</code> identifies an entry in a hash %{$self->{pending_lookups}} where the object which spawned this query can be found, and through which further information about the query is accessible.</p>
+
+<p><code>$pkt</code> may be undef, indicating that no response packet is available, but a query has completed (e.g. was aborted or dismissed) and is no longer "pending".</p>
+
+<p>The DNS resolver's response packet <code>$pkt</code> will be made available to a callback subroutine through its argument as well as in <code>$ent->{response_packet}</code>.</p>
+
+</dd>
+<dt id="async-report_id_complete-id-key-key-timestamp">$async->report_id_complete($id,$key,$key,$timestamp)</dt>
+<dd>
+
+<p>DEPRECATED since 4.0.0. Do not use.</p>
+
+<p>Legacy. Equivalent to $self->set_response_packet($id,undef,$key,$timestamp), i.e. providing undef as a response packet. Register that a query has completed and is no longer "pending". <code>$id</code> is the ID for the query, and must match the <code>id</code> supplied in <code>start_lookup()</code>.</p>
+
+<p>One or the other of <code>set_response_packet()</code> or <code>report_id_complete()</code> should be called, but not both.</p>
+
+</dd>
+<dt id="time-async-last_poll_responses_time">$time = $async->last_poll_responses_time()</dt>
+<dd>
+
+<p>Get the time of the last call to <code>poll_responses()</code> (which is called from <code>complete_lookups()</code>. If <code>poll_responses()</code> was never called or <code>abort_remaining_lookups()</code> has been called <code>last_poll_responses_time()</code> will return undef.</p>
+
+</dd>
+</dl>
+
+
+</body>
+
+</html>
+
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,144 @@
+NAME
+ Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop
+
+DESCRIPTION
+ An asynchronous event loop used for long-running operations, performed
+ "in the background" during the Mail::SpamAssassin::check() scan
+ operation, such as DNS blocklist lookups.
+
+METHODS
+ $ent = $async->bgsend_and_start_lookup($name, $type, $class, $ent, $cb,
+ %options)
+ Launch async DNS lookups. This is the only official method supported
+ for plugins since version 4.0.0. Do not use bgsend and start_lookup
+ separately.
+
+ Merges duplicate queries automatically, only launches one and calls
+ all related callbacks on answer.
+
+ $name (required)
+ Name to query.
+
+ $type (required)
+ Type to query, A, TXT, NS, etc.
+
+ $class (required/deprecated)
+ Deprecated, ignored, set as undef.
+
+ $ent is a required hash reference containing the following items:
+
+ $ent->{rulename} (required)
+ The rulename that started and/or depends on this query.
+ Required for rule dependencies to work correctly. Can be a
+ single rulename, or array of multiple rulenames.
+
+ $ent->{type} (optional)
+ A string, typically one word, used to describe the type of
+ lookup in log messages, such as "DNSBL", "URIBL-A". If not
+ defined, default is value of $type.
+
+ $ent->{zone} (optional)
+ A zone specification (typically a DNS zone name - e.g. host,
+ domain, or RBL) which may be used as a key to look up
+ per-zone settings. No semantics on this parameter is imposed
+ by this module. Currently used to fetch by-zone timeouts
+ (from rbl_timeout setting). Defaults to $name.
+
+ $ent->{timeout_initial} (optional)
+ An initial value of elapsed time for which we are willing to
+ wait for a response (time in seconds, floating point value
+ is allowed). When elapsed time since a query started exceeds
+ the timeout value and there are no other queries to wait
+ for, the query is aborted. The actual timeout value ranges
+ from timeout_initial and gradually approaches timeout_min
+ (see next parameter) as the number of already completed
+ queries approaches the number of all queries started.
+
+ If a caller does not explicitly provide this parameter or
+ its value is undefined, a default initial timeout value is
+ settable by a configuration variable rbl_timeout.
+
+ If a value of the timeout_initial parameter is below
+ timeout_min, the initial timeout is set to timeout_min.
+
+ $ent->{timeout_min} (optional)
+ A lower bound (in seconds) to which the actual timeout
+ approaches as the number of queries completed approaches the
+ number of all queries started. Defaults to 0.2 *
+ timeout_initial.
+
+ $ent->{key}, $ent->{id} (deprecated)
+ Deprecated, ignored, automatically generated since 4.0.0.
+
+ $ent->{YOUR_OWN_ITEM}
+ Any other custom values/objects that you want to pass on to
+ the answer callback.
+
+ $cb (required)
+ Callback function for answer, called as $cb->($ent, $pkt). $ent
+ is the same object that bgsend_and_start_lookup was called with.
+ $pkt is the packet object for the response, Net::DNS:RR objects
+ can be found from $pkt->answer.
+
+ %options (required)
+ Hash of options. Only supported and required option is
+ master_deadline:
+
+ master_deadline => $pms->{master_deadline}
+
+ $ent = $async->start_lookup($ent, $master_deadline)
+ DIRECT USE DEPRECATED since 4.0.0, please use
+ bgsend_and_start_lookup.
+
+ $ent = $async->get_lookup($key)
+ DEPRECATED since 4.0.0. Do not use.
+
+ $async->log_lookups_timing()
+ Log sorted timing for all completed lookups.
+
+ $alldone = $async->complete_lookups()
+ Perform a poll of the pending lookups, to see if any are completed.
+ Callbacks on completed queries will be called from poll_responses().
+
+ If there are no lookups remaining, or if too much time has elapsed
+ since any results were returned, 1 is returned, otherwise 0.
+
+ $async->abort_remaining_lookups()
+ Abort any remaining lookups.
+
+ $async->set_response_packet($id, $pkt, $key, $timestamp)
+ For internal use, do not call from plugins.
+
+ Register a "response packet" for a given query. $id is the ID for
+ the query, and must match the "id" supplied in "start_lookup()".
+ $pkt is the packet object for the response. A parameter $key
+ identifies an entry in a hash %{$self->{pending_lookups}} where the
+ object which spawned this query can be found, and through which
+ further information about the query is accessible.
+
+ $pkt may be undef, indicating that no response packet is available,
+ but a query has completed (e.g. was aborted or dismissed) and is no
+ longer "pending".
+
+ The DNS resolver's response packet $pkt will be made available to a
+ callback subroutine through its argument as well as in
+ "$ent->{response_packet}".
+
+ $async->report_id_complete($id,$key,$key,$timestamp)
+ DEPRECATED since 4.0.0. Do not use.
+
+ Legacy. Equivalent to
+ $self->set_response_packet($id,undef,$key,$timestamp), i.e.
+ providing undef as a response packet. Register that a query has
+ completed and is no longer "pending". $id is the ID for the query,
+ and must match the "id" supplied in "start_lookup()".
+
+ One or the other of "set_response_packet()" or
+ "report_id_complete()" should be called, but not both.
+
+ $time = $async->last_poll_responses_time()
+ Get the time of the last call to "poll_responses()" (which is called
+ from "complete_lookups()". If "poll_responses()" was never called or
+ "abort_remaining_lookups()" has been called
+ "last_poll_responses_time()" will return undef.
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,78 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::AutoWelcomelist - auto-welcomelist handler for SpamAssassin</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+ <li><a href="#METHODS">METHODS</a></li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::AutoWelcomelist - auto-welcomelist handler for SpamAssassin</p>
+
+<h1 id="SYNOPSIS">SYNOPSIS</h1>
+
+<pre><code>(see Mail::SpamAssassin)</code></pre>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>Mail::SpamAssassin is a module to identify spam using text analysis and several internet-based realtime blocklists.</p>
+
+<p>This class is used internally by SpamAssassin to manage the automatic welcomelisting functionality. Please refer to the <code>Mail::SpamAssassin</code> documentation for public interfaces.</p>
+
+<h1 id="METHODS">METHODS</h1>
+
+<dl>
+
+<dt id="meanscore-awl-check_address-addr-originating_ip-signedby">$meanscore = awl->check_address($addr, $originating_ip, $signedby);</dt>
+<dd>
+
+<p>This method will return the mean score of all messages associated with the given address, or undef if the address hasn't been seen before.</p>
+
+<p>If <b>$originating_ip</b> is supplied, it will be used in the lookup.</p>
+
+</dd>
+<dt id="awl-count">awl->count();</dt>
+<dd>
+
+<p>This method will return the count of messages used in determining the welcomelist correction.</p>
+
+</dd>
+<dt id="awl-add_score-score">awl->add_score($score);</dt>
+<dd>
+
+<p>This method will add half the score to the current entry. Half the score is used, so that repeated use of the same From and IP address combination will gradually reduce the score.</p>
+
+</dd>
+<dt id="awl-add_known_good_address-addr">awl->add_known_good_address($addr);</dt>
+<dd>
+
+<p>This method will add a score of -100 to the given address -- effectively "bootstrapping" the address as being one that should be welcomelisted.</p>
+
+</dd>
+<dt id="awl-add_known_bad_address-addr">awl->add_known_bad_address($addr);</dt>
+<dd>
+
+<p>This method will add a score of 100 to the given address -- effectively "bootstrapping" the address as being one that should be blocklisted.</p>
+
+</dd>
+</dl>
+
+
+</body>
+
+</html>
+
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,42 @@
+NAME
+ Mail::SpamAssassin::AutoWelcomelist - auto-welcomelist handler for
+ SpamAssassin
+
+SYNOPSIS
+ (see Mail::SpamAssassin)
+
+DESCRIPTION
+ Mail::SpamAssassin is a module to identify spam using text analysis and
+ several internet-based realtime blocklists.
+
+ This class is used internally by SpamAssassin to manage the automatic
+ welcomelisting functionality. Please refer to the "Mail::SpamAssassin"
+ documentation for public interfaces.
+
+METHODS
+ $meanscore = awl->check_address($addr, $originating_ip, $signedby);
+ This method will return the mean score of all messages associated
+ with the given address, or undef if the address hasn't been seen
+ before.
+
+ If $originating_ip is supplied, it will be used in the lookup.
+
+ awl->count();
+ This method will return the count of messages used in determining
+ the welcomelist correction.
+
+ awl->add_score($score);
+ This method will add half the score to the current entry. Half the
+ score is used, so that repeated use of the same From and IP address
+ combination will gradually reduce the score.
+
+ awl->add_known_good_address($addr);
+ This method will add a score of -100 to the given address --
+ effectively "bootstrapping" the address as being one that should be
+ welcomelisted.
+
+ awl->add_known_bad_address($addr);
+ This method will add a score of 100 to the given address --
+ effectively "bootstrapping" the address as being one that should be
+ blocklisted.
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,34 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::Bayes - support for learning classifiers</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::Bayes - support for learning classifiers</p>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>This is the general class used to train a learning classifier with new samples of spam and ham mail, and classify based on prior training.</p>
+
+<p>Prior to version 3.3.0, the default Bayes implementation was here; if you're looking for information on that, it has moved to <code>Mail::SpamAssassin::Plugin::Bayes</code>.</p>
+
+
+</body>
+
+</html>
+
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,11 @@
+NAME
+ Mail::SpamAssassin::Bayes - support for learning classifiers
+
+DESCRIPTION
+ This is the general class used to train a learning classifier with new
+ samples of spam and ham mail, and classify based on prior training.
+
+ Prior to version 3.3.0, the default Bayes implementation was here; if
+ you're looking for information on that, it has moved to
+ "Mail::SpamAssassin::Plugin::Bayes".
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,393 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::BayesStore - Storage Module for default Bayes classifier</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+ <li><a href="#METHODS">METHODS</a></li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::BayesStore - Storage Module for default Bayes classifier</p>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>This is the public API for the Bayesian store methods. Any implementation of the storage module for the default Bayes classifier must implement these methods.</p>
+
+<h1 id="METHODS">METHODS</h1>
+
+<dl>
+
+<dt id="new">new</dt>
+<dd>
+
+<p>public class (Mail::SpamAssassin::BayesStore) new (Mail::SpamAssassin::Plugin::Bayes $bayes)</p>
+
+<p>Description: This method creates a new instance of the Mail::SpamAssassin::BayesStore object. You must pass in an instance of the Mail::SpamAssassin::Plugin::Bayes object, which is stashed for use throughout the module.</p>
+
+</dd>
+<dt id="DB_VERSION">DB_VERSION</dt>
+<dd>
+
+<p>public instance (Integer) DB_VERSION ()</p>
+
+<p>Description: This method returns the currently supported database version for the implementation.</p>
+
+</dd>
+<dt id="read_db_configs">read_db_configs</dt>
+<dd>
+
+<p>public instance () read_db_configs ()</p>
+
+<p>Description: This method reads any needed config variables from the configuration object and then calls the Mail::SpamAssassin::Plugin::Bayes read_db_configs method.</p>
+
+</dd>
+<dt id="prefork_init">prefork_init</dt>
+<dd>
+
+<p>public instance (Boolean) prefork_init ()</p>
+
+<p>Description: This optional method is called in the parent process shortly before forking off child processes.</p>
+
+</dd>
+<dt id="spamd_child_init">spamd_child_init</dt>
+<dd>
+
+<p>public instance (Boolean) spamd_child_init ()</p>
+
+<p>Description: This optional method is called in a child process shortly after being spawned.</p>
+
+</dd>
+<dt id="tie_db_readonly">tie_db_readonly</dt>
+<dd>
+
+<p>public instance (Boolean) tie_db_readonly ()</p>
+
+<p>Description: This method opens up the database in readonly mode.</p>
+
+</dd>
+<dt id="tie_db_writable">tie_db_writable</dt>
+<dd>
+
+<p>public instance (Boolean) tie_db_writable ()</p>
+
+<p>Description: This method opens up the database in writable mode.</p>
+
+<p>Any callers of this methods should ensure that they call untie_db() afterwards.</p>
+
+</dd>
+<dt id="untie_db">untie_db</dt>
+<dd>
+
+<p>public instance () untie_db ()</p>
+
+<p>Description: This method unties the database.</p>
+
+</dd>
+<dt id="calculate_expire_delta">calculate_expire_delta</dt>
+<dd>
+
+<p>public instance (%) calculate_expire_delta (Integer $newest_atime, Integer $start, Integer $max_expire_mult)</p>
+
+<p>Description: This method performs a calculation on the data to determine the optimum atime for token expiration.</p>
+
+</dd>
+<dt id="token_expiration">token_expiration</dt>
+<dd>
+
+<p>public instance (Integer, Integer, Integer, Integer) token_expiration(\% $opts, Integer $newest_atime, Integer $newdelta)</p>
+
+<p>Description: This method performs the database specific expiration of tokens based on the passed in <code>$newest_atime</code> and <code>$newdelta</code>.</p>
+
+</dd>
+<dt id="expire_old_tokens">expire_old_tokens</dt>
+<dd>
+
+<p>public instance (Boolean) expire_old_tokens (\% hashref)</p>
+
+<p>Description: This method expires old tokens from the database.</p>
+
+</dd>
+<dt id="expire_old_tokens_trapped">expire_old_tokens_trapped</dt>
+<dd>
+
+<p>public instance (Boolean) expire_old_tokens_trapped (\% $opts)</p>
+
+<p>Description: This methods does the actual token expiration.</p>
+
+<p>XXX More docs here about the methodology and what not</p>
+
+</dd>
+<dt id="sync_due">sync_due</dt>
+<dd>
+
+<p>public instance (Boolean) sync_due ()</p>
+
+<p>Description: This methods determines if a sync is due.</p>
+
+</dd>
+<dt id="expiry_due">expiry_due</dt>
+<dd>
+
+<p>public instance (Boolean) expiry_due ()</p>
+
+<p>Description: This methods determines if an expire is due.</p>
+
+</dd>
+<dt id="seen_get">seen_get</dt>
+<dd>
+
+<p>public instance (Char) seen_get (String $msgid)</p>
+
+<p>Description: This method retrieves the stored value, if any, for <code>$msgid</code>. The return value is the stored string ('s' for spam and 'h' for ham) or undef if <code>$msgid</code> is not found.</p>
+
+</dd>
+<dt id="seen_put">seen_put</dt>
+<dd>
+
+<p>public instance (Boolean) seen_put (String $msgid, Char $flag)</p>
+
+<p>Description: This method records <code>$msgid</code> as the type given by <code>$flag</code>. <code>$flag</code> is one of two values 's' for spam and 'h' for ham.</p>
+
+</dd>
+<dt id="seen_delete">seen_delete</dt>
+<dd>
+
+<p>public instance (Boolean) seen_delete (String $msgid)</p>
+
+<p>Description: This method removes <code>$msgid</code> from storage.</p>
+
+</dd>
+<dt id="get_storage_variables">get_storage_variables</dt>
+<dd>
+
+<p>public instance (@) get_storage_variables ()</p>
+
+<p>Description: This method retrieves the various administrative variables used by the Bayes storage implementation.</p>
+
+<p>The values returned in the array are in the following order:</p>
+
+<p>0: scan count base</p>
+
+<p>1: number of spam</p>
+
+<p>2: number of ham</p>
+
+<p>3: number of tokens in db</p>
+
+<p>4: last expire atime</p>
+
+<p>5: oldest token in db atime</p>
+
+<p>6: db version value</p>
+
+<p>7: last journal sync</p>
+
+<p>8: last atime delta</p>
+
+<p>9: last expire reduction count</p>
+
+<p>10: newest token in db atime</p>
+
+</dd>
+<dt id="dump_db_toks">dump_db_toks</dt>
+<dd>
+
+<p>public instance () dump_db_toks (String $template, String $regex, @ @vars)</p>
+
+<p>Description: This method loops over all tokens, computing the probability for the token and then printing it out according to the passed in template.</p>
+
+</dd>
+<dt id="set_last_expire">set_last_expire</dt>
+<dd>
+
+<p>public instance (Boolean) _set_last_expire (Integer $time)</p>
+
+<p>Description: This method sets the last expire time.</p>
+
+</dd>
+<dt id="get_running_expire_tok">get_running_expire_tok</dt>
+<dd>
+
+<p>public instance (Time) get_running_expire_tok ()</p>
+
+<p>Description: This method determines if an expire is currently running and returns the time the expire started.</p>
+
+</dd>
+<dt id="set_running_expire_tok">set_running_expire_tok</dt>
+<dd>
+
+<p>public instance (Time) set_running_expire_tok ()</p>
+
+<p>Description: This method sets the running expire time to the current time.</p>
+
+</dd>
+<dt id="remove_running_expire_tok">remove_running_expire_tok</dt>
+<dd>
+
+<p>public instance (Boolean) remove_running_expire_tok ()</p>
+
+<p>Description: This method removes a currently set running expire time.</p>
+
+</dd>
+<dt id="tok_get">tok_get</dt>
+<dd>
+
+<p>public instance (Integer, Integer, Time) tok_get (String $token)</p>
+
+<p>Description: This method retrieves the specified token (<code>$token</code>) from storage and returns it's spam count, ham count and last access time.</p>
+
+</dd>
+<dt id="tok_get_all">tok_get_all</dt>
+<dd>
+
+<p>public instance (\@) tok_get_all (@ @tokens)</p>
+
+<p>Description: This method retrieves the specified tokens (<code>@tokens</code>) from storage and returns an array ref of arrays spam count, ham count and last access time.</p>
+
+</dd>
+<dt id="tok_count_change">tok_count_change</dt>
+<dd>
+
+<p>public instance (Boolean) tok_count_change (Integer $spam_count, Integer $ham_count, String $token, Time $atime)</p>
+
+<p>Description: This method takes a <code>$spam_count</code> and <code>$ham_count</code> and adds it to <code>$token</code> along with updating <code>$token</code>s atime with <code>$atime</code>.</p>
+
+</dd>
+<dt id="multi_tok_count_change">multi_tok_count_change</dt>
+<dd>
+
+<p>public instance (Boolean) multi_tok_count_change (Integer $spam_count, Integer $ham_count, \% $tokens, String $atime)</p>
+
+<p>Description: This method takes a <code>$spam_count</code> and <code>$ham_count</code> and adds it to all of the tokens in the <code>$tokens</code> hash ref along with updating each tokens atime with <code>$atime</code>.</p>
+
+</dd>
+<dt id="nspam_nham_get">nspam_nham_get</dt>
+<dd>
+
+<p>public instance (Integer, Integer) nspam_nham_get ()</p>
+
+<p>Description: This method retrieves the total number of spam and the total number of ham currently under storage.</p>
+
+</dd>
+<dt id="nspam_nham_change">nspam_nham_change</dt>
+<dd>
+
+<p>public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer $num_ham)</p>
+
+<p>Description: This method updates the number of spam and the number of ham in the database.</p>
+
+</dd>
+<dt id="tok_touch">tok_touch</dt>
+<dd>
+
+<p>public instance (Boolean) tok_touch (String $token, Time $atime)</p>
+
+<p>Description: This method updates the given tokens (<code>$token</code>) access time.</p>
+
+</dd>
+<dt id="tok_touch_all">tok_touch_all</dt>
+<dd>
+
+<p>public instance (Boolean) tok_touch_all (\@ $tokens, Time $atime)</p>
+
+<p>Description: This method does a mass update of the given list of tokens <code>$tokens</code>, if the existing token atime is < <code>$atime</code>.</p>
+
+</dd>
+<dt id="cleanup">cleanup</dt>
+<dd>
+
+<p>public instance (Boolean) cleanup ()</p>
+
+<p>Description: This method performs any cleanup necessary before moving onto the next operation.</p>
+
+</dd>
+<dt id="get_magic_re">get_magic_re</dt>
+<dd>
+
+<p>public instance get_magic_re (String)</p>
+
+<p>Description: This method returns a regexp which indicates a magic token.</p>
+
+</dd>
+<dt id="sync">sync</dt>
+<dd>
+
+<p>public instance (Boolean) sync (\% $opts)</p>
+
+<p>Description: This method performs a sync of the database.</p>
+
+</dd>
+<dt id="perform_upgrade">perform_upgrade</dt>
+<dd>
+
+<p>public instance (Boolean) perform_upgrade (\% $opts)</p>
+
+<p>Description: This method is a utility method that performs any necessary upgrades between versions. It should know how to handle previous versions and what needs to happen to upgrade them.</p>
+
+<p>A true return value indicates success.</p>
+
+</dd>
+<dt id="clear_database">clear_database</dt>
+<dd>
+
+<p>public instance (Boolean) clear_database ()</p>
+
+<p>Description: This method deletes all records for a particular user.</p>
+
+<p>Callers should be aware that any errors returned by this method could causes the database to be inconsistent for the given user.</p>
+
+</dd>
+<dt id="backup_database">backup_database</dt>
+<dd>
+
+<p>public instance (Boolean) backup_database ()</p>
+
+<p>Description: This method will dump the users database in a machine readable format.</p>
+
+</dd>
+<dt id="restore_database">restore_database</dt>
+<dd>
+
+<p>public instance (Boolean) restore_database (String $filename, Boolean $showdots)</p>
+
+<p>Description: This method restores a database from the given filename, <code>$filename</code>.</p>
+
+<p>Callers should be aware that any errors returned by this method could causes the database to be inconsistent for the given user.</p>
+
+</dd>
+<dt id="db_readable">db_readable</dt>
+<dd>
+
+<p>public instance (Boolean) db_readable ()</p>
+
+<p>Description: This method returns whether or not the Bayes DB is available in a readable state.</p>
+
+</dd>
+<dt id="db_writable">db_writable</dt>
+<dd>
+
+<p>public instance (Boolean) db_writable ()</p>
+
+<p>Description: This method returns whether or not the Bayes DB is available in a writable state.</p>
+
+</dd>
+</dl>
+
+
+</body>
+
+</html>
+
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,291 @@
+NAME
+ Mail::SpamAssassin::BayesStore - Storage Module for default Bayes
+ classifier
+
+DESCRIPTION
+ This is the public API for the Bayesian store methods. Any
+ implementation of the storage module for the default Bayes classifier
+ must implement these methods.
+
+METHODS
+ new public class (Mail::SpamAssassin::BayesStore) new
+ (Mail::SpamAssassin::Plugin::Bayes $bayes)
+
+ Description: This method creates a new instance of the
+ Mail::SpamAssassin::BayesStore object. You must pass in an instance
+ of the Mail::SpamAssassin::Plugin::Bayes object, which is stashed
+ for use throughout the module.
+
+ DB_VERSION
+ public instance (Integer) DB_VERSION ()
+
+ Description: This method returns the currently supported database
+ version for the implementation.
+
+ read_db_configs
+ public instance () read_db_configs ()
+
+ Description: This method reads any needed config variables from the
+ configuration object and then calls the
+ Mail::SpamAssassin::Plugin::Bayes read_db_configs method.
+
+ prefork_init
+ public instance (Boolean) prefork_init ()
+
+ Description: This optional method is called in the parent process
+ shortly before forking off child processes.
+
+ spamd_child_init
+ public instance (Boolean) spamd_child_init ()
+
+ Description: This optional method is called in a child process
+ shortly after being spawned.
+
+ tie_db_readonly
+ public instance (Boolean) tie_db_readonly ()
+
+ Description: This method opens up the database in readonly mode.
+
+ tie_db_writable
+ public instance (Boolean) tie_db_writable ()
+
+ Description: This method opens up the database in writable mode.
+
+ Any callers of this methods should ensure that they call untie_db()
+ afterwards.
+
+ untie_db
+ public instance () untie_db ()
+
+ Description: This method unties the database.
+
+ calculate_expire_delta
+ public instance (%) calculate_expire_delta (Integer $newest_atime,
+ Integer $start, Integer $max_expire_mult)
+
+ Description: This method performs a calculation on the data to
+ determine the optimum atime for token expiration.
+
+ token_expiration
+ public instance (Integer, Integer, Integer, Integer)
+ token_expiration(\% $opts, Integer $newest_atime, Integer $newdelta)
+
+ Description: This method performs the database specific expiration
+ of tokens based on the passed in $newest_atime and $newdelta.
+
+ expire_old_tokens
+ public instance (Boolean) expire_old_tokens (\% hashref)
+
+ Description: This method expires old tokens from the database.
+
+ expire_old_tokens_trapped
+ public instance (Boolean) expire_old_tokens_trapped (\% $opts)
+
+ Description: This methods does the actual token expiration.
+
+ XXX More docs here about the methodology and what not
+
+ sync_due
+ public instance (Boolean) sync_due ()
+
+ Description: This methods determines if a sync is due.
+
+ expiry_due
+ public instance (Boolean) expiry_due ()
+
+ Description: This methods determines if an expire is due.
+
+ seen_get
+ public instance (Char) seen_get (String $msgid)
+
+ Description: This method retrieves the stored value, if any, for
+ $msgid. The return value is the stored string ('s' for spam and 'h'
+ for ham) or undef if $msgid is not found.
+
+ seen_put
+ public instance (Boolean) seen_put (String $msgid, Char $flag)
+
+ Description: This method records $msgid as the type given by $flag.
+ $flag is one of two values 's' for spam and 'h' for ham.
+
+ seen_delete
+ public instance (Boolean) seen_delete (String $msgid)
+
+ Description: This method removes $msgid from storage.
+
+ get_storage_variables
+ public instance (@) get_storage_variables ()
+
+ Description: This method retrieves the various administrative
+ variables used by the Bayes storage implementation.
+
+ The values returned in the array are in the following order:
+
+ 0: scan count base
+
+ 1: number of spam
+
+ 2: number of ham
+
+ 3: number of tokens in db
+
+ 4: last expire atime
+
+ 5: oldest token in db atime
+
+ 6: db version value
+
+ 7: last journal sync
+
+ 8: last atime delta
+
+ 9: last expire reduction count
+
+ 10: newest token in db atime
+
+ dump_db_toks
+ public instance () dump_db_toks (String $template, String $regex, @
+ @vars)
+
+ Description: This method loops over all tokens, computing the
+ probability for the token and then printing it out according to the
+ passed in template.
+
+ set_last_expire
+ public instance (Boolean) _set_last_expire (Integer $time)
+
+ Description: This method sets the last expire time.
+
+ get_running_expire_tok
+ public instance (Time) get_running_expire_tok ()
+
+ Description: This method determines if an expire is currently
+ running and returns the time the expire started.
+
+ set_running_expire_tok
+ public instance (Time) set_running_expire_tok ()
+
+ Description: This method sets the running expire time to the current
+ time.
+
+ remove_running_expire_tok
+ public instance (Boolean) remove_running_expire_tok ()
+
+ Description: This method removes a currently set running expire
+ time.
+
+ tok_get
+ public instance (Integer, Integer, Time) tok_get (String $token)
+
+ Description: This method retrieves the specified token ($token) from
+ storage and returns it's spam count, ham count and last access time.
+
+ tok_get_all
+ public instance (\@) tok_get_all (@ @tokens)
+
+ Description: This method retrieves the specified tokens (@tokens)
+ from storage and returns an array ref of arrays spam count, ham
+ count and last access time.
+
+ tok_count_change
+ public instance (Boolean) tok_count_change (Integer $spam_count,
+ Integer $ham_count, String $token, Time $atime)
+
+ Description: This method takes a $spam_count and $ham_count and adds
+ it to $token along with updating $tokens atime with $atime.
+
+ multi_tok_count_change
+ public instance (Boolean) multi_tok_count_change (Integer
+ $spam_count, Integer $ham_count, \% $tokens, String $atime)
+
+ Description: This method takes a $spam_count and $ham_count and adds
+ it to all of the tokens in the $tokens hash ref along with updating
+ each tokens atime with $atime.
+
+ nspam_nham_get
+ public instance (Integer, Integer) nspam_nham_get ()
+
+ Description: This method retrieves the total number of spam and the
+ total number of ham currently under storage.
+
+ nspam_nham_change
+ public instance (Boolean) nspam_nham_change (Integer $num_spam,
+ Integer $num_ham)
+
+ Description: This method updates the number of spam and the number
+ of ham in the database.
+
+ tok_touch
+ public instance (Boolean) tok_touch (String $token, Time $atime)
+
+ Description: This method updates the given tokens ($token) access
+ time.
+
+ tok_touch_all
+ public instance (Boolean) tok_touch_all (\@ $tokens, Time $atime)
+
+ Description: This method does a mass update of the given list of
+ tokens $tokens, if the existing token atime is < $atime.
+
+ cleanup
+ public instance (Boolean) cleanup ()
+
+ Description: This method performs any cleanup necessary before
+ moving onto the next operation.
+
+ get_magic_re
+ public instance get_magic_re (String)
+
+ Description: This method returns a regexp which indicates a magic
+ token.
+
+ sync
+ public instance (Boolean) sync (\% $opts)
+
+ Description: This method performs a sync of the database.
+
+ perform_upgrade
+ public instance (Boolean) perform_upgrade (\% $opts)
+
+ Description: This method is a utility method that performs any
+ necessary upgrades between versions. It should know how to handle
+ previous versions and what needs to happen to upgrade them.
+
+ A true return value indicates success.
+
+ clear_database
+ public instance (Boolean) clear_database ()
+
+ Description: This method deletes all records for a particular user.
+
+ Callers should be aware that any errors returned by this method
+ could causes the database to be inconsistent for the given user.
+
+ backup_database
+ public instance (Boolean) backup_database ()
+
+ Description: This method will dump the users database in a machine
+ readable format.
+
+ restore_database
+ public instance (Boolean) restore_database (String $filename,
+ Boolean $showdots)
+
+ Description: This method restores a database from the given
+ filename, $filename.
+
+ Callers should be aware that any errors returned by this method
+ could causes the database to be inconsistent for the given user.
+
+ db_readable
+ public instance (Boolean) db_readable ()
+
+ Description: This method returns whether or not the Bayes DB is
+ available in a readable state.
+
+ db_writable
+ public instance (Boolean) db_writable ()
+
+ Description: This method returns whether or not the Bayes DB is
+ available in a writable state.
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,330 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::BayesStore::BDB - BerkeleyDB Bayesian Storage Module Implementation</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+ <li><a href="#METHODS">METHODS</a>
+ <ul>
+ <li><a href="#new">new</a></li>
+ <li><a href="#tie_db_readonly">tie_db_readonly</a></li>
+ <li><a href="#tie_db_writable">tie_db_writable</a></li>
+ <li><a href="#open_db">_open_db</a></li>
+ <li><a href="#untie_db">untie_db</a></li>
+ <li><a href="#calculate_expire_delta">calculate_expire_delta</a></li>
+ <li><a href="#token_expiration">token_expiration</a></li>
+ <li><a href="#sync_due">sync_due</a></li>
+ <li><a href="#seen_get">seen_get</a></li>
+ <li><a href="#seen_put">seen_put</a></li>
+ <li><a href="#seen_delete">seen_delete</a></li>
+ <li><a href="#get_storage_variables">get_storage_variables</a></li>
+ <li><a href="#dump_tokens">dump_tokens</a></li>
+ <li><a href="#set_last_expire">set_last_expire</a></li>
+ <li><a href="#get_running_expire_tok">get_running_expire_tok</a></li>
+ <li><a href="#set_running_expire_tok">set_running_expire_tok</a></li>
+ <li><a href="#remove_running_expire_tok">remove_running_expire_tok</a></li>
+ <li><a href="#tok_get">tok_get</a></li>
+ <li><a href="#tok_get_all">tok_get_all</a></li>
+ <li><a href="#tok_count_change">tok_count_change</a></li>
+ <li><a href="#multi_tok_count_change">multi_tok_count_change</a></li>
+ <li><a href="#nspam_nham_get">nspam_nham_get</a></li>
+ <li><a href="#nspam_nham_change">nspam_nham_change</a></li>
+ <li><a href="#tok_touch">tok_touch</a></li>
+ <li><a href="#tok_touch_all">tok_touch_all</a></li>
+ <li><a href="#cleanup">cleanup</a></li>
+ <li><a href="#get_magic_re">get_magic_re</a></li>
+ <li><a href="#sync">sync</a></li>
+ <li><a href="#perform_upgrade">perform_upgrade</a></li>
+ <li><a href="#clear_database">clear_database</a></li>
+ <li><a href="#backup_database">backup_database</a></li>
+ <li><a href="#restore_database">restore_database</a></li>
+ <li><a href="#db_readable">db_readable</a></li>
+ <li><a href="#db_writable">db_writable</a></li>
+ <li><a href="#extract_atime">_extract_atime</a></li>
+ <li><a href="#put_token">_put_token</a></li>
+ </ul>
+ </li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::BayesStore::BDB - BerkeleyDB Bayesian Storage Module Implementation</p>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>This module implements a BDB based bayesian storage module.</p>
+
+<h1 id="METHODS">METHODS</h1>
+
+<h2 id="new">new</h2>
+
+<p>public class (Mail::SpamAssassin::BayesStore::SQL) new (Mail::Spamassassin::Plugin::Bayes $bayes)</p>
+
+<p>Description: This methods creates a new instance of the Mail::SpamAssassin::BayesStore::BDB object. It expects to be passed an instance of the Mail::SpamAssassin:Bayes object which is passed into the Mail::SpamAssassin::BayesStore parent object.</p>
+
+<h2 id="tie_db_readonly">tie_db_readonly</h2>
+
+<p>public instance (Boolean) tie_db_readonly ();</p>
+
+<p>Description: This method ensures that the database connection is properly setup and working.</p>
+
+<h2 id="tie_db_writable">tie_db_writable</h2>
+
+<p>public instance (Boolean) tie_db_writable ()</p>
+
+<p>Description: This method ensures that the database connection is properly setup and working. If necessary it will initialize the database so that they can begin using the database immediately.</p>
+
+<h2 id="open_db">_open_db</h2>
+
+<p>private instance (Boolean) _open_db (Boolean $writable)</p>
+
+<p>Description: This method ensures that the database connection is properly setup and working. It will initialize a users bayes variables so that they can begin using the database immediately.</p>
+
+<h2 id="untie_db">untie_db</h2>
+
+<p>public instance () untie_db ()</p>
+
+<p>Description: Closes any open db handles. You can safely call this at any time.</p>
+
+<h2 id="calculate_expire_delta">calculate_expire_delta</h2>
+
+<p>public instance (%) calculate_expire_delta ( Integer $newest_atime, Integer $start, Integer $max_expire_mult)</p>
+
+<p>Description: This method performs a calculation on the data to determine the optimum atime for token expiration.</p>
+
+<h2 id="token_expiration">token_expiration</h2>
+
+<p>public instance (Integer, Integer, Integer, Integer) token_expiration (\% $opts, Integer $newdelta, @ @vars)</p>
+
+<p>Description: This method performs the database specific expiration of tokens based on the passed in <code>$newdelta</code> and <code>@vars</code>.</p>
+
+<h2 id="sync_due">sync_due</h2>
+
+<p>public instance (Boolean) sync_due ()</p>
+
+<p>Description: This method determines if a database sync is currently required.</p>
+
+<p>Unused for BDB implementation.</p>
+
+<h2 id="seen_get">seen_get</h2>
+
+<p>public instance (String) seen_get (string $msgid)</p>
+
+<p>Description: This method retrieves the stored value, if any, for <code>$msgid</code>. The return value is the stored string ('s' for spam and 'h' for ham) or undef if <code>$msgid</code> is not found.</p>
+
+<h2 id="seen_put">seen_put</h2>
+
+<p>public (Boolean) seen_put (string $msgid, char $flag)</p>
+
+<p>Description: This method records <code>$msgid</code> as the type given by <code>$flag</code>. <code>$flag</code> is one of two values 's' for spam and 'h' for ham.</p>
+
+<h2 id="seen_delete">seen_delete</h2>
+
+<p>public instance (Boolean) seen_delete (string $msgid)</p>
+
+<p>Description: This method removes <code>$msgid</code> from the database.</p>
+
+<h2 id="get_storage_variables">get_storage_variables</h2>
+
+<p>public instance (@) get_storage_variables ()</p>
+
+<p>Description: This method retrieves the various administrative variables used by the Bayes process and database.</p>
+
+<p>The values returned in the array are in the following order:</p>
+
+<p>0: scan count base</p>
+
+<p>1: number of spam</p>
+
+<p>2: number of ham</p>
+
+<p>3: number of tokens in db</p>
+
+<p>4: last expire atime</p>
+
+<p>5: oldest token in db atime</p>
+
+<p>6: db version value</p>
+
+<p>7: last journal sync</p>
+
+<p>8: last atime delta</p>
+
+<p>9: last expire reduction count</p>
+
+<p>10: newest token in db atime</p>
+
+<h2 id="dump_tokens">dump_tokens</h2>
+
+<p>public instance () dump_tokens (String $template, String $regex, Array @vars)</p>
+
+<p>Description: This method loops over all tokens, computing the probability for the token and then printing it out according to the passed in token.</p>
+
+<h2 id="set_last_expire">set_last_expire</h2>
+
+<p>public instance (Boolean) set_last_expire (Integer $time)</p>
+
+<p>Description: This method sets the last expire time.</p>
+
+<h2 id="get_running_expire_tok">get_running_expire_tok</h2>
+
+<p>public instance (String $time) get_running_expire_tok ()</p>
+
+<p>Description: This method determines if an expire is currently running and returns the last time set.</p>
+
+<p>There can be multiple times, so we just pull the greatest (most recent) value.</p>
+
+<h2 id="set_running_expire_tok">set_running_expire_tok</h2>
+
+<p>public instance (String $time) set_running_expire_tok ()</p>
+
+<p>Description: This method sets the time that an expire starts running.</p>
+
+<h2 id="remove_running_expire_tok">remove_running_expire_tok</h2>
+
+<p>public instance (Boolean) remove_running_expire_tok ()</p>
+
+<p>Description: This method removes the row in the database that indicates that and expire is currently running.</p>
+
+<h2 id="tok_get">tok_get</h2>
+
+<p>public instance (Integer, Integer, Integer) tok_get (String $token)</p>
+
+<p>Description: This method retrieves a specified token (<code>$token</code>) from the database and returns its spam_count, ham_count and last access time.</p>
+
+<h2 id="tok_get_all">tok_get_all</h2>
+
+<p>public instance (\@) tok_get (@ $tokens)</p>
+
+<p>Description: This method retrieves the specified tokens (<code>$tokens</code>) from storage and returns an array ref of arrays spam count, ham count and last access time.</p>
+
+<h2 id="tok_count_change">tok_count_change</h2>
+
+<p>public instance (Boolean) tok_count_change ( Integer $dspam, Integer $dham, String $token, String $newatime)</p>
+
+<p>Description: This method takes a <code>$spam_count</code> and <code>$ham_count</code> and adds it to <code>$tok</code> along with updating <code>$tok</code>s atime with <code>$atime</code>.</p>
+
+<h2 id="multi_tok_count_change">multi_tok_count_change</h2>
+
+<p>public instance (Boolean) multi_tok_count_change ( Integer $dspam, Integer $dham, \% $tokens, String $newatime)</p>
+
+<p>Description: This method takes a <code>$dspam</code> and <code>$dham</code> and adds it to all of the tokens in the <code>$tokens</code> hash ref along with updating each tokens atime with <code>$atime</code>.</p>
+
+<h2 id="nspam_nham_get">nspam_nham_get</h2>
+
+<p>public instance ($spam_count, $ham_count) nspam_nham_get ()</p>
+
+<p>Description: This method retrieves the total number of spam and the total number of ham learned.</p>
+
+<h2 id="nspam_nham_change">nspam_nham_change</h2>
+
+<p>public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer $num_ham)</p>
+
+<p>Description: This method updates the number of spam and the number of ham in the database.</p>
+
+<h2 id="tok_touch">tok_touch</h2>
+
+<p>public instance (Boolean) tok_touch (String $token, String $atime)</p>
+
+<p>Description: This method updates the given tokens (<code>$token</code>) atime.</p>
+
+<p>The assumption is that the token already exists in the database.</p>
+
+<p>We will never update to an older atime</p>
+
+<h2 id="tok_touch_all">tok_touch_all</h2>
+
+<p>public instance (Boolean) tok_touch (\@ $tokens String $atime)</p>
+
+<p>Description: This method does a mass update of the given list of tokens <code>$tokens</code>, if the existing token atime is < <code>$atime</code>.</p>
+
+<p>The assumption is that the tokens already exist in the database.</p>
+
+<p>We should never be touching more than N_SIGNIFICANT_TOKENS, so we can make some assumptions about how to handle the data (ie no need to batch like we do in tok_get_all)</p>
+
+<h2 id="cleanup">cleanup</h2>
+
+<p>public instance (Boolean) cleanup ()</p>
+
+<p>Description: This method performs any cleanup necessary before moving onto the next operation.</p>
+
+<h2 id="get_magic_re">get_magic_re</h2>
+
+<p>public instance (String) get_magic_re ()</p>
+
+<p>Description: This method returns a regexp which indicates a magic token.</p>
+
+<p>Unused in BDB implementation.</p>
+
+<h2 id="sync">sync</h2>
+
+<p>public instance (Boolean) sync (\% $opts)</p>
+
+<p>Description: This method performs a sync of the database</p>
+
+<h2 id="perform_upgrade">perform_upgrade</h2>
+
+<p>public instance (Boolean) perform_upgrade (\% $opts);</p>
+
+<p>Description: Performs an upgrade of the database from one version to another, not currently used in this implementation.</p>
+
+<h2 id="clear_database">clear_database</h2>
+
+<p>public instance (Boolean) clear_database ()</p>
+
+<p>Description: This method deletes all records for a particular user.</p>
+
+<p>Callers should be aware that any errors returned by this method could causes the database to be inconsistent for the given user.</p>
+
+<h2 id="backup_database">backup_database</h2>
+
+<p>public instance (Boolean) backup_database ()</p>
+
+<p>Description: This method will dump the users database in a machine readable format.</p>
+
+<h2 id="restore_database">restore_database</h2>
+
+<p>public instance (Boolean) restore_database (String $filename, Boolean $showdots)</p>
+
+<p>Description: This method restores a database from the given filename, <code>$filename</code>.</p>
+
+<p>Callers should be aware that any errors returned by this method could causes the database to be inconsistent for the given user.</p>
+
+<h2 id="db_readable">db_readable</h2>
+
+<p>public instance (Boolean) db_readable()</p>
+
+<p>Description: This method returns a boolean value indicating if the database is in a readable state.</p>
+
+<h2 id="db_writable">db_writable</h2>
+
+<p>public instance (Boolean) db_writable()</p>
+
+<p>Description: This method returns a boolean value indicating if the database is in a writable state.</p>
+
+<h2 id="extract_atime">_extract_atime</h2>
+
+<p>private instance () _extract_atime (String $token, String $value, String $index)</p>
+
+<p>Description: This method ensures that the database connection is properly setup and working. If appropriate it will initialize a users bayes variables so that they can begin using the database immediately.</p>
+
+<h2 id="put_token">_put_token</h2>
+
+<p>FIXME: This is rarely a good interface, because of the churn that will often happen in the "magic" tokens. Open-code this stuff in the presence of loops.</p>
+
+
+</body>
+
+</html>
+
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,281 @@
+NAME
+ Mail::SpamAssassin::BayesStore::BDB - BerkeleyDB Bayesian Storage Module
+ Implementation
+
+DESCRIPTION
+ This module implements a BDB based bayesian storage module.
+
+METHODS
+ new
+ public class (Mail::SpamAssassin::BayesStore::SQL) new
+ (Mail::Spamassassin::Plugin::Bayes $bayes)
+
+ Description: This methods creates a new instance of the
+ Mail::SpamAssassin::BayesStore::BDB object. It expects to be passed an
+ instance of the Mail::SpamAssassin:Bayes object which is passed into the
+ Mail::SpamAssassin::BayesStore parent object.
+
+ tie_db_readonly
+ public instance (Boolean) tie_db_readonly ();
+
+ Description: This method ensures that the database connection is
+ properly setup and working.
+
+ tie_db_writable
+ public instance (Boolean) tie_db_writable ()
+
+ Description: This method ensures that the database connection is
+ properly setup and working. If necessary it will initialize the database
+ so that they can begin using the database immediately.
+
+ _open_db
+ private instance (Boolean) _open_db (Boolean $writable)
+
+ Description: This method ensures that the database connection is
+ properly setup and working. It will initialize a users bayes variables
+ so that they can begin using the database immediately.
+
+ untie_db
+ public instance () untie_db ()
+
+ Description: Closes any open db handles. You can safely call this at any
+ time.
+
+ calculate_expire_delta
+ public instance (%) calculate_expire_delta ( Integer $newest_atime,
+ Integer $start, Integer $max_expire_mult)
+
+ Description: This method performs a calculation on the data to determine
+ the optimum atime for token expiration.
+
+ token_expiration
+ public instance (Integer, Integer, Integer, Integer) token_expiration
+ (\% $opts, Integer $newdelta, @ @vars)
+
+ Description: This method performs the database specific expiration of
+ tokens based on the passed in $newdelta and @vars.
+
+ sync_due
+ public instance (Boolean) sync_due ()
+
+ Description: This method determines if a database sync is currently
+ required.
+
+ Unused for BDB implementation.
+
+ seen_get
+ public instance (String) seen_get (string $msgid)
+
+ Description: This method retrieves the stored value, if any, for $msgid.
+ The return value is the stored string ('s' for spam and 'h' for ham) or
+ undef if $msgid is not found.
+
+ seen_put
+ public (Boolean) seen_put (string $msgid, char $flag)
+
+ Description: This method records $msgid as the type given by $flag.
+ $flag is one of two values 's' for spam and 'h' for ham.
+
+ seen_delete
+ public instance (Boolean) seen_delete (string $msgid)
+
+ Description: This method removes $msgid from the database.
+
+ get_storage_variables
+ public instance (@) get_storage_variables ()
+
+ Description: This method retrieves the various administrative variables
+ used by the Bayes process and database.
+
+ The values returned in the array are in the following order:
+
+ 0: scan count base
+
+ 1: number of spam
+
+ 2: number of ham
+
+ 3: number of tokens in db
+
+ 4: last expire atime
+
+ 5: oldest token in db atime
+
+ 6: db version value
+
+ 7: last journal sync
+
+ 8: last atime delta
+
+ 9: last expire reduction count
+
+ 10: newest token in db atime
+
+ dump_tokens
+ public instance () dump_tokens (String $template, String $regex, Array
+ @vars)
+
+ Description: This method loops over all tokens, computing the
+ probability for the token and then printing it out according to the
+ passed in token.
+
+ set_last_expire
+ public instance (Boolean) set_last_expire (Integer $time)
+
+ Description: This method sets the last expire time.
+
+ get_running_expire_tok
+ public instance (String $time) get_running_expire_tok ()
+
+ Description: This method determines if an expire is currently running
+ and returns the last time set.
+
+ There can be multiple times, so we just pull the greatest (most recent)
+ value.
+
+ set_running_expire_tok
+ public instance (String $time) set_running_expire_tok ()
+
+ Description: This method sets the time that an expire starts running.
+
+ remove_running_expire_tok
+ public instance (Boolean) remove_running_expire_tok ()
+
+ Description: This method removes the row in the database that indicates
+ that and expire is currently running.
+
+ tok_get
+ public instance (Integer, Integer, Integer) tok_get (String $token)
+
+ Description: This method retrieves a specified token ($token) from the
+ database and returns its spam_count, ham_count and last access time.
+
+ tok_get_all
+ public instance (\@) tok_get (@ $tokens)
+
+ Description: This method retrieves the specified tokens ($tokens) from
+ storage and returns an array ref of arrays spam count, ham count and
+ last access time.
+
+ tok_count_change
+ public instance (Boolean) tok_count_change ( Integer $dspam, Integer
+ $dham, String $token, String $newatime)
+
+ Description: This method takes a $spam_count and $ham_count and adds it
+ to $tok along with updating $toks atime with $atime.
+
+ multi_tok_count_change
+ public instance (Boolean) multi_tok_count_change ( Integer $dspam,
+ Integer $dham, \% $tokens, String $newatime)
+
+ Description: This method takes a $dspam and $dham and adds it to all of
+ the tokens in the $tokens hash ref along with updating each tokens atime
+ with $atime.
+
+ nspam_nham_get
+ public instance ($spam_count, $ham_count) nspam_nham_get ()
+
+ Description: This method retrieves the total number of spam and the
+ total number of ham learned.
+
+ nspam_nham_change
+ public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer
+ $num_ham)
+
+ Description: This method updates the number of spam and the number of
+ ham in the database.
+
+ tok_touch
+ public instance (Boolean) tok_touch (String $token, String $atime)
+
+ Description: This method updates the given tokens ($token) atime.
+
+ The assumption is that the token already exists in the database.
+
+ We will never update to an older atime
+
+ tok_touch_all
+ public instance (Boolean) tok_touch (\@ $tokens String $atime)
+
+ Description: This method does a mass update of the given list of tokens
+ $tokens, if the existing token atime is < $atime.
+
+ The assumption is that the tokens already exist in the database.
+
+ We should never be touching more than N_SIGNIFICANT_TOKENS, so we can
+ make some assumptions about how to handle the data (ie no need to batch
+ like we do in tok_get_all)
+
+ cleanup
+ public instance (Boolean) cleanup ()
+
+ Description: This method performs any cleanup necessary before moving
+ onto the next operation.
+
+ get_magic_re
+ public instance (String) get_magic_re ()
+
+ Description: This method returns a regexp which indicates a magic token.
+
+ Unused in BDB implementation.
+
+ sync
+ public instance (Boolean) sync (\% $opts)
+
+ Description: This method performs a sync of the database
+
+ perform_upgrade
+ public instance (Boolean) perform_upgrade (\% $opts);
+
+ Description: Performs an upgrade of the database from one version to
+ another, not currently used in this implementation.
+
+ clear_database
+ public instance (Boolean) clear_database ()
+
+ Description: This method deletes all records for a particular user.
+
+ Callers should be aware that any errors returned by this method could
+ causes the database to be inconsistent for the given user.
+
+ backup_database
+ public instance (Boolean) backup_database ()
+
+ Description: This method will dump the users database in a machine
+ readable format.
+
+ restore_database
+ public instance (Boolean) restore_database (String $filename, Boolean
+ $showdots)
+
+ Description: This method restores a database from the given filename,
+ $filename.
+
+ Callers should be aware that any errors returned by this method could
+ causes the database to be inconsistent for the given user.
+
+ db_readable
+ public instance (Boolean) db_readable()
+
+ Description: This method returns a boolean value indicating if the
+ database is in a readable state.
+
+ db_writable
+ public instance (Boolean) db_writable()
+
+ Description: This method returns a boolean value indicating if the
+ database is in a writable state.
+
+ _extract_atime
+ private instance () _extract_atime (String $token, String $value, String
+ $index)
+
+ Description: This method ensures that the database connection is
+ properly setup and working. If appropriate it will initialize a users
+ bayes variables so that they can begin using the database immediately.
+
+ _put_token
+ FIXME: This is rarely a good interface, because of the churn that will
+ often happen in the "magic" tokens. Open-code this stuff in the presence
+ of loops.
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,184 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::BayesStore::MySQL - MySQL Specific Bayesian Storage Module Implementation</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+ <li><a href="#METHODS">METHODS</a>
+ <ul>
+ <li><a href="#token_expiration">token_expiration</a></li>
+ <li><a href="#seen_put">seen_put</a></li>
+ <li><a href="#seen_delete">seen_delete</a></li>
+ <li><a href="#set_last_expire">set_last_expire</a></li>
+ <li><a href="#set_running_expire_tok">set_running_expire_tok</a></li>
+ <li><a href="#remove_running_expire_tok">remove_running_expire_tok</a></li>
+ <li><a href="#tok_get">tok_get</a></li>
+ <li><a href="#tok_get_all">tok_get_all</a></li>
+ <li><a href="#nspam_nham_change">nspam_nham_change</a></li>
+ <li><a href="#tok_touch">tok_touch</a></li>
+ <li><a href="#tok_touch_all">tok_touch_all</a></li>
+ <li><a href="#cleanup">cleanup</a></li>
+ <li><a href="#clear_database">clear_database</a></li>
+ </ul>
+ </li>
+ <li><a href="#Private-Methods">Private Methods</a>
+ <ul>
+ <li><a href="#connect_db">_connect_db</a></li>
+ <li><a href="#initialize_db">_initialize_db</a></li>
+ <li><a href="#put_token">_put_token</a></li>
+ <li><a href="#put_tokens">_put_tokens</a></li>
+ <li><a href="#token_select_string">_token_select_string</a></li>
+ </ul>
+ </li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::BayesStore::MySQL - MySQL Specific Bayesian Storage Module Implementation</p>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>This module implements a MySQL specific based bayesian storage module. It requires that you are running at least version 4.1 of MySQL, if you are running a version of MySQL < 4.1 then several aspects of this module will fail and possibly corrupt your bayes database data.</p>
+
+<p>In addition, this module will support rollback on error, if you are using the InnoDB database table type in MySQL. For more information please review the instructions in sql/README.bayes.</p>
+
+<p>This module is also compatible with MariaDB and DBD::MariaDB can be used instead of DBD::mysql driver.</p>
+
+<h1 id="METHODS">METHODS</h1>
+
+<h2 id="token_expiration">token_expiration</h2>
+
+<p>public instance (Integer, Integer, Integer, Integer) token_expiration(\% $opts, Integer $newdelta, @ @vars)</p>
+
+<p>Description: This method performs the database specific expiration of tokens based on the passed in <code>$newdelta</code> and <code>@vars</code>.</p>
+
+<h2 id="seen_put">seen_put</h2>
+
+<p>public (Boolean) seen_put (string $msgid, char $flag)</p>
+
+<p>Description: This method records <code>$msgid</code> as the type given by <code>$flag</code>. <code>$flag</code> is one of two values 's' for spam and 'h' for ham.</p>
+
+<h2 id="seen_delete">seen_delete</h2>
+
+<p>public instance (Boolean) seen_delete (string $msgid)</p>
+
+<p>Description: This method removes <code>$msgid</code> from the database.</p>
+
+<h2 id="set_last_expire">set_last_expire</h2>
+
+<p>public instance (Boolean) set_last_expire (Integer $time)</p>
+
+<p>Description: This method sets the last expire time.</p>
+
+<h2 id="set_running_expire_tok">set_running_expire_tok</h2>
+
+<p>public instance (String $time) set_running_expire_tok ()</p>
+
+<p>Description: This method sets the time that an expire starts running.</p>
+
+<h2 id="remove_running_expire_tok">remove_running_expire_tok</h2>
+
+<p>public instance (Boolean) remove_running_expire_tok ()</p>
+
+<p>Description: This method removes the row in the database that indicates that and expire is currently running.</p>
+
+<h2 id="tok_get">tok_get</h2>
+
+<p>public instance (Integer, Integer, Integer) tok_get (String $token)</p>
+
+<p>Description: This method retrieves a specified token (<code>$token</code>) from the database and returns it's spam_count, ham_count and last access time.</p>
+
+<h2 id="tok_get_all">tok_get_all</h2>
+
+<p>public instance (\@) tok_get (@ $tokens)</p>
+
+<p>Description: This method retrieves the specified tokens (<code>$tokens</code>) from storage and returns an array ref of arrays spam count, ham count and last access time.</p>
+
+<h2 id="nspam_nham_change">nspam_nham_change</h2>
+
+<p>public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer $num_ham)</p>
+
+<p>Description: This method updates the number of spam and the number of ham in the database.</p>
+
+<h2 id="tok_touch">tok_touch</h2>
+
+<p>public instance (Boolean) tok_touch (String $token, String $atime)</p>
+
+<p>Description: This method updates the given tokens (<code>$token</code>) atime.</p>
+
+<p>The assumption is that the token already exists in the database.</p>
+
+<h2 id="tok_touch_all">tok_touch_all</h2>
+
+<p>public instance (Boolean) tok_touch (\@ $tokens String $atime)</p>
+
+<p>Description: This method does a mass update of the given list of tokens <code>$tokens</code>, if the existing token atime is < <code>$atime</code>.</p>
+
+<p>The assumption is that the tokens already exist in the database.</p>
+
+<p>We should never be touching more than N_SIGNIFICANT_TOKENS, so we can make some assumptions about how to handle the data (ie no need to batch like we do in tok_get_all)</p>
+
+<h2 id="cleanup">cleanup</h2>
+
+<p>public instance (Boolean) cleanup ()</p>
+
+<p>Description: This method performs any cleanup necessary before moving onto the next operation.</p>
+
+<h2 id="clear_database">clear_database</h2>
+
+<p>public instance (Boolean) clear_database ()</p>
+
+<p>Description: This method deletes all records for a particular user.</p>
+
+<p>Callers should be aware that any errors returned by this method could causes the database to be inconsistent for the given user.</p>
+
+<h1 id="Private-Methods">Private Methods</h1>
+
+<h2 id="connect_db">_connect_db</h2>
+
+<p>private instance (Boolean) _connect_db ()</p>
+
+<p>Description: This method connects to the SQL database.</p>
+
+<h2 id="initialize_db">_initialize_db</h2>
+
+<p>private instance (Boolean) _initialize_db ()</p>
+
+<p>Description: This method will check to see if a user has had their bayes variables initialized. If not then it will perform this initialization.</p>
+
+<h2 id="put_token">_put_token</h2>
+
+<p>private instance (Boolean) _put_token (string $token, integer $spam_count, integer $ham_count, string $atime)</p>
+
+<p>Description: This method performs the work of either inserting or updating a token in the database.</p>
+
+<h2 id="put_tokens">_put_tokens</h2>
+
+<p>private instance (Boolean) _put_tokens (\% $tokens, integer $spam_count, integer $ham_count, string $atime)</p>
+
+<p>Description: This method performs the work of either inserting or updating tokens in the database.</p>
+
+<h2 id="token_select_string">_token_select_string</h2>
+
+<p>private instance (String) _token_select_string</p>
+
+<p>Description: This method returns the string to be used in SELECT statements to represent the token column.</p>
+
+<p>The default is to use the RPAD function to pad the token out to 5 characters.</p>
+
+
+</body>
+
+</html>
+
+
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_ArchiveIterator.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_ArchiveIterator.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_ArchiveIterator.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,186 @@
+NAME
+ Mail::SpamAssassin::ArchiveIterator - find and process messages one at a
+ time
+
+SYNOPSIS
+ my $iter = Mail::SpamAssassin::ArchiveIterator->new(
+ {
+ 'opt_max_size' => 500 * 1024, # 0 implies no limit
+ 'opt_cache' => 1,
+ }
+ );
+
+ $iter->set_functions( \&wanted, sub { } );
+
+ eval { $iter->run(@ARGV); };
+
+ sub wanted {
+ my($class, $filename, $recv_date, $msg_array) = @_;
+
+
+ ...
+ }
+
+DESCRIPTION
+ The Mail::SpamAssassin::ArchiveIterator module will go through a set of
+ mbox files, mbx files, and directories (with a single message per file)
+ and generate a list of messages. It will then call the "wanted_sub" and
+ "result_sub" functions appropriately per message.
+
+METHODS
+ $item = Mail::SpamAssassin::ArchiveIterator->new( [ { opt => val, ... }
+ ] )
+ Constructs a new "Mail::SpamAssassin::ArchiveIterator" object. You
+ may pass the following attribute-value pairs to the constructor. The
+ pairs are optional unless otherwise noted.
+
+ opt_max_size
+ A value of option *opt_max_size* determines a limit (number of
+ bytes) beyond which a message is considered large and is skipped
+ by ArchiveIterator.
+
+ A value 0 implies no size limit, all messages are examined. An
+ undefined value implies a default limit of 500 KiB.
+
+ opt_all
+ Setting this option to true implicitly sets *opt_max_size* to 0,
+ i.e. no limit of a message size, all messages are processes by
+ ArchiveIterator. For compatibility with SpamAssassin versions
+ older than 3.4.0 which lacked option *opt_max_size*.
+
+ opt_scanprob
+ Randomly select messages to scan, with a probability of N, where
+ N ranges from 0.0 (no messages scanned) to 1.0 (all messages
+ scanned). Default is 1.0.
+
+ This setting can be specified separately for each target.
+
+ opt_before
+ Only use messages which are received after the given time_t
+ value. Negative values are an offset from the current time, e.g.
+ -86400 = last 24 hours; or as parsed by Time::ParseDate (e.g.
+ '-6 months')
+
+ This setting can be specified separately for each target.
+
+ opt_after
+ Same as opt_before, except the messages are only used if after
+ the given time_t value.
+
+ This setting can be specified separately for each target.
+
+ opt_want_date
+ Set to 1 (default) if you want the received date to be filled in
+ in the "wanted_sub" callback below. Set this to 0 to avoid this;
+ it's a good idea to set this to 0 if you can, as it imposes a
+ performance hit.
+
+ opt_skip_empty_messages
+ Set to 1 if you want to skip corrupt, 0-byte messages. The
+ default is 0.
+
+ opt_cache
+ Set to 0 (default) if you don't want to use cached information
+ to help speed up ArchiveIterator. Set to 1 to enable. This
+ setting requires "opt_cachedir" also be set.
+
+ opt_cachedir
+ Set to the path of a directory where you wish to store cached
+ information for "opt_cache", if you don't want to mix them with
+ the input files (as is the default). The directory must be both
+ readable and writable.
+
+ wanted_sub
+ Reference to a subroutine which will process message data.
+ Usually set via set_functions(). The routine will be passed 5
+ values: class (scalar), filename (scalar), received date
+ (scalar), message content (array reference, one message line per
+ element), and the message format key ('f' for file, 'm' for
+ mbox, 'b' for mbx).
+
+ Note that if "opt_want_date" is set to 0, the received date
+ scalar will be undefined.
+
+ result_sub
+ Reference to a subroutine which will process the results of the
+ wanted_sub for each message processed. Usually set via
+ set_functions(). The routine will be passed 3 values: class
+ (scalar), result (scalar, returned from wanted_sub), and
+ received date (scalar).
+
+ Note that if "opt_want_date" is set to 0, the received date
+ scalar will be undefined.
+
+ scan_progress_sub
+ Reference to a subroutine which will be called intermittently
+ during the 'scan' phase of the mass-check. No guarantees are
+ made as to how frequently this may happen, mind you.
+
+ opt_from_regex
+ This setting allows for flexibility in specifying the mbox
+ format From separator.
+
+ It defaults to the regular expression:
+
+ /^From \S+ ?(\S\S\S \S\S\S .?\d .?\d:\d\d:\d\d
+ \d{4}|.?\d-\d\d-\d{4}_\d\d:\d\d:\d\d_)/
+
+ Some SpamAssassin programs such as sa-learn will use the
+ configuration option 'mbox_format_from_regex' to override the
+ default regular expression.
+
+ set_functions( \&wanted_sub, \&result_sub )
+ Sets the subroutines used for message processing (wanted_sub), and
+ result reporting. For more information, see *new()* above.
+
+ run ( @target_paths )
+ Generates the list of messages to process, then runs each message
+ through the configured wanted subroutine.
+
+ Compressed files are detected and uncompressed automatically
+ regardless of file extension. Supported formats are "gzip", "bzip2",
+ "xz", "lz4", "lzip", "lzo". Gzip is uncompressed via IO::Zlib
+ module, others use their specific command line tool
+ (bzip2/xz/lz4/lzip/lzop). Compressed mailbox/mbox files are not
+ supported.
+
+ The target_paths array is expected to be either one element per path
+ in the following format: "class:format:raw_location", or a hash
+ reference containing key-value option pairs and a 'target' key with
+ a value in that format.
+
+ The key-value option pairs that can be used are: opt_scanprob,
+ opt_after, opt_before. See the constructor method's documentation
+ for more information on their effects.
+
+ run() returns 0 if there was an error (can't open a file, etc,) and
+ 1 if there were no errors.
+
+ class
+ Either 'h' for ham or 's' for spam. If the class is longer than
+ 1 character, it will be truncated. If blank, 'h' is default.
+
+ format
+ Specifies the format of the raw_location. "dir" is a directory
+ whose files are individual messages, "file" a file with a single
+ message, "mbox" an mbox formatted file, or "mbx" for an mbx
+ formatted directory.
+
+ "detect" can also be used. This assumes "mbox" for any file
+ whose path contains the pattern "/\.mbox/i", "file" anything
+ that is not a directory, or "directory" otherwise.
+
+ raw_location
+ Path to file or directory. File globbing is allowed using the
+ standard csh-style globbing (see "perldoc -f glob"). "~" at the
+ front of the value will be replaced by the "HOME" environment
+ variable. Escaped whitespace is protected as well.
+
+ NOTE: "~user" is not allowed.
+
+ NOTE 2: "-" is not allowed as a raw location. To have
+ ArchiveIterator deal with STDIN, generate a temp file.
+
+SEE ALSO
+ Mail::SpamAssassin(3) spamassassin(1) mass-check(1)
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,197 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+ <li><a href="#METHODS">METHODS</a></li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop</p>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>An asynchronous event loop used for long-running operations, performed "in the background" during the Mail::SpamAssassin::check() scan operation, such as DNS blocklist lookups.</p>
+
+<h1 id="METHODS">METHODS</h1>
+
+<dl>
+
+<dt id="ent-async-bgsend_and_start_lookup-name-type-class-ent-cb-options">$ent = $async->bgsend_and_start_lookup($name, $type, $class, $ent, $cb, %options)</dt>
+<dd>
+
+<p>Launch async DNS lookups. This is the only official method supported for plugins since version 4.0.0. Do not use bgsend and start_lookup separately.</p>
+
+<p>Merges duplicate queries automatically, only launches one and calls all related callbacks on answer.</p>
+
+<dl>
+
+<dt id="name-required">$name (required)</dt>
+<dd>
+
+<p>Name to query.</p>
+
+</dd>
+<dt id="type-required">$type (required)</dt>
+<dd>
+
+<p>Type to query, A, TXT, NS, etc.</p>
+
+</dd>
+<dt id="class-required-deprecated">$class (required/deprecated)</dt>
+<dd>
+
+<p>Deprecated, ignored, set as undef.</p>
+
+</dd>
+<dt id="ent-is-a-required-hash-reference-containing-the-following-items"><code>$ent</code> is a required hash reference containing the following items:</dt>
+<dd>
+
+<dl>
+
+<dt id="ent--rulename-required">$ent->{rulename} (required)</dt>
+<dd>
+
+<p>The rulename that started and/or depends on this query. Required for rule dependencies to work correctly. Can be a single rulename, or array of multiple rulenames.</p>
+
+</dd>
+<dt id="ent--type-optional">$ent->{type} (optional)</dt>
+<dd>
+
+<p>A string, typically one word, used to describe the type of lookup in log messages, such as <code>DNSBL</code>, <code>URIBL-A</code>. If not defined, default is value of $type.</p>
+
+</dd>
+<dt id="ent--zone-optional">$ent->{zone} (optional)</dt>
+<dd>
+
+<p>A zone specification (typically a DNS zone name - e.g. host, domain, or RBL) which may be used as a key to look up per-zone settings. No semantics on this parameter is imposed by this module. Currently used to fetch by-zone timeouts (from rbl_timeout setting). Defaults to $name.</p>
+
+</dd>
+<dt id="ent--timeout_initial-optional">$ent->{timeout_initial} (optional)</dt>
+<dd>
+
+<p>An initial value of elapsed time for which we are willing to wait for a response (time in seconds, floating point value is allowed). When elapsed time since a query started exceeds the timeout value and there are no other queries to wait for, the query is aborted. The actual timeout value ranges from timeout_initial and gradually approaches timeout_min (see next parameter) as the number of already completed queries approaches the number of all queries started.</p>
+
+<p>If a caller does not explicitly provide this parameter or its value is undefined, a default initial timeout value is settable by a configuration variable rbl_timeout.</p>
+
+<p>If a value of the timeout_initial parameter is below timeout_min, the initial timeout is set to timeout_min.</p>
+
+</dd>
+<dt id="ent--timeout_min-optional">$ent->{timeout_min} (optional)</dt>
+<dd>
+
+<p>A lower bound (in seconds) to which the actual timeout approaches as the number of queries completed approaches the number of all queries started. Defaults to 0.2 * timeout_initial.</p>
+
+</dd>
+<dt id="ent--key-ent--id-deprecated">$ent->{key}, $ent->{id} (deprecated)</dt>
+<dd>
+
+<p>Deprecated, ignored, automatically generated since 4.0.0.</p>
+
+</dd>
+<dt id="ent--YOUR_OWN_ITEM">$ent->{YOUR_OWN_ITEM}</dt>
+<dd>
+
+<p>Any other custom values/objects that you want to pass on to the answer callback.</p>
+
+</dd>
+</dl>
+
+</dd>
+<dt id="cb-required">$cb (required)</dt>
+<dd>
+
+<p>Callback function for answer, called as $cb->($ent, $pkt). <code>$ent</code> is the same object that bgsend_and_start_lookup was called with. <code>$pkt</code> is the packet object for the response, Net::DNS:RR objects can be found from $pkt->answer.</p>
+
+</dd>
+<dt id="options-required">%options (required)</dt>
+<dd>
+
+<p>Hash of options. Only supported and required option is master_deadline:</p>
+
+<pre><code>master_deadline => $pms->{master_deadline}</code></pre>
+
+</dd>
+</dl>
+
+</dd>
+<dt id="ent-async-start_lookup-ent-master_deadline">$ent = $async->start_lookup($ent, $master_deadline)</dt>
+<dd>
+
+<p>DIRECT USE DEPRECATED since 4.0.0, please use bgsend_and_start_lookup.</p>
+
+</dd>
+<dt id="ent-async-get_lookup-key">$ent = $async->get_lookup($key)</dt>
+<dd>
+
+<p>DEPRECATED since 4.0.0. Do not use.</p>
+
+</dd>
+<dt id="async-log_lookups_timing">$async->log_lookups_timing()</dt>
+<dd>
+
+<p>Log sorted timing for all completed lookups.</p>
+
+</dd>
+<dt id="alldone-async-complete_lookups">$alldone = $async->complete_lookups()</dt>
+<dd>
+
+<p>Perform a poll of the pending lookups, to see if any are completed. Callbacks on completed queries will be called from poll_responses().</p>
+
+<p>If there are no lookups remaining, or if too much time has elapsed since any results were returned, <code>1</code> is returned, otherwise <code>0</code>.</p>
+
+</dd>
+<dt id="async-abort_remaining_lookups">$async->abort_remaining_lookups()</dt>
+<dd>
+
+<p>Abort any remaining lookups.</p>
+
+</dd>
+<dt id="async-set_response_packet-id-pkt-key-timestamp">$async->set_response_packet($id, $pkt, $key, $timestamp)</dt>
+<dd>
+
+<p>For internal use, do not call from plugins.</p>
+
+<p>Register a "response packet" for a given query. <code>$id</code> is the ID for the query, and must match the <code>id</code> supplied in <code>start_lookup()</code>. <code>$pkt</code> is the packet object for the response. A parameter <code>$key</code> identifies an entry in a hash %{$self->{pending_lookups}} where the object which spawned this query can be found, and through which further information about the query is accessible.</p>
+
+<p><code>$pkt</code> may be undef, indicating that no response packet is available, but a query has completed (e.g. was aborted or dismissed) and is no longer "pending".</p>
+
+<p>The DNS resolver's response packet <code>$pkt</code> will be made available to a callback subroutine through its argument as well as in <code>$ent->{response_packet}</code>.</p>
+
+</dd>
+<dt id="async-report_id_complete-id-key-key-timestamp">$async->report_id_complete($id,$key,$key,$timestamp)</dt>
+<dd>
+
+<p>DEPRECATED since 4.0.0. Do not use.</p>
+
+<p>Legacy. Equivalent to $self->set_response_packet($id,undef,$key,$timestamp), i.e. providing undef as a response packet. Register that a query has completed and is no longer "pending". <code>$id</code> is the ID for the query, and must match the <code>id</code> supplied in <code>start_lookup()</code>.</p>
+
+<p>One or the other of <code>set_response_packet()</code> or <code>report_id_complete()</code> should be called, but not both.</p>
+
+</dd>
+<dt id="time-async-last_poll_responses_time">$time = $async->last_poll_responses_time()</dt>
+<dd>
+
+<p>Get the time of the last call to <code>poll_responses()</code> (which is called from <code>complete_lookups()</code>. If <code>poll_responses()</code> was never called or <code>abort_remaining_lookups()</code> has been called <code>last_poll_responses_time()</code> will return undef.</p>
+
+</dd>
+</dl>
+
+
+</body>
+
+</html>
+
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AsyncLoop.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,144 @@
+NAME
+ Mail::SpamAssassin::AsyncLoop - scanner asynchronous event loop
+
+DESCRIPTION
+ An asynchronous event loop used for long-running operations, performed
+ "in the background" during the Mail::SpamAssassin::check() scan
+ operation, such as DNS blocklist lookups.
+
+METHODS
+ $ent = $async->bgsend_and_start_lookup($name, $type, $class, $ent, $cb,
+ %options)
+ Launch async DNS lookups. This is the only official method supported
+ for plugins since version 4.0.0. Do not use bgsend and start_lookup
+ separately.
+
+ Merges duplicate queries automatically, only launches one and calls
+ all related callbacks on answer.
+
+ $name (required)
+ Name to query.
+
+ $type (required)
+ Type to query, A, TXT, NS, etc.
+
+ $class (required/deprecated)
+ Deprecated, ignored, set as undef.
+
+ $ent is a required hash reference containing the following items:
+
+ $ent->{rulename} (required)
+ The rulename that started and/or depends on this query.
+ Required for rule dependencies to work correctly. Can be a
+ single rulename, or array of multiple rulenames.
+
+ $ent->{type} (optional)
+ A string, typically one word, used to describe the type of
+ lookup in log messages, such as "DNSBL", "URIBL-A". If not
+ defined, default is value of $type.
+
+ $ent->{zone} (optional)
+ A zone specification (typically a DNS zone name - e.g. host,
+ domain, or RBL) which may be used as a key to look up
+ per-zone settings. No semantics on this parameter is imposed
+ by this module. Currently used to fetch by-zone timeouts
+ (from rbl_timeout setting). Defaults to $name.
+
+ $ent->{timeout_initial} (optional)
+ An initial value of elapsed time for which we are willing to
+ wait for a response (time in seconds, floating point value
+ is allowed). When elapsed time since a query started exceeds
+ the timeout value and there are no other queries to wait
+ for, the query is aborted. The actual timeout value ranges
+ from timeout_initial and gradually approaches timeout_min
+ (see next parameter) as the number of already completed
+ queries approaches the number of all queries started.
+
+ If a caller does not explicitly provide this parameter or
+ its value is undefined, a default initial timeout value is
+ settable by a configuration variable rbl_timeout.
+
+ If a value of the timeout_initial parameter is below
+ timeout_min, the initial timeout is set to timeout_min.
+
+ $ent->{timeout_min} (optional)
+ A lower bound (in seconds) to which the actual timeout
+ approaches as the number of queries completed approaches the
+ number of all queries started. Defaults to 0.2 *
+ timeout_initial.
+
+ $ent->{key}, $ent->{id} (deprecated)
+ Deprecated, ignored, automatically generated since 4.0.0.
+
+ $ent->{YOUR_OWN_ITEM}
+ Any other custom values/objects that you want to pass on to
+ the answer callback.
+
+ $cb (required)
+ Callback function for answer, called as $cb->($ent, $pkt). $ent
+ is the same object that bgsend_and_start_lookup was called with.
+ $pkt is the packet object for the response, Net::DNS:RR objects
+ can be found from $pkt->answer.
+
+ %options (required)
+ Hash of options. Only supported and required option is
+ master_deadline:
+
+ master_deadline => $pms->{master_deadline}
+
+ $ent = $async->start_lookup($ent, $master_deadline)
+ DIRECT USE DEPRECATED since 4.0.0, please use
+ bgsend_and_start_lookup.
+
+ $ent = $async->get_lookup($key)
+ DEPRECATED since 4.0.0. Do not use.
+
+ $async->log_lookups_timing()
+ Log sorted timing for all completed lookups.
+
+ $alldone = $async->complete_lookups()
+ Perform a poll of the pending lookups, to see if any are completed.
+ Callbacks on completed queries will be called from poll_responses().
+
+ If there are no lookups remaining, or if too much time has elapsed
+ since any results were returned, 1 is returned, otherwise 0.
+
+ $async->abort_remaining_lookups()
+ Abort any remaining lookups.
+
+ $async->set_response_packet($id, $pkt, $key, $timestamp)
+ For internal use, do not call from plugins.
+
+ Register a "response packet" for a given query. $id is the ID for
+ the query, and must match the "id" supplied in "start_lookup()".
+ $pkt is the packet object for the response. A parameter $key
+ identifies an entry in a hash %{$self->{pending_lookups}} where the
+ object which spawned this query can be found, and through which
+ further information about the query is accessible.
+
+ $pkt may be undef, indicating that no response packet is available,
+ but a query has completed (e.g. was aborted or dismissed) and is no
+ longer "pending".
+
+ The DNS resolver's response packet $pkt will be made available to a
+ callback subroutine through its argument as well as in
+ "$ent->{response_packet}".
+
+ $async->report_id_complete($id,$key,$key,$timestamp)
+ DEPRECATED since 4.0.0. Do not use.
+
+ Legacy. Equivalent to
+ $self->set_response_packet($id,undef,$key,$timestamp), i.e.
+ providing undef as a response packet. Register that a query has
+ completed and is no longer "pending". $id is the ID for the query,
+ and must match the "id" supplied in "start_lookup()".
+
+ One or the other of "set_response_packet()" or
+ "report_id_complete()" should be called, but not both.
+
+ $time = $async->last_poll_responses_time()
+ Get the time of the last call to "poll_responses()" (which is called
+ from "complete_lookups()". If "poll_responses()" was never called or
+ "abort_remaining_lookups()" has been called
+ "last_poll_responses_time()" will return undef.
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,78 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::AutoWelcomelist - auto-welcomelist handler for SpamAssassin</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+ <li><a href="#METHODS">METHODS</a></li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::AutoWelcomelist - auto-welcomelist handler for SpamAssassin</p>
+
+<h1 id="SYNOPSIS">SYNOPSIS</h1>
+
+<pre><code>(see Mail::SpamAssassin)</code></pre>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>Mail::SpamAssassin is a module to identify spam using text analysis and several internet-based realtime blocklists.</p>
+
+<p>This class is used internally by SpamAssassin to manage the automatic welcomelisting functionality. Please refer to the <code>Mail::SpamAssassin</code> documentation for public interfaces.</p>
+
+<h1 id="METHODS">METHODS</h1>
+
+<dl>
+
+<dt id="meanscore-awl-check_address-addr-originating_ip-signedby">$meanscore = awl->check_address($addr, $originating_ip, $signedby);</dt>
+<dd>
+
+<p>This method will return the mean score of all messages associated with the given address, or undef if the address hasn't been seen before.</p>
+
+<p>If <b>$originating_ip</b> is supplied, it will be used in the lookup.</p>
+
+</dd>
+<dt id="awl-count">awl->count();</dt>
+<dd>
+
+<p>This method will return the count of messages used in determining the welcomelist correction.</p>
+
+</dd>
+<dt id="awl-add_score-score">awl->add_score($score);</dt>
+<dd>
+
+<p>This method will add half the score to the current entry. Half the score is used, so that repeated use of the same From and IP address combination will gradually reduce the score.</p>
+
+</dd>
+<dt id="awl-add_known_good_address-addr">awl->add_known_good_address($addr);</dt>
+<dd>
+
+<p>This method will add a score of -100 to the given address -- effectively "bootstrapping" the address as being one that should be welcomelisted.</p>
+
+</dd>
+<dt id="awl-add_known_bad_address-addr">awl->add_known_bad_address($addr);</dt>
+<dd>
+
+<p>This method will add a score of 100 to the given address -- effectively "bootstrapping" the address as being one that should be blocklisted.</p>
+
+</dd>
+</dl>
+
+
+</body>
+
+</html>
+
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_AutoWelcomelist.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,42 @@
+NAME
+ Mail::SpamAssassin::AutoWelcomelist - auto-welcomelist handler for
+ SpamAssassin
+
+SYNOPSIS
+ (see Mail::SpamAssassin)
+
+DESCRIPTION
+ Mail::SpamAssassin is a module to identify spam using text analysis and
+ several internet-based realtime blocklists.
+
+ This class is used internally by SpamAssassin to manage the automatic
+ welcomelisting functionality. Please refer to the "Mail::SpamAssassin"
+ documentation for public interfaces.
+
+METHODS
+ $meanscore = awl->check_address($addr, $originating_ip, $signedby);
+ This method will return the mean score of all messages associated
+ with the given address, or undef if the address hasn't been seen
+ before.
+
+ If $originating_ip is supplied, it will be used in the lookup.
+
+ awl->count();
+ This method will return the count of messages used in determining
+ the welcomelist correction.
+
+ awl->add_score($score);
+ This method will add half the score to the current entry. Half the
+ score is used, so that repeated use of the same From and IP address
+ combination will gradually reduce the score.
+
+ awl->add_known_good_address($addr);
+ This method will add a score of -100 to the given address --
+ effectively "bootstrapping" the address as being one that should be
+ welcomelisted.
+
+ awl->add_known_bad_address($addr);
+ This method will add a score of 100 to the given address --
+ effectively "bootstrapping" the address as being one that should be
+ blocklisted.
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,34 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::Bayes - support for learning classifiers</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::Bayes - support for learning classifiers</p>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>This is the general class used to train a learning classifier with new samples of spam and ham mail, and classify based on prior training.</p>
+
+<p>Prior to version 3.3.0, the default Bayes implementation was here; if you're looking for information on that, it has moved to <code>Mail::SpamAssassin::Plugin::Bayes</code>.</p>
+
+
+</body>
+
+</html>
+
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_Bayes.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,11 @@
+NAME
+ Mail::SpamAssassin::Bayes - support for learning classifiers
+
+DESCRIPTION
+ This is the general class used to train a learning classifier with new
+ samples of spam and ham mail, and classify based on prior training.
+
+ Prior to version 3.3.0, the default Bayes implementation was here; if
+ you're looking for information on that, it has moved to
+ "Mail::SpamAssassin::Plugin::Bayes".
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,393 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::BayesStore - Storage Module for default Bayes classifier</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+ <li><a href="#METHODS">METHODS</a></li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::BayesStore - Storage Module for default Bayes classifier</p>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>This is the public API for the Bayesian store methods. Any implementation of the storage module for the default Bayes classifier must implement these methods.</p>
+
+<h1 id="METHODS">METHODS</h1>
+
+<dl>
+
+<dt id="new">new</dt>
+<dd>
+
+<p>public class (Mail::SpamAssassin::BayesStore) new (Mail::SpamAssassin::Plugin::Bayes $bayes)</p>
+
+<p>Description: This method creates a new instance of the Mail::SpamAssassin::BayesStore object. You must pass in an instance of the Mail::SpamAssassin::Plugin::Bayes object, which is stashed for use throughout the module.</p>
+
+</dd>
+<dt id="DB_VERSION">DB_VERSION</dt>
+<dd>
+
+<p>public instance (Integer) DB_VERSION ()</p>
+
+<p>Description: This method returns the currently supported database version for the implementation.</p>
+
+</dd>
+<dt id="read_db_configs">read_db_configs</dt>
+<dd>
+
+<p>public instance () read_db_configs ()</p>
+
+<p>Description: This method reads any needed config variables from the configuration object and then calls the Mail::SpamAssassin::Plugin::Bayes read_db_configs method.</p>
+
+</dd>
+<dt id="prefork_init">prefork_init</dt>
+<dd>
+
+<p>public instance (Boolean) prefork_init ()</p>
+
+<p>Description: This optional method is called in the parent process shortly before forking off child processes.</p>
+
+</dd>
+<dt id="spamd_child_init">spamd_child_init</dt>
+<dd>
+
+<p>public instance (Boolean) spamd_child_init ()</p>
+
+<p>Description: This optional method is called in a child process shortly after being spawned.</p>
+
+</dd>
+<dt id="tie_db_readonly">tie_db_readonly</dt>
+<dd>
+
+<p>public instance (Boolean) tie_db_readonly ()</p>
+
+<p>Description: This method opens up the database in readonly mode.</p>
+
+</dd>
+<dt id="tie_db_writable">tie_db_writable</dt>
+<dd>
+
+<p>public instance (Boolean) tie_db_writable ()</p>
+
+<p>Description: This method opens up the database in writable mode.</p>
+
+<p>Any callers of this methods should ensure that they call untie_db() afterwards.</p>
+
+</dd>
+<dt id="untie_db">untie_db</dt>
+<dd>
+
+<p>public instance () untie_db ()</p>
+
+<p>Description: This method unties the database.</p>
+
+</dd>
+<dt id="calculate_expire_delta">calculate_expire_delta</dt>
+<dd>
+
+<p>public instance (%) calculate_expire_delta (Integer $newest_atime, Integer $start, Integer $max_expire_mult)</p>
+
+<p>Description: This method performs a calculation on the data to determine the optimum atime for token expiration.</p>
+
+</dd>
+<dt id="token_expiration">token_expiration</dt>
+<dd>
+
+<p>public instance (Integer, Integer, Integer, Integer) token_expiration(\% $opts, Integer $newest_atime, Integer $newdelta)</p>
+
+<p>Description: This method performs the database specific expiration of tokens based on the passed in <code>$newest_atime</code> and <code>$newdelta</code>.</p>
+
+</dd>
+<dt id="expire_old_tokens">expire_old_tokens</dt>
+<dd>
+
+<p>public instance (Boolean) expire_old_tokens (\% hashref)</p>
+
+<p>Description: This method expires old tokens from the database.</p>
+
+</dd>
+<dt id="expire_old_tokens_trapped">expire_old_tokens_trapped</dt>
+<dd>
+
+<p>public instance (Boolean) expire_old_tokens_trapped (\% $opts)</p>
+
+<p>Description: This methods does the actual token expiration.</p>
+
+<p>XXX More docs here about the methodology and what not</p>
+
+</dd>
+<dt id="sync_due">sync_due</dt>
+<dd>
+
+<p>public instance (Boolean) sync_due ()</p>
+
+<p>Description: This methods determines if a sync is due.</p>
+
+</dd>
+<dt id="expiry_due">expiry_due</dt>
+<dd>
+
+<p>public instance (Boolean) expiry_due ()</p>
+
+<p>Description: This methods determines if an expire is due.</p>
+
+</dd>
+<dt id="seen_get">seen_get</dt>
+<dd>
+
+<p>public instance (Char) seen_get (String $msgid)</p>
+
+<p>Description: This method retrieves the stored value, if any, for <code>$msgid</code>. The return value is the stored string ('s' for spam and 'h' for ham) or undef if <code>$msgid</code> is not found.</p>
+
+</dd>
+<dt id="seen_put">seen_put</dt>
+<dd>
+
+<p>public instance (Boolean) seen_put (String $msgid, Char $flag)</p>
+
+<p>Description: This method records <code>$msgid</code> as the type given by <code>$flag</code>. <code>$flag</code> is one of two values 's' for spam and 'h' for ham.</p>
+
+</dd>
+<dt id="seen_delete">seen_delete</dt>
+<dd>
+
+<p>public instance (Boolean) seen_delete (String $msgid)</p>
+
+<p>Description: This method removes <code>$msgid</code> from storage.</p>
+
+</dd>
+<dt id="get_storage_variables">get_storage_variables</dt>
+<dd>
+
+<p>public instance (@) get_storage_variables ()</p>
+
+<p>Description: This method retrieves the various administrative variables used by the Bayes storage implementation.</p>
+
+<p>The values returned in the array are in the following order:</p>
+
+<p>0: scan count base</p>
+
+<p>1: number of spam</p>
+
+<p>2: number of ham</p>
+
+<p>3: number of tokens in db</p>
+
+<p>4: last expire atime</p>
+
+<p>5: oldest token in db atime</p>
+
+<p>6: db version value</p>
+
+<p>7: last journal sync</p>
+
+<p>8: last atime delta</p>
+
+<p>9: last expire reduction count</p>
+
+<p>10: newest token in db atime</p>
+
+</dd>
+<dt id="dump_db_toks">dump_db_toks</dt>
+<dd>
+
+<p>public instance () dump_db_toks (String $template, String $regex, @ @vars)</p>
+
+<p>Description: This method loops over all tokens, computing the probability for the token and then printing it out according to the passed in template.</p>
+
+</dd>
+<dt id="set_last_expire">set_last_expire</dt>
+<dd>
+
+<p>public instance (Boolean) _set_last_expire (Integer $time)</p>
+
+<p>Description: This method sets the last expire time.</p>
+
+</dd>
+<dt id="get_running_expire_tok">get_running_expire_tok</dt>
+<dd>
+
+<p>public instance (Time) get_running_expire_tok ()</p>
+
+<p>Description: This method determines if an expire is currently running and returns the time the expire started.</p>
+
+</dd>
+<dt id="set_running_expire_tok">set_running_expire_tok</dt>
+<dd>
+
+<p>public instance (Time) set_running_expire_tok ()</p>
+
+<p>Description: This method sets the running expire time to the current time.</p>
+
+</dd>
+<dt id="remove_running_expire_tok">remove_running_expire_tok</dt>
+<dd>
+
+<p>public instance (Boolean) remove_running_expire_tok ()</p>
+
+<p>Description: This method removes a currently set running expire time.</p>
+
+</dd>
+<dt id="tok_get">tok_get</dt>
+<dd>
+
+<p>public instance (Integer, Integer, Time) tok_get (String $token)</p>
+
+<p>Description: This method retrieves the specified token (<code>$token</code>) from storage and returns it's spam count, ham count and last access time.</p>
+
+</dd>
+<dt id="tok_get_all">tok_get_all</dt>
+<dd>
+
+<p>public instance (\@) tok_get_all (@ @tokens)</p>
+
+<p>Description: This method retrieves the specified tokens (<code>@tokens</code>) from storage and returns an array ref of arrays spam count, ham count and last access time.</p>
+
+</dd>
+<dt id="tok_count_change">tok_count_change</dt>
+<dd>
+
+<p>public instance (Boolean) tok_count_change (Integer $spam_count, Integer $ham_count, String $token, Time $atime)</p>
+
+<p>Description: This method takes a <code>$spam_count</code> and <code>$ham_count</code> and adds it to <code>$token</code> along with updating <code>$token</code>s atime with <code>$atime</code>.</p>
+
+</dd>
+<dt id="multi_tok_count_change">multi_tok_count_change</dt>
+<dd>
+
+<p>public instance (Boolean) multi_tok_count_change (Integer $spam_count, Integer $ham_count, \% $tokens, String $atime)</p>
+
+<p>Description: This method takes a <code>$spam_count</code> and <code>$ham_count</code> and adds it to all of the tokens in the <code>$tokens</code> hash ref along with updating each tokens atime with <code>$atime</code>.</p>
+
+</dd>
+<dt id="nspam_nham_get">nspam_nham_get</dt>
+<dd>
+
+<p>public instance (Integer, Integer) nspam_nham_get ()</p>
+
+<p>Description: This method retrieves the total number of spam and the total number of ham currently under storage.</p>
+
+</dd>
+<dt id="nspam_nham_change">nspam_nham_change</dt>
+<dd>
+
+<p>public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer $num_ham)</p>
+
+<p>Description: This method updates the number of spam and the number of ham in the database.</p>
+
+</dd>
+<dt id="tok_touch">tok_touch</dt>
+<dd>
+
+<p>public instance (Boolean) tok_touch (String $token, Time $atime)</p>
+
+<p>Description: This method updates the given tokens (<code>$token</code>) access time.</p>
+
+</dd>
+<dt id="tok_touch_all">tok_touch_all</dt>
+<dd>
+
+<p>public instance (Boolean) tok_touch_all (\@ $tokens, Time $atime)</p>
+
+<p>Description: This method does a mass update of the given list of tokens <code>$tokens</code>, if the existing token atime is < <code>$atime</code>.</p>
+
+</dd>
+<dt id="cleanup">cleanup</dt>
+<dd>
+
+<p>public instance (Boolean) cleanup ()</p>
+
+<p>Description: This method performs any cleanup necessary before moving onto the next operation.</p>
+
+</dd>
+<dt id="get_magic_re">get_magic_re</dt>
+<dd>
+
+<p>public instance get_magic_re (String)</p>
+
+<p>Description: This method returns a regexp which indicates a magic token.</p>
+
+</dd>
+<dt id="sync">sync</dt>
+<dd>
+
+<p>public instance (Boolean) sync (\% $opts)</p>
+
+<p>Description: This method performs a sync of the database.</p>
+
+</dd>
+<dt id="perform_upgrade">perform_upgrade</dt>
+<dd>
+
+<p>public instance (Boolean) perform_upgrade (\% $opts)</p>
+
+<p>Description: This method is a utility method that performs any necessary upgrades between versions. It should know how to handle previous versions and what needs to happen to upgrade them.</p>
+
+<p>A true return value indicates success.</p>
+
+</dd>
+<dt id="clear_database">clear_database</dt>
+<dd>
+
+<p>public instance (Boolean) clear_database ()</p>
+
+<p>Description: This method deletes all records for a particular user.</p>
+
+<p>Callers should be aware that any errors returned by this method could causes the database to be inconsistent for the given user.</p>
+
+</dd>
+<dt id="backup_database">backup_database</dt>
+<dd>
+
+<p>public instance (Boolean) backup_database ()</p>
+
+<p>Description: This method will dump the users database in a machine readable format.</p>
+
+</dd>
+<dt id="restore_database">restore_database</dt>
+<dd>
+
+<p>public instance (Boolean) restore_database (String $filename, Boolean $showdots)</p>
+
+<p>Description: This method restores a database from the given filename, <code>$filename</code>.</p>
+
+<p>Callers should be aware that any errors returned by this method could causes the database to be inconsistent for the given user.</p>
+
+</dd>
+<dt id="db_readable">db_readable</dt>
+<dd>
+
+<p>public instance (Boolean) db_readable ()</p>
+
+<p>Description: This method returns whether or not the Bayes DB is available in a readable state.</p>
+
+</dd>
+<dt id="db_writable">db_writable</dt>
+<dd>
+
+<p>public instance (Boolean) db_writable ()</p>
+
+<p>Description: This method returns whether or not the Bayes DB is available in a writable state.</p>
+
+</dd>
+</dl>
+
+
+</body>
+
+</html>
+
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,291 @@
+NAME
+ Mail::SpamAssassin::BayesStore - Storage Module for default Bayes
+ classifier
+
+DESCRIPTION
+ This is the public API for the Bayesian store methods. Any
+ implementation of the storage module for the default Bayes classifier
+ must implement these methods.
+
+METHODS
+ new public class (Mail::SpamAssassin::BayesStore) new
+ (Mail::SpamAssassin::Plugin::Bayes $bayes)
+
+ Description: This method creates a new instance of the
+ Mail::SpamAssassin::BayesStore object. You must pass in an instance
+ of the Mail::SpamAssassin::Plugin::Bayes object, which is stashed
+ for use throughout the module.
+
+ DB_VERSION
+ public instance (Integer) DB_VERSION ()
+
+ Description: This method returns the currently supported database
+ version for the implementation.
+
+ read_db_configs
+ public instance () read_db_configs ()
+
+ Description: This method reads any needed config variables from the
+ configuration object and then calls the
+ Mail::SpamAssassin::Plugin::Bayes read_db_configs method.
+
+ prefork_init
+ public instance (Boolean) prefork_init ()
+
+ Description: This optional method is called in the parent process
+ shortly before forking off child processes.
+
+ spamd_child_init
+ public instance (Boolean) spamd_child_init ()
+
+ Description: This optional method is called in a child process
+ shortly after being spawned.
+
+ tie_db_readonly
+ public instance (Boolean) tie_db_readonly ()
+
+ Description: This method opens up the database in readonly mode.
+
+ tie_db_writable
+ public instance (Boolean) tie_db_writable ()
+
+ Description: This method opens up the database in writable mode.
+
+ Any callers of this methods should ensure that they call untie_db()
+ afterwards.
+
+ untie_db
+ public instance () untie_db ()
+
+ Description: This method unties the database.
+
+ calculate_expire_delta
+ public instance (%) calculate_expire_delta (Integer $newest_atime,
+ Integer $start, Integer $max_expire_mult)
+
+ Description: This method performs a calculation on the data to
+ determine the optimum atime for token expiration.
+
+ token_expiration
+ public instance (Integer, Integer, Integer, Integer)
+ token_expiration(\% $opts, Integer $newest_atime, Integer $newdelta)
+
+ Description: This method performs the database specific expiration
+ of tokens based on the passed in $newest_atime and $newdelta.
+
+ expire_old_tokens
+ public instance (Boolean) expire_old_tokens (\% hashref)
+
+ Description: This method expires old tokens from the database.
+
+ expire_old_tokens_trapped
+ public instance (Boolean) expire_old_tokens_trapped (\% $opts)
+
+ Description: This methods does the actual token expiration.
+
+ XXX More docs here about the methodology and what not
+
+ sync_due
+ public instance (Boolean) sync_due ()
+
+ Description: This methods determines if a sync is due.
+
+ expiry_due
+ public instance (Boolean) expiry_due ()
+
+ Description: This methods determines if an expire is due.
+
+ seen_get
+ public instance (Char) seen_get (String $msgid)
+
+ Description: This method retrieves the stored value, if any, for
+ $msgid. The return value is the stored string ('s' for spam and 'h'
+ for ham) or undef if $msgid is not found.
+
+ seen_put
+ public instance (Boolean) seen_put (String $msgid, Char $flag)
+
+ Description: This method records $msgid as the type given by $flag.
+ $flag is one of two values 's' for spam and 'h' for ham.
+
+ seen_delete
+ public instance (Boolean) seen_delete (String $msgid)
+
+ Description: This method removes $msgid from storage.
+
+ get_storage_variables
+ public instance (@) get_storage_variables ()
+
+ Description: This method retrieves the various administrative
+ variables used by the Bayes storage implementation.
+
+ The values returned in the array are in the following order:
+
+ 0: scan count base
+
+ 1: number of spam
+
+ 2: number of ham
+
+ 3: number of tokens in db
+
+ 4: last expire atime
+
+ 5: oldest token in db atime
+
+ 6: db version value
+
+ 7: last journal sync
+
+ 8: last atime delta
+
+ 9: last expire reduction count
+
+ 10: newest token in db atime
+
+ dump_db_toks
+ public instance () dump_db_toks (String $template, String $regex, @
+ @vars)
+
+ Description: This method loops over all tokens, computing the
+ probability for the token and then printing it out according to the
+ passed in template.
+
+ set_last_expire
+ public instance (Boolean) _set_last_expire (Integer $time)
+
+ Description: This method sets the last expire time.
+
+ get_running_expire_tok
+ public instance (Time) get_running_expire_tok ()
+
+ Description: This method determines if an expire is currently
+ running and returns the time the expire started.
+
+ set_running_expire_tok
+ public instance (Time) set_running_expire_tok ()
+
+ Description: This method sets the running expire time to the current
+ time.
+
+ remove_running_expire_tok
+ public instance (Boolean) remove_running_expire_tok ()
+
+ Description: This method removes a currently set running expire
+ time.
+
+ tok_get
+ public instance (Integer, Integer, Time) tok_get (String $token)
+
+ Description: This method retrieves the specified token ($token) from
+ storage and returns it's spam count, ham count and last access time.
+
+ tok_get_all
+ public instance (\@) tok_get_all (@ @tokens)
+
+ Description: This method retrieves the specified tokens (@tokens)
+ from storage and returns an array ref of arrays spam count, ham
+ count and last access time.
+
+ tok_count_change
+ public instance (Boolean) tok_count_change (Integer $spam_count,
+ Integer $ham_count, String $token, Time $atime)
+
+ Description: This method takes a $spam_count and $ham_count and adds
+ it to $token along with updating $tokens atime with $atime.
+
+ multi_tok_count_change
+ public instance (Boolean) multi_tok_count_change (Integer
+ $spam_count, Integer $ham_count, \% $tokens, String $atime)
+
+ Description: This method takes a $spam_count and $ham_count and adds
+ it to all of the tokens in the $tokens hash ref along with updating
+ each tokens atime with $atime.
+
+ nspam_nham_get
+ public instance (Integer, Integer) nspam_nham_get ()
+
+ Description: This method retrieves the total number of spam and the
+ total number of ham currently under storage.
+
+ nspam_nham_change
+ public instance (Boolean) nspam_nham_change (Integer $num_spam,
+ Integer $num_ham)
+
+ Description: This method updates the number of spam and the number
+ of ham in the database.
+
+ tok_touch
+ public instance (Boolean) tok_touch (String $token, Time $atime)
+
+ Description: This method updates the given tokens ($token) access
+ time.
+
+ tok_touch_all
+ public instance (Boolean) tok_touch_all (\@ $tokens, Time $atime)
+
+ Description: This method does a mass update of the given list of
+ tokens $tokens, if the existing token atime is < $atime.
+
+ cleanup
+ public instance (Boolean) cleanup ()
+
+ Description: This method performs any cleanup necessary before
+ moving onto the next operation.
+
+ get_magic_re
+ public instance get_magic_re (String)
+
+ Description: This method returns a regexp which indicates a magic
+ token.
+
+ sync
+ public instance (Boolean) sync (\% $opts)
+
+ Description: This method performs a sync of the database.
+
+ perform_upgrade
+ public instance (Boolean) perform_upgrade (\% $opts)
+
+ Description: This method is a utility method that performs any
+ necessary upgrades between versions. It should know how to handle
+ previous versions and what needs to happen to upgrade them.
+
+ A true return value indicates success.
+
+ clear_database
+ public instance (Boolean) clear_database ()
+
+ Description: This method deletes all records for a particular user.
+
+ Callers should be aware that any errors returned by this method
+ could causes the database to be inconsistent for the given user.
+
+ backup_database
+ public instance (Boolean) backup_database ()
+
+ Description: This method will dump the users database in a machine
+ readable format.
+
+ restore_database
+ public instance (Boolean) restore_database (String $filename,
+ Boolean $showdots)
+
+ Description: This method restores a database from the given
+ filename, $filename.
+
+ Callers should be aware that any errors returned by this method
+ could causes the database to be inconsistent for the given user.
+
+ db_readable
+ public instance (Boolean) db_readable ()
+
+ Description: This method returns whether or not the Bayes DB is
+ available in a readable state.
+
+ db_writable
+ public instance (Boolean) db_writable ()
+
+ Description: This method returns whether or not the Bayes DB is
+ available in a writable state.
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,330 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::BayesStore::BDB - BerkeleyDB Bayesian Storage Module Implementation</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+ <li><a href="#METHODS">METHODS</a>
+ <ul>
+ <li><a href="#new">new</a></li>
+ <li><a href="#tie_db_readonly">tie_db_readonly</a></li>
+ <li><a href="#tie_db_writable">tie_db_writable</a></li>
+ <li><a href="#open_db">_open_db</a></li>
+ <li><a href="#untie_db">untie_db</a></li>
+ <li><a href="#calculate_expire_delta">calculate_expire_delta</a></li>
+ <li><a href="#token_expiration">token_expiration</a></li>
+ <li><a href="#sync_due">sync_due</a></li>
+ <li><a href="#seen_get">seen_get</a></li>
+ <li><a href="#seen_put">seen_put</a></li>
+ <li><a href="#seen_delete">seen_delete</a></li>
+ <li><a href="#get_storage_variables">get_storage_variables</a></li>
+ <li><a href="#dump_tokens">dump_tokens</a></li>
+ <li><a href="#set_last_expire">set_last_expire</a></li>
+ <li><a href="#get_running_expire_tok">get_running_expire_tok</a></li>
+ <li><a href="#set_running_expire_tok">set_running_expire_tok</a></li>
+ <li><a href="#remove_running_expire_tok">remove_running_expire_tok</a></li>
+ <li><a href="#tok_get">tok_get</a></li>
+ <li><a href="#tok_get_all">tok_get_all</a></li>
+ <li><a href="#tok_count_change">tok_count_change</a></li>
+ <li><a href="#multi_tok_count_change">multi_tok_count_change</a></li>
+ <li><a href="#nspam_nham_get">nspam_nham_get</a></li>
+ <li><a href="#nspam_nham_change">nspam_nham_change</a></li>
+ <li><a href="#tok_touch">tok_touch</a></li>
+ <li><a href="#tok_touch_all">tok_touch_all</a></li>
+ <li><a href="#cleanup">cleanup</a></li>
+ <li><a href="#get_magic_re">get_magic_re</a></li>
+ <li><a href="#sync">sync</a></li>
+ <li><a href="#perform_upgrade">perform_upgrade</a></li>
+ <li><a href="#clear_database">clear_database</a></li>
+ <li><a href="#backup_database">backup_database</a></li>
+ <li><a href="#restore_database">restore_database</a></li>
+ <li><a href="#db_readable">db_readable</a></li>
+ <li><a href="#db_writable">db_writable</a></li>
+ <li><a href="#extract_atime">_extract_atime</a></li>
+ <li><a href="#put_token">_put_token</a></li>
+ </ul>
+ </li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::BayesStore::BDB - BerkeleyDB Bayesian Storage Module Implementation</p>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>This module implements a BDB based bayesian storage module.</p>
+
+<h1 id="METHODS">METHODS</h1>
+
+<h2 id="new">new</h2>
+
+<p>public class (Mail::SpamAssassin::BayesStore::SQL) new (Mail::Spamassassin::Plugin::Bayes $bayes)</p>
+
+<p>Description: This methods creates a new instance of the Mail::SpamAssassin::BayesStore::BDB object. It expects to be passed an instance of the Mail::SpamAssassin:Bayes object which is passed into the Mail::SpamAssassin::BayesStore parent object.</p>
+
+<h2 id="tie_db_readonly">tie_db_readonly</h2>
+
+<p>public instance (Boolean) tie_db_readonly ();</p>
+
+<p>Description: This method ensures that the database connection is properly setup and working.</p>
+
+<h2 id="tie_db_writable">tie_db_writable</h2>
+
+<p>public instance (Boolean) tie_db_writable ()</p>
+
+<p>Description: This method ensures that the database connection is properly setup and working. If necessary it will initialize the database so that they can begin using the database immediately.</p>
+
+<h2 id="open_db">_open_db</h2>
+
+<p>private instance (Boolean) _open_db (Boolean $writable)</p>
+
+<p>Description: This method ensures that the database connection is properly setup and working. It will initialize a users bayes variables so that they can begin using the database immediately.</p>
+
+<h2 id="untie_db">untie_db</h2>
+
+<p>public instance () untie_db ()</p>
+
+<p>Description: Closes any open db handles. You can safely call this at any time.</p>
+
+<h2 id="calculate_expire_delta">calculate_expire_delta</h2>
+
+<p>public instance (%) calculate_expire_delta ( Integer $newest_atime, Integer $start, Integer $max_expire_mult)</p>
+
+<p>Description: This method performs a calculation on the data to determine the optimum atime for token expiration.</p>
+
+<h2 id="token_expiration">token_expiration</h2>
+
+<p>public instance (Integer, Integer, Integer, Integer) token_expiration (\% $opts, Integer $newdelta, @ @vars)</p>
+
+<p>Description: This method performs the database specific expiration of tokens based on the passed in <code>$newdelta</code> and <code>@vars</code>.</p>
+
+<h2 id="sync_due">sync_due</h2>
+
+<p>public instance (Boolean) sync_due ()</p>
+
+<p>Description: This method determines if a database sync is currently required.</p>
+
+<p>Unused for BDB implementation.</p>
+
+<h2 id="seen_get">seen_get</h2>
+
+<p>public instance (String) seen_get (string $msgid)</p>
+
+<p>Description: This method retrieves the stored value, if any, for <code>$msgid</code>. The return value is the stored string ('s' for spam and 'h' for ham) or undef if <code>$msgid</code> is not found.</p>
+
+<h2 id="seen_put">seen_put</h2>
+
+<p>public (Boolean) seen_put (string $msgid, char $flag)</p>
+
+<p>Description: This method records <code>$msgid</code> as the type given by <code>$flag</code>. <code>$flag</code> is one of two values 's' for spam and 'h' for ham.</p>
+
+<h2 id="seen_delete">seen_delete</h2>
+
+<p>public instance (Boolean) seen_delete (string $msgid)</p>
+
+<p>Description: This method removes <code>$msgid</code> from the database.</p>
+
+<h2 id="get_storage_variables">get_storage_variables</h2>
+
+<p>public instance (@) get_storage_variables ()</p>
+
+<p>Description: This method retrieves the various administrative variables used by the Bayes process and database.</p>
+
+<p>The values returned in the array are in the following order:</p>
+
+<p>0: scan count base</p>
+
+<p>1: number of spam</p>
+
+<p>2: number of ham</p>
+
+<p>3: number of tokens in db</p>
+
+<p>4: last expire atime</p>
+
+<p>5: oldest token in db atime</p>
+
+<p>6: db version value</p>
+
+<p>7: last journal sync</p>
+
+<p>8: last atime delta</p>
+
+<p>9: last expire reduction count</p>
+
+<p>10: newest token in db atime</p>
+
+<h2 id="dump_tokens">dump_tokens</h2>
+
+<p>public instance () dump_tokens (String $template, String $regex, Array @vars)</p>
+
+<p>Description: This method loops over all tokens, computing the probability for the token and then printing it out according to the passed in token.</p>
+
+<h2 id="set_last_expire">set_last_expire</h2>
+
+<p>public instance (Boolean) set_last_expire (Integer $time)</p>
+
+<p>Description: This method sets the last expire time.</p>
+
+<h2 id="get_running_expire_tok">get_running_expire_tok</h2>
+
+<p>public instance (String $time) get_running_expire_tok ()</p>
+
+<p>Description: This method determines if an expire is currently running and returns the last time set.</p>
+
+<p>There can be multiple times, so we just pull the greatest (most recent) value.</p>
+
+<h2 id="set_running_expire_tok">set_running_expire_tok</h2>
+
+<p>public instance (String $time) set_running_expire_tok ()</p>
+
+<p>Description: This method sets the time that an expire starts running.</p>
+
+<h2 id="remove_running_expire_tok">remove_running_expire_tok</h2>
+
+<p>public instance (Boolean) remove_running_expire_tok ()</p>
+
+<p>Description: This method removes the row in the database that indicates that and expire is currently running.</p>
+
+<h2 id="tok_get">tok_get</h2>
+
+<p>public instance (Integer, Integer, Integer) tok_get (String $token)</p>
+
+<p>Description: This method retrieves a specified token (<code>$token</code>) from the database and returns its spam_count, ham_count and last access time.</p>
+
+<h2 id="tok_get_all">tok_get_all</h2>
+
+<p>public instance (\@) tok_get (@ $tokens)</p>
+
+<p>Description: This method retrieves the specified tokens (<code>$tokens</code>) from storage and returns an array ref of arrays spam count, ham count and last access time.</p>
+
+<h2 id="tok_count_change">tok_count_change</h2>
+
+<p>public instance (Boolean) tok_count_change ( Integer $dspam, Integer $dham, String $token, String $newatime)</p>
+
+<p>Description: This method takes a <code>$spam_count</code> and <code>$ham_count</code> and adds it to <code>$tok</code> along with updating <code>$tok</code>s atime with <code>$atime</code>.</p>
+
+<h2 id="multi_tok_count_change">multi_tok_count_change</h2>
+
+<p>public instance (Boolean) multi_tok_count_change ( Integer $dspam, Integer $dham, \% $tokens, String $newatime)</p>
+
+<p>Description: This method takes a <code>$dspam</code> and <code>$dham</code> and adds it to all of the tokens in the <code>$tokens</code> hash ref along with updating each tokens atime with <code>$atime</code>.</p>
+
+<h2 id="nspam_nham_get">nspam_nham_get</h2>
+
+<p>public instance ($spam_count, $ham_count) nspam_nham_get ()</p>
+
+<p>Description: This method retrieves the total number of spam and the total number of ham learned.</p>
+
+<h2 id="nspam_nham_change">nspam_nham_change</h2>
+
+<p>public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer $num_ham)</p>
+
+<p>Description: This method updates the number of spam and the number of ham in the database.</p>
+
+<h2 id="tok_touch">tok_touch</h2>
+
+<p>public instance (Boolean) tok_touch (String $token, String $atime)</p>
+
+<p>Description: This method updates the given tokens (<code>$token</code>) atime.</p>
+
+<p>The assumption is that the token already exists in the database.</p>
+
+<p>We will never update to an older atime</p>
+
+<h2 id="tok_touch_all">tok_touch_all</h2>
+
+<p>public instance (Boolean) tok_touch (\@ $tokens String $atime)</p>
+
+<p>Description: This method does a mass update of the given list of tokens <code>$tokens</code>, if the existing token atime is < <code>$atime</code>.</p>
+
+<p>The assumption is that the tokens already exist in the database.</p>
+
+<p>We should never be touching more than N_SIGNIFICANT_TOKENS, so we can make some assumptions about how to handle the data (ie no need to batch like we do in tok_get_all)</p>
+
+<h2 id="cleanup">cleanup</h2>
+
+<p>public instance (Boolean) cleanup ()</p>
+
+<p>Description: This method performs any cleanup necessary before moving onto the next operation.</p>
+
+<h2 id="get_magic_re">get_magic_re</h2>
+
+<p>public instance (String) get_magic_re ()</p>
+
+<p>Description: This method returns a regexp which indicates a magic token.</p>
+
+<p>Unused in BDB implementation.</p>
+
+<h2 id="sync">sync</h2>
+
+<p>public instance (Boolean) sync (\% $opts)</p>
+
+<p>Description: This method performs a sync of the database</p>
+
+<h2 id="perform_upgrade">perform_upgrade</h2>
+
+<p>public instance (Boolean) perform_upgrade (\% $opts);</p>
+
+<p>Description: Performs an upgrade of the database from one version to another, not currently used in this implementation.</p>
+
+<h2 id="clear_database">clear_database</h2>
+
+<p>public instance (Boolean) clear_database ()</p>
+
+<p>Description: This method deletes all records for a particular user.</p>
+
+<p>Callers should be aware that any errors returned by this method could causes the database to be inconsistent for the given user.</p>
+
+<h2 id="backup_database">backup_database</h2>
+
+<p>public instance (Boolean) backup_database ()</p>
+
+<p>Description: This method will dump the users database in a machine readable format.</p>
+
+<h2 id="restore_database">restore_database</h2>
+
+<p>public instance (Boolean) restore_database (String $filename, Boolean $showdots)</p>
+
+<p>Description: This method restores a database from the given filename, <code>$filename</code>.</p>
+
+<p>Callers should be aware that any errors returned by this method could causes the database to be inconsistent for the given user.</p>
+
+<h2 id="db_readable">db_readable</h2>
+
+<p>public instance (Boolean) db_readable()</p>
+
+<p>Description: This method returns a boolean value indicating if the database is in a readable state.</p>
+
+<h2 id="db_writable">db_writable</h2>
+
+<p>public instance (Boolean) db_writable()</p>
+
+<p>Description: This method returns a boolean value indicating if the database is in a writable state.</p>
+
+<h2 id="extract_atime">_extract_atime</h2>
+
+<p>private instance () _extract_atime (String $token, String $value, String $index)</p>
+
+<p>Description: This method ensures that the database connection is properly setup and working. If appropriate it will initialize a users bayes variables so that they can begin using the database immediately.</p>
+
+<h2 id="put_token">_put_token</h2>
+
+<p>FIXME: This is rarely a good interface, because of the churn that will often happen in the "magic" tokens. Open-code this stuff in the presence of loops.</p>
+
+
+</body>
+
+</html>
+
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_BDB.txt Fri Mar 29 12:01:17 2024
@@ -0,0 +1,281 @@
+NAME
+ Mail::SpamAssassin::BayesStore::BDB - BerkeleyDB Bayesian Storage Module
+ Implementation
+
+DESCRIPTION
+ This module implements a BDB based bayesian storage module.
+
+METHODS
+ new
+ public class (Mail::SpamAssassin::BayesStore::SQL) new
+ (Mail::Spamassassin::Plugin::Bayes $bayes)
+
+ Description: This methods creates a new instance of the
+ Mail::SpamAssassin::BayesStore::BDB object. It expects to be passed an
+ instance of the Mail::SpamAssassin:Bayes object which is passed into the
+ Mail::SpamAssassin::BayesStore parent object.
+
+ tie_db_readonly
+ public instance (Boolean) tie_db_readonly ();
+
+ Description: This method ensures that the database connection is
+ properly setup and working.
+
+ tie_db_writable
+ public instance (Boolean) tie_db_writable ()
+
+ Description: This method ensures that the database connection is
+ properly setup and working. If necessary it will initialize the database
+ so that they can begin using the database immediately.
+
+ _open_db
+ private instance (Boolean) _open_db (Boolean $writable)
+
+ Description: This method ensures that the database connection is
+ properly setup and working. It will initialize a users bayes variables
+ so that they can begin using the database immediately.
+
+ untie_db
+ public instance () untie_db ()
+
+ Description: Closes any open db handles. You can safely call this at any
+ time.
+
+ calculate_expire_delta
+ public instance (%) calculate_expire_delta ( Integer $newest_atime,
+ Integer $start, Integer $max_expire_mult)
+
+ Description: This method performs a calculation on the data to determine
+ the optimum atime for token expiration.
+
+ token_expiration
+ public instance (Integer, Integer, Integer, Integer) token_expiration
+ (\% $opts, Integer $newdelta, @ @vars)
+
+ Description: This method performs the database specific expiration of
+ tokens based on the passed in $newdelta and @vars.
+
+ sync_due
+ public instance (Boolean) sync_due ()
+
+ Description: This method determines if a database sync is currently
+ required.
+
+ Unused for BDB implementation.
+
+ seen_get
+ public instance (String) seen_get (string $msgid)
+
+ Description: This method retrieves the stored value, if any, for $msgid.
+ The return value is the stored string ('s' for spam and 'h' for ham) or
+ undef if $msgid is not found.
+
+ seen_put
+ public (Boolean) seen_put (string $msgid, char $flag)
+
+ Description: This method records $msgid as the type given by $flag.
+ $flag is one of two values 's' for spam and 'h' for ham.
+
+ seen_delete
+ public instance (Boolean) seen_delete (string $msgid)
+
+ Description: This method removes $msgid from the database.
+
+ get_storage_variables
+ public instance (@) get_storage_variables ()
+
+ Description: This method retrieves the various administrative variables
+ used by the Bayes process and database.
+
+ The values returned in the array are in the following order:
+
+ 0: scan count base
+
+ 1: number of spam
+
+ 2: number of ham
+
+ 3: number of tokens in db
+
+ 4: last expire atime
+
+ 5: oldest token in db atime
+
+ 6: db version value
+
+ 7: last journal sync
+
+ 8: last atime delta
+
+ 9: last expire reduction count
+
+ 10: newest token in db atime
+
+ dump_tokens
+ public instance () dump_tokens (String $template, String $regex, Array
+ @vars)
+
+ Description: This method loops over all tokens, computing the
+ probability for the token and then printing it out according to the
+ passed in token.
+
+ set_last_expire
+ public instance (Boolean) set_last_expire (Integer $time)
+
+ Description: This method sets the last expire time.
+
+ get_running_expire_tok
+ public instance (String $time) get_running_expire_tok ()
+
+ Description: This method determines if an expire is currently running
+ and returns the last time set.
+
+ There can be multiple times, so we just pull the greatest (most recent)
+ value.
+
+ set_running_expire_tok
+ public instance (String $time) set_running_expire_tok ()
+
+ Description: This method sets the time that an expire starts running.
+
+ remove_running_expire_tok
+ public instance (Boolean) remove_running_expire_tok ()
+
+ Description: This method removes the row in the database that indicates
+ that and expire is currently running.
+
+ tok_get
+ public instance (Integer, Integer, Integer) tok_get (String $token)
+
+ Description: This method retrieves a specified token ($token) from the
+ database and returns its spam_count, ham_count and last access time.
+
+ tok_get_all
+ public instance (\@) tok_get (@ $tokens)
+
+ Description: This method retrieves the specified tokens ($tokens) from
+ storage and returns an array ref of arrays spam count, ham count and
+ last access time.
+
+ tok_count_change
+ public instance (Boolean) tok_count_change ( Integer $dspam, Integer
+ $dham, String $token, String $newatime)
+
+ Description: This method takes a $spam_count and $ham_count and adds it
+ to $tok along with updating $toks atime with $atime.
+
+ multi_tok_count_change
+ public instance (Boolean) multi_tok_count_change ( Integer $dspam,
+ Integer $dham, \% $tokens, String $newatime)
+
+ Description: This method takes a $dspam and $dham and adds it to all of
+ the tokens in the $tokens hash ref along with updating each tokens atime
+ with $atime.
+
+ nspam_nham_get
+ public instance ($spam_count, $ham_count) nspam_nham_get ()
+
+ Description: This method retrieves the total number of spam and the
+ total number of ham learned.
+
+ nspam_nham_change
+ public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer
+ $num_ham)
+
+ Description: This method updates the number of spam and the number of
+ ham in the database.
+
+ tok_touch
+ public instance (Boolean) tok_touch (String $token, String $atime)
+
+ Description: This method updates the given tokens ($token) atime.
+
+ The assumption is that the token already exists in the database.
+
+ We will never update to an older atime
+
+ tok_touch_all
+ public instance (Boolean) tok_touch (\@ $tokens String $atime)
+
+ Description: This method does a mass update of the given list of tokens
+ $tokens, if the existing token atime is < $atime.
+
+ The assumption is that the tokens already exist in the database.
+
+ We should never be touching more than N_SIGNIFICANT_TOKENS, so we can
+ make some assumptions about how to handle the data (ie no need to batch
+ like we do in tok_get_all)
+
+ cleanup
+ public instance (Boolean) cleanup ()
+
+ Description: This method performs any cleanup necessary before moving
+ onto the next operation.
+
+ get_magic_re
+ public instance (String) get_magic_re ()
+
+ Description: This method returns a regexp which indicates a magic token.
+
+ Unused in BDB implementation.
+
+ sync
+ public instance (Boolean) sync (\% $opts)
+
+ Description: This method performs a sync of the database
+
+ perform_upgrade
+ public instance (Boolean) perform_upgrade (\% $opts);
+
+ Description: Performs an upgrade of the database from one version to
+ another, not currently used in this implementation.
+
+ clear_database
+ public instance (Boolean) clear_database ()
+
+ Description: This method deletes all records for a particular user.
+
+ Callers should be aware that any errors returned by this method could
+ causes the database to be inconsistent for the given user.
+
+ backup_database
+ public instance (Boolean) backup_database ()
+
+ Description: This method will dump the users database in a machine
+ readable format.
+
+ restore_database
+ public instance (Boolean) restore_database (String $filename, Boolean
+ $showdots)
+
+ Description: This method restores a database from the given filename,
+ $filename.
+
+ Callers should be aware that any errors returned by this method could
+ causes the database to be inconsistent for the given user.
+
+ db_readable
+ public instance (Boolean) db_readable()
+
+ Description: This method returns a boolean value indicating if the
+ database is in a readable state.
+
+ db_writable
+ public instance (Boolean) db_writable()
+
+ Description: This method returns a boolean value indicating if the
+ database is in a writable state.
+
+ _extract_atime
+ private instance () _extract_atime (String $token, String $value, String
+ $index)
+
+ Description: This method ensures that the database connection is
+ properly setup and working. If appropriate it will initialize a users
+ bayes variables so that they can begin using the database immediately.
+
+ _put_token
+ FIXME: This is rarely a good interface, because of the churn that will
+ often happen in the "magic" tokens. Open-code this stuff in the presence
+ of loops.
+
Added: spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html?rev=1916621&view=auto
==============================================================================
--- spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html (added)
+++ spamassassin/site/full/4.0.x/doc/Mail_SpamAssassin_BayesStore_MySQL.html Fri Mar 29 12:01:17 2024
@@ -0,0 +1,184 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::BayesStore::MySQL - MySQL Specific Bayesian Storage Module Implementation</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+
+
+<ul id="index">
+ <li><a href="#NAME">NAME</a></li>
+ <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
+ <li><a href="#METHODS">METHODS</a>
+ <ul>
+ <li><a href="#token_expiration">token_expiration</a></li>
+ <li><a href="#seen_put">seen_put</a></li>
+ <li><a href="#seen_delete">seen_delete</a></li>
+ <li><a href="#set_last_expire">set_last_expire</a></li>
+ <li><a href="#set_running_expire_tok">set_running_expire_tok</a></li>
+ <li><a href="#remove_running_expire_tok">remove_running_expire_tok</a></li>
+ <li><a href="#tok_get">tok_get</a></li>
+ <li><a href="#tok_get_all">tok_get_all</a></li>
+ <li><a href="#nspam_nham_change">nspam_nham_change</a></li>
+ <li><a href="#tok_touch">tok_touch</a></li>
+ <li><a href="#tok_touch_all">tok_touch_all</a></li>
+ <li><a href="#cleanup">cleanup</a></li>
+ <li><a href="#clear_database">clear_database</a></li>
+ </ul>
+ </li>
+ <li><a href="#Private-Methods">Private Methods</a>
+ <ul>
+ <li><a href="#connect_db">_connect_db</a></li>
+ <li><a href="#initialize_db">_initialize_db</a></li>
+ <li><a href="#put_token">_put_token</a></li>
+ <li><a href="#put_tokens">_put_tokens</a></li>
+ <li><a href="#token_select_string">_token_select_string</a></li>
+ </ul>
+ </li>
+</ul>
+
+<h1 id="NAME">NAME</h1>
+
+<p>Mail::SpamAssassin::BayesStore::MySQL - MySQL Specific Bayesian Storage Module Implementation</p>
+
+<h1 id="DESCRIPTION">DESCRIPTION</h1>
+
+<p>This module implements a MySQL specific based bayesian storage module. It requires that you are running at least version 4.1 of MySQL, if you are running a version of MySQL < 4.1 then several aspects of this module will fail and possibly corrupt your bayes database data.</p>
+
+<p>In addition, this module will support rollback on error, if you are using the InnoDB database table type in MySQL. For more information please review the instructions in sql/README.bayes.</p>
+
+<p>This module is also compatible with MariaDB and DBD::MariaDB can be used instead of DBD::mysql driver.</p>
+
+<h1 id="METHODS">METHODS</h1>
+
+<h2 id="token_expiration">token_expiration</h2>
+
+<p>public instance (Integer, Integer, Integer, Integer) token_expiration(\% $opts, Integer $newdelta, @ @vars)</p>
+
+<p>Description: This method performs the database specific expiration of tokens based on the passed in <code>$newdelta</code> and <code>@vars</code>.</p>
+
+<h2 id="seen_put">seen_put</h2>
+
+<p>public (Boolean) seen_put (string $msgid, char $flag)</p>
+
+<p>Description: This method records <code>$msgid</code> as the type given by <code>$flag</code>. <code>$flag</code> is one of two values 's' for spam and 'h' for ham.</p>
+
+<h2 id="seen_delete">seen_delete</h2>
+
+<p>public instance (Boolean) seen_delete (string $msgid)</p>
+
+<p>Description: This method removes <code>$msgid</code> from the database.</p>
+
+<h2 id="set_last_expire">set_last_expire</h2>
+
+<p>public instance (Boolean) set_last_expire (Integer $time)</p>
+
+<p>Description: This method sets the last expire time.</p>
+
+<h2 id="set_running_expire_tok">set_running_expire_tok</h2>
+
+<p>public instance (String $time) set_running_expire_tok ()</p>
+
+<p>Description: This method sets the time that an expire starts running.</p>
+
+<h2 id="remove_running_expire_tok">remove_running_expire_tok</h2>
+
+<p>public instance (Boolean) remove_running_expire_tok ()</p>
+
+<p>Description: This method removes the row in the database that indicates that and expire is currently running.</p>
+
+<h2 id="tok_get">tok_get</h2>
+
+<p>public instance (Integer, Integer, Integer) tok_get (String $token)</p>
+
+<p>Description: This method retrieves a specified token (<code>$token</code>) from the database and returns it's spam_count, ham_count and last access time.</p>
+
+<h2 id="tok_get_all">tok_get_all</h2>
+
+<p>public instance (\@) tok_get (@ $tokens)</p>
+
+<p>Description: This method retrieves the specified tokens (<code>$tokens</code>) from storage and returns an array ref of arrays spam count, ham count and last access time.</p>
+
+<h2 id="nspam_nham_change">nspam_nham_change</h2>
+
+<p>public instance (Boolean) nspam_nham_change (Integer $num_spam, Integer $num_ham)</p>
+
+<p>Description: This method updates the number of spam and the number of ham in the database.</p>
+
+<h2 id="tok_touch">tok_touch</h2>
+
+<p>public instance (Boolean) tok_touch (String $token, String $atime)</p>
+
+<p>Description: This method updates the given tokens (<code>$token</code>) atime.</p>
+
+<p>The assumption is that the token already exists in the database.</p>
+
+<h2 id="tok_touch_all">tok_touch_all</h2>
+
+<p>public instance (Boolean) tok_touch (\@ $tokens String $atime)</p>
+
+<p>Description: This method does a mass update of the given list of tokens <code>$tokens</code>, if the existing token atime is < <code>$atime</code>.</p>
+
+<p>The assumption is that the tokens already exist in the database.</p>
+
+<p>We should never be touching more than N_SIGNIFICANT_TOKENS, so we can make some assumptions about how to handle the data (ie no need to batch like we do in tok_get_all)</p>
+
+<h2 id="cleanup">cleanup</h2>
+
+<p>public instance (Boolean) cleanup ()</p>
+
+<p>Description: This method performs any cleanup necessary before moving onto the next operation.</p>
+
+<h2 id="clear_database">clear_database</h2>
+
+<p>public instance (Boolean) clear_database ()</p>
+
+<p>Description: This method deletes all records for a particular user.</p>
+
+<p>Callers should be aware that any errors returned by this method could causes the database to be inconsistent for the given user.</p>
+
+<h1 id="Private-Methods">Private Methods</h1>
+
+<h2 id="connect_db">_connect_db</h2>
+
+<p>private instance (Boolean) _connect_db ()</p>
+
+<p>Description: This method connects to the SQL database.</p>
+
+<h2 id="initialize_db">_initialize_db</h2>
+
+<p>private instance (Boolean) _initialize_db ()</p>
+
+<p>Description: This method will check to see if a user has had their bayes variables initialized. If not then it will perform this initialization.</p>
+
+<h2 id="put_token">_put_token</h2>
+
+<p>private instance (Boolean) _put_token (string $token, integer $spam_count, integer $ham_count, string $atime)</p>
+
+<p>Description: This method performs the work of either inserting or updating a token in the database.</p>
+
+<h2 id="put_tokens">_put_tokens</h2>
+
+<p>private instance (Boolean) _put_tokens (\% $tokens, integer $spam_count, integer $ham_count, string $atime)</p>
+
+<p>Description: This method performs the work of either inserting or updating tokens in the database.</p>
+
+<h2 id="token_select_string">_token_select_string</h2>
+
+<p>private instance (String) _token_select_string</p>
+
+<p>Description: This method returns the string to be used in SELECT statements to represent the token column.</p>
+
+<p>The default is to use the RPAD function to pad the token out to 5 characters.</p>
+
+
+</body>
+
+</html>
+
+