File Coverage

blib/lib/SMS/Handler/Dispatcher.pm

Criterion	Covered	Total	%
statement	15	49	30.6
branch	0	32	0.0
condition	0	2	0.0
subroutine	5	8	62.5
pod	3	3	100.0
total	23	94	24.4

package SMS::Handler::Dispatcher;

require 5.005_62;

use Carp;
use strict;
use warnings;
use SMS::Handler;
use SMS::Handler::Utils;

our $Debug = 0;

# $Id: Dispatcher.pm,v 1.4 2003/03/13 20:41:54 lem Exp $

our $VERSION = q$Revision: 1.4 $;
$VERSION =~ s/Revision: //;

=pod

=head1 NAME

SMS::Handler::Dispatcher - Helper class for dispatch - based SMS handlers

=head1 SYNOPSIS

  use SMS::Handler::Dispatcher;
  package MyHandler;
  @ISA = qw(SMS::Handler::Dispatcher);

  ...

=head1 DESCRIPTION

This module provides a base class that implements a dispatch table
based on the commands contained in the given SMS. Commands consist of
words (sequences of characters matching C<\w>) or its abbreviations
preceded by a single dot.

=pod

The following methods are provided:

=over 4

=pod

=item C<-Ehandle()>

Dispatch the required command to the handlers set up by the invoking
class. The command to method mapping is assumed to be supplied by the
object when calling C<-Eabbrevs> (for the command abbreviations)
or C<-Ecmds> for the command mapping. C<-Eabbrevs> must return
a reference to a hash where each key is a possible command
abbreviation andd its value, is the actual command.

C<-Ecmds> must return a reference to a hash, where each key is a
command and each value is a reference to the corresponding method to
call. This class includes dummy methods that simply return
C<-E{abbrevs}> or C<-E{cmds}> respectively.

Each of the methods implementing a command, will be called with the
following arguments.

=over 3

=item *

A reference to the object.

=item *

The hash reference passed to C<-Ehandle>.

=item *

A compact representation of the source address, made from
concatenating the NPI, TON and SOURCE with dots.

=item *

A reference to the command line of the SMS (or the whole SMS if no
separate lines).

=item *

A reference to the remainder of the SMS.

=back

A positive return value from said methods, tell C<-Ehandle> to
keep looking for commands. A false return value, stops the search for
further commands. In any case, C<-Ehandle> will return C
| SMS_DEQUEUE>.

If no corresponding command can be found for a given SMS, the
C<-Edispatch_error> method will be invoked, using the same calling
protocol than command methods. Its return value will be returned by
C<-Ehandle>.

The calling protocol depicted above is only attempted if the object
contains C<$self-E{number}>. In this case, the SMS destination
address is matched against C<$self-{dest_addr_ton}>,
C<$self-{dest_addr_npi}> and
C<$self-{dest_addr_destination_addr}>. Only if this match
succeeds, the message is accepted. This allows an object to restrict
the numbers it handles. C is returned in this case, to
allow other objects a chance to process this message.

=cut

sub handle
{
    my $self = shift;
    my $hsms = shift;

    if ($self->{number})
    {
	unless ($hsms->{dest_addr_ton} == $self->{ton})
	{
	    warn "Email: Destination address did not match TON\n" if $Debug;
	    return SMS_CONTINUE;
	}
        unless ($hsms->{dest_addr_npi} == $self->{npi})
	{
	    warn "Email: Destination address did not match NPI\n" if $Debug;
	    return SMS_CONTINUE;
	}
	unless ($hsms->{destination_addr} == $self->{number})
	{
	    warn "Email: Destination address did not match NUMBER\n" if $Debug;
	    return SMS_CONTINUE;
	}
    }
				# This is a convenient shortcut for the
				# source address

    my $source = join('.', $hsms->{source_addr_ton},
		      $hsms->{source_addr_npi},
		      $hsms->{source_addr});

    my $msg = $hsms->{short_message};
    my $body;

    ($msg, $body) = SMS::Handler::Utils::Split($msg);
				# $msg contains the first line of the SMS,
				# where we must look for commands.
				# We will look for a command keyword and
				# hand the whole thing to the corresponding
				# handler method

    $msg =~ s/^[^\.]+//;	# Remove any potential garbage before the
				# first dot.

    $msg =~ s/\s+$//;		# Remove trailing whitespace

    while ($msg =~ m/^\.(\w+)/)
    {
	warn "Dispatcher: Looking for command for '$1'\n" if $Debug;
	if ($self->cmds->{uc $1})
	{
	    warn "Dispatcher: command found\n" if $Debug;
	    last unless $self->cmds->{uc $1}->($self, $hsms,
					       $source, \$msg,
					       \$body);
	}
	else
	{
	    my $name = $self->abbrevs->{uc $1} || undef;
	    last unless $name;

	    warn "Dispatcher: match with $name\n" if $Debug;

	    last unless $self->cmds->{$name}->($self, $hsms, $source,
					       \$msg, \$body);
	}
    }

    $msg =~ s/^\s+$//;		# Discard void whitespace

    if ($msg)
    {
	warn "Dispatcher: no match\n" if $Debug;
	return $self->dispatch_error($hsms, $source, \$msg, \$body);
    }

    return SMS_STOP | SMS_DEQUEUE;
}

=pod

=item C<-Edispatch_error>

sub dispatch_error
{
    croak "Classes based on SMS::Handler::Dispatcher must implement their dispatch_method()\n";
}

=cut

=pod

=item C<-Eabbrevs>

Return C<$self->{abbrevs}>.

=cut

sub abbrevs { return $_[0]->{abbrevs}; }

=item C<-Ecmds>

Return C<$self->{cmds}>.

=cut

sub cmds { return $_[0]->{cmds}; }

1;

__END__