WWW::SMS(3)

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.