Net::DCCIf - Interface to the DCC daemon
my $dcc = Net::DCCIf->new(); $dcc->connect(); my ($results, $oks) = $dcc->dcc_file("test.eml"); $dcc->disconnect();
This module is a simple interface to the Distributed Checksum Clearinghouse daemon (dccifd). It is a simpler replacement for the dccif.pl script that dcc ships with, making usage more perlish (though probably at the expense of a slight performance drop).
The API is intentionally simple. Hopefully it allows enough flexibility to support everything needed, however if not there may be some advantages to sticking with dccif.pl from the DCC distribution.
Net::DCCIf->new()
This constructs a new Net::DCCIf object. It takes no options, and will always return a valid object unless there is an out of memory error.
$dcc->connect(%options)
Attempt to connect to the local unix domain socket. By default this domain socket is expected to be at /var/dcc/dccifd, however you can override this with the homedir option. If the connection fails for any reason then an exception will be thrown detailing the error.
homedir
Returns the object, to facilitate method chaining.
Options
env_from => $from
The envelope from address (MAIL FROM data).
MAIL FROM
env_to => \@env_tos
The envelope to addresses as an array reference (RCPT TO data).
RCPT TO
WARNING: if you pass an empty list here then DCC will assume zero recipients and not increment the counter for this email (equivalent to doing a query_only lookup).
query_only
helo => $helo
The HELO line.
homedir => $dir
Specifies the location of the dccifd unix domain socket.
dccifd
clnt_addr => $addr
Specifies the IP address of the connecting server. If this is an invalid address then an exception will be thrown.
clnt_name => $name
Specifies the host name of the connecting server. If the clnt_name is specified, but clnt_addr is not, then a hostname lookup will be performed to try and determine the IP address. If this lookup fails an exception will be thrown.
clnt_name
clnt_addr
known_spam => 1
Specifies that we already know this email is spam (i.e. it came in to a spamtrap address) and so we let the DCC server know about it.
output_body => 1
Makes get_output() return the full body of the email with a header added to it.
output_header => 1
Makes get_output() return just a header line.
query_only => 1
Issues a query only, rather than first incrementing the database and then querying.
$dcc->dcc_file($filename)
Opens the file and calls dcc_fh() on the resulting filehandle.
Returns ($result, @mappings). See "Results" below.
($result, @mappings)
$dcc->dcc_fh($fh)
Sends the contents of the filehandle to the dcc server.
$dcc->send($type, @data)
Sends raw text data to the dcc server. The type is usually one of "header" or "body", and is used in error messages if there is a problem sending the data.
"header"
"body"
Use this method before any calls to dcc_fh or dcc_file. Using it after may result in an error or unexpected results.
dcc_fh
dcc_file
$dcc->get_results()
Following sending the email via send() you have to manually extract the results (these are the same results as returned by dcc_fh() and dcc_file() above).
send()
dcc_fh()
dcc_file()
$dcc->get_output(%options)
This method returns the header or body from the dcc server that resulted from running dcc on the data. The output depends on the values of the output_body or output_header options passed in the connect() call.
output_body
output_header
connect()
Returns the data as a string unless the output_fh or output_file options are set.
output_fh
output_file
output_fh => $fh
A filehandle to send the output to. If you wish the output to go to STDOUT, you can pass it with $dcc->get_output(output_fh => \*STDOUT).
$dcc->get_output(output_fh => \*STDOUT)
This option overrides any setting for output_file.
output_file => $file
A filename to send the output to, as with output_fh above.
$dcc->disconnect()
Disconnect from the dccifd server and cleanup.
The results returned from dcc_file, dcc_fh and get_results above are a list of values: ($action, @mappings).
get_results
($action, @mappings)
The $action value is one of:
$action
The @mappings value is a list of envelope to addresses followed by the action that should be taken for that address. It is often easier to map this to a hash:
@mappings
my ($action, %mappings) = $dcc->get_results(); print "Action: $action\n"; print "Matt Sergeant action: " . $mappings{'matt@sergeant.org'} . "\n";
This should only have differing values in it should the primary action be "Reject Some", otherwise the values will all be the same as $action.
Ordering of the mappings will be the same as the order of env_to addresses passed to connect() above. Note that this ordering will be lost if you map it to a hash.
env_to
This module throws exceptions for all errors. In order to catch these errors without having your program exit you can use the eval {} construct:
eval {}
my $dcc = Net::DCCIf->new(); eval { $dcc->connect(); my ($results, %mapping) = $dcc->dcc_file("test.eml"); print "Results: $results\n"; print "Recipients: $_ => $mapping{$_}\n" for keys %mapping; }; if ($@) { warn("An error occurred in dcc: $@"); }
No real test suite yet, as its hard to do when testing daemons and so I got lazy :-(
Matt Sergeant <matt@sergeant.org> working for MessageLabs
This is free software. You may redistribute it under the same terms as Perl itself.
Copyright 2003. All Rights Reserved.
To install Net::DCCIf, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::DCCIf
CPAN shell
perl -MCPAN -e shell install Net::DCCIf
For more information on module installation, please visit the detailed CPAN module installation guide.