NAME

WWW::SMS - sends SMS using service provided by free websites

SYNOPSIS

    use WWW::SMS;
    my $sms = WWW::SMS->new(
        '39',                #international prefix
        '333',               #operator prefix
        '1234567',           #phone number
        'This is a test.',   #message text
        username => 'abcde', #optional parameters
        passwd => 'edcba'    #in hash fashion
    );

    #or now even just
    my $sms = WWW::SMS->new($whole_number, $smstext);
    
    for ( $sms->gateways(sorted => 'reliability') ) {
                                   #for every compatible gateway
        if ($sms->send( $_ ) {     #try to send sms
            last;                  #until it succeds
        } else {
            print $WWW::SMS:Error; #here is the error
        }
    }

DESCRIPTION

WWW::SMS a Perl framework for sending free SMSs over the web.

A new WWW::SMS object must be created with the new method. Once created you can send it through one of the available submodules.

WWW::SMS->new(INTPREFIX, OPPREFIX, PHONE_NUMBER, MESSAGETEXT [, OPTIONS]);

WWW::SMS->new(WHOLE_NUMBER, MESSAGETEXT [, OPTIONS]);

This is the default SMS object constructor.

INTPREFIX is the international prefix: some gateways just don't use the international prefix, but put something in here anyway.

OPPREFIX is the operator prefix

PHONE_NUMBER not much to say

WHOLE_NUMBER the alternative constructor use the the whole number of your cellphone: it includes international prefix and operator prefix. It relies on the database in Telephone::Number to split your number in its 3 basic parts. So if unsure just use the "three-part-phone-number" constructor.

MESSAGETEXT even here not much to say. Submodules are going to cut the SMS to the maximum allowed length by the operator. You can check anyway the maximum length directly looking for the MAXLENGTH constant in submodules.

OPTIONS are passed in a hash fashion. The useful ones to set include

proxy your HTTP proxy

cookie_jar The file where to store cookies. If not set, every cookie goes in the file "lwpcookies.txt" in your working directory.

username and passwd Used by registration based gateways

Other parameters may be required by specific submodules.

METHODS

$sms->send(GATEWAY)

Sends $sms using GATEWAY: returns 1 if succesfull, 0 if there are errors. The last error is in the $WWW::SMS::Error variable.

GATEWAY the gateway you wish to use for sending the SMS: must be a scalar.

gateways([OPTIONS])

Scans @INC directories and returns an ARRAY containing the names of the available gateway submodules. If used upon a SMS object the submodules list returned is filtered by the PREFIX capability. Like this:

   WWW::SMS->gateways(); #returns every available gateway

   $sms->gateways(); #returns just the gateways that can send $sms

   #compatible gateways sorted by reliability
   $sms->gateways(sorted => 'reliability');
   

SUBMODULE GUIDELINES

So, now you got WWW::SMS but what's next? Well, all that's cool about it resides in submodules. A submodule got to do the dirty work of GETting and POSTing webpages. How to write a submodule then? There are a few points to observe:

1 Take a look at submodules provided as example first!

Yes, copying and pasting a submodule structure is a good start point.

2 sub MAXLENGTH

Please set the EXPORTable constant MAXLENGTH to what is the maximum length of SMS the gateway you are scripting for allow.

3 @PREFIXES

@PREFIXES got to be an array of Telephone::Number objects. Telephone::Number->new takes 3 parameters: each one can be a scalar or an array reference. Each scalar or element of referenced arrays is a regular expression. Code will check for the phone number to match at least one of the regexp for each of intpref, prefix and phone_number. If you don't have regexp for one of these fields just give undef to Telephone::Number->new. Take a look at other submodules to better make up your mind.

4 Steps and $WWW::SMS::Error

Do GETs and POSTs as you want, using other submodules as you like. Just remember to mark each GET or POST with a increasing step number. And when you got an error please set the error variable $WWW::SMS::Error to something useful and include the step number in it, so debugging will be easier. Then return 0. If everything goes alright just return 1.

5 Post your module back to the community!

That's important, cause having a high available number of working gateways is difficult (websites keep changing pretty fast) so everybody should share his/her new & cool submodules implementation. Thank you.

COPYRIGHT

Copyright 2001-2003 Giulio Motta giulienk@cpan.org Ivo Marino eim@cpan.org.

Project page at http://www-sms.sourceforge.net/

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.