NAME

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

SYNOPSIS

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

  ...

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 \w) or its abbreviations preceded by a single dot.

The following methods are provided:

->handle()

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 ->abbrevs (for the command abbreviations) or ->cmds for the command mapping. ->abbrevs must return a reference to a hash where each key is a possible command abbreviation andd its value, is the actual command.

->cmds 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 ->{abbrevs} or ->{cmds} respectively.

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

• A reference to the object.

• The hash reference passed to ->handle.

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

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

• A reference to the remainder of the SMS.

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

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

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

->dispatch_error

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

->abbrevs

Return $self-{abbrevs}>.

->cmds

Return $self-{cmds}>.

EXPORT

None by default.

LICENSE AND WARRANTY

This code comes with no warranty of any kind. The author cannot be held liable for anything arising of the use of this code under no circumstances.

This code is released under the terms and conditions of the GPL. Please see the file LICENSE that accompains this distribution for more specific information.

This code is (c) 2002 Luis E. Muñoz.

HISTORY

$Log: Dispatcher.pm,v $ Revision 1.4 2003/03/13 20:41:54 lem Fixed case where a command was not followed by any options or any whitespace

Revision 1.3 2003/01/08 02:39:03 lem Body was not being updated by _CMD_SEND. "Nokia" format send command is now properly understood. First segment of the message is being sent by .FORWARD and .REPLY.

Revision 1.2 2003/01/03 00:17:00 lem Documented the address matching in ::Dispatch. Added a few more tests.

Revision 1.1 2002/12/27 19:43:42 lem Added ::Dispatcher and ::Utils to better distribute code. This should make easier the writting of new methods easier

AUTHOR

Luis E. Muñoz <luismunoz@cpan.org>

SEE ALSO

SMS::Handler, perl(1).