NAME

Convert::BulkDecoder - Extract (binary) data from mail and news messages

SYNOPSIS

use Convert::BulkDecoder;
my $cvt = new Convert::BulkDecoder::;
# Collect the articles into an array ref.
my $art = [<>];
# Decode.
my $res =  $cvt->decode($art);
die("Failed!") unless $res eq "OK";
print "Extracted ", $cvt->{size}, " bytes to file ", $cvt->{file}, "\n";

DESCRIPTION

Convert::BulkDecoder can be used to decode binary contents as included in email and news articles. It supports UUdecoding, ydecoding and MIME attachments. The contents may be split over multiple articles (files), but must be supplied to the decode() function in one bulk.

For yencoded contents, it is possible to verify file consistency using length and checksum tests.

CONSTRUCTOR ARGUMENTS

crc

When non-zero (default), the CRC of the data is verified, if possible.

md5

Return a base64 encoded MD5 checksum of the data.

force

When non-zero, disables duplicate detection.

verbose

Produce some information during the operation.

debug

Produce some debugging information during the operation.

destdir

The name of the directory where resultant files must be placed. Default is the current directory.

tmpdir

A place where temporary files can be stored, if needed.

neat

A function that gets called with the name of the file as deduced from the data. It must return the desired name of the file to be created.

Default is a function that strips out illegal (and problematic) characters, and turns all blanks into underscores.

RETURN VALUES

Return values are constant strings.

Severe errors are signalled using die(), so you should use try { } to catch them.

OK

The decode operation completed successfully.

EMPTY

No contents was found.

FAIL

The operation failed.

DUP

The requested file already exists with a non-zero size.

Additionally, this information will be returned in the decoder object:

result

The return value.

type

The type of decoding: "M" (MIME), "U" (uudecode) or "Y" (ydecode).

name

The name of the file created, relative to the destination directory.

file

The full name (destination directory + name) of the file created.

size

The length of the data.

md5

A base64 encoded MD5 checksum of the data.

parts

An array reference. Each element is a hash reference that contains the fields result, name, file, size, and md5 for each file that was extracted.

If decoding originated in more than one file, the fields result, name, file, size, and md5 will apply to the first file that was extracted.

LIMITATIONS

Only yencoded data can be CRC checked. CRC checking is slow, so only the partial checksums are verified.

Multi-message MIME attachments are not handled yet.

AUTHOR

Johan Vromans, Squirrel Consultancy <jvromans@squirrel.nl>

Parts of the ydecoding have been stolen from other tools, in particular newsgrab by Jesper L. Nielsen <lyager@phunkbros.dk>.

SEE ALSO

Convert::yEnc, Mail::Box.

COPYRIGHT AND LICENCE

Copyright 2003 Squirrel Consultancy.

License: Artistic.