/ 
Net-DCCIf-0.02
River stage zero No dependents
/ Net::DCCIf

NAME

Net::DCCIf - Interface to the DCC daemon

SYNOPSIS

my $dcc = Net::DCCIf->new();
$dcc->connect();
my ($results, $oks) = $dcc->dcc_file("test.eml");
$dcc->disconnect();

DESCRIPTION

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).

API

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.

Returns the object, to facilitate method chaining.

Options

env_from => $from

The envelope from address (MAIL FROM data).

env_to => \@env_tos

The envelope to addresses as an array reference (RCPT TO data).

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).

helo => $helo

The HELO line.

homedir => $dir

Specifies the location of the dccifd unix domain socket.

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.

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.

$dcc->dcc_fh($fh)

Sends the contents of the filehandle to the dcc server.

Returns ($result, @mappings). See "Results" below.

$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.

Use this method before any calls to dcc_fh or dcc_file. Using it after may result in an error or unexpected results.

$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).

$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.

Returns the data as a string unless the output_fh or output_file options are set.

Options

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).

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.

Results

The results returned from dcc_file, dcc_fh and get_results above are a list of values: ($action, @mappings).

The $action value is one of:

"Accept"
"Reject"
"Reject Some"
"Temporary Failure"

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:

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.

Exceptions

This module throws exceptions for all errors. In order to catch these errors without having your program exit you can use the eval {} construct:

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: $@");
}

BUGS

No real test suite yet, as its hard to do when testing daemons and so I got lazy :-(

AUTHOR

Matt Sergeant <matt@sergeant.org> working for MessageLabs

LICENSE

This is free software. You may redistribute it under the same terms as Perl itself.

Copyright 2003. All Rights Reserved.