NAME¶

Mail::SpamAssassin::Handler - superclass for MIME-part handlers

SYNOPSIS¶

  package MyHandler;
  use Mail::SpamAssassin::Handler;
  our @ISA = qw(Mail::SpamAssassin::Handler);
  sub new {
    my ($class, $mailsaobject) = @_;
    $class = ref($class) || $class;
    my $self = $class->SUPER::new($mailsaobject);
    bless ($self, $class);
    $self->register_handler('image/jpeg', 'handle_jpeg');
    return $self;
  }
  sub handle_jpeg {
    my ($self, $node, $permsgstatus) = @_;
    # ... analyse the part, optionally return synthetic child parts ...
    return [];
  }

DESCRIPTION¶

A handler is a plugin that processes individual MIME parts: it registers itself for one or more content types with register_handler and is invoked once per matching part during message metadata extraction.

"Mail::SpamAssassin::Handler" is a thin subclass of Mail::SpamAssassin::Plugin. Handlers are loaded, configured and dispatched through the same machinery as plugins; inheriting from this class instead of from "Mail::SpamAssassin::Plugin" gives handlers a distinct identity (so they can be told apart with "$obj->isa('Mail::SpamAssassin::Handler')") and a place for handler-specific behaviour to live in future. Handlers are loaded with the "loadhandler" / "tryhandler" configuration directives, and a block of configuration can be made conditional on a handler with "ifhandler".

Everything in Mail::SpamAssassin::Plugin is available to handlers; only the handler-specific method below is added here.

$handler->register_handler ($mime_pattern, $nameofsub)

Register one of this handler's methods as the MIME-part handler for a content-type pattern. $mime_pattern is an exact type ("image/jpeg") or a major-type glob ("image/*"); the most specific match wins. $nameofsub is the name of a method on this handler that will be called as "$handler->$nameofsub($node, $permsgstatus)" for each matching MIME part, during message metadata extraction (before body rules run and before the URI list is frozen).

The method may inject extracted text into the part with "$node->set_rendered($text, $type)", accumulate per-message findings on $permsgstatus, and return an arrayref of synthetic child-part specs ("{ type => ..., data => $bytes, name => ... }") which are dispatched recursively -- or "undef"/"[]" for none.

SEE ALSO¶

Mail::SpamAssassin::Plugin