NAME

Net::SMS::O2_DE - a module to send SMS messages using the O2 Germany web2sms! It's working for Internet-Pack users. They have normally 50 free sms each month. Maybe it is working also for other users. Please tell me if it's working with you and you aren't a Internet-Pack user.

VERSION

Version: 0.07 Date: 24.07.2011

SYNOPSIS

        use strict;
        use Net::SMS::O2_DE;
        
        my $sms = Net::SMS::O2_DE->new(
            autotruncate => 1,
            username => '01701234567',
            password => 'SECRET',
            sender => 'YourMother',
            recipient => '+4917676543210',
            message => 'a test message',
        );
        
        $sms->verbose( 1 );
        $sms->login();
        print "Quota: " , $sms->quota(). "\n";
        $sms->message( 'a different message' );
        print "sending message to mobile number ", $sms->recipient();
        $sms->send_sms();
        $sms->logout();

WARNING

If you don't have any free sms left, sending SMS may cost you money!!

So check, if your quota is high enough to send the desired sms. Use the function sms_count to determine how much sms will be sent with the current settings.

Keep in mind that if you have sheduled sms, they arent yet included in the quota. Eg: If you send now, with quota=10 a scheduled sms which will be sent each hour for the next 3 hours, quota will be decreased to 9 after the first sms is sent. An hour later to 8, another hour later to 7. So the quota will not be immideately 7.

If you have scheduled a sms with schedule_start and frequency but no end date is set there will be send an infinite amount of sms. This this is in most cases undesired. So remind to set schedule_start AND schedule_end

Use sms_count to check, if you send an infinite number of sms.

DESCRIPTION

A perl module to send SMS messages, using the O2 web2sms gateway. This module will only work with mobile phone numbers that have been registered with O2 (http://www.o2.de/) and uses form submission to a URL that may be subject to change. The O2 service is currently only available to german phone users with internet pack.

There is a maximum length for SMS message (1800 for O2). If the sum of message length exceed this, the behaviour of the Net::SMS::O2_DE objects depends on the value of the 'autotruncate' argument to the constructor. If this is a true value, then the subject / message will be truncated to 1800 characters. If false, the object will throw an exception (die). If you set notruncate to 1, then the module won't check the message length, and you are on your own!

This implementation is based on the module Net::SMS::O2.

The HTTP requests are sent using Net::SMS::WEB which uses LWP::UserAgent module. If you are using a proxy, you may need to set the HTTP_PROXY environment variable for this to work (see LWP::UserAgent).

TODO

There is no check if you entered a valid tel number or frequency or other fields.

SUBROUTINES/METHODS

CONSTRUCTOR Parameters

The constructor for Net::SMS::O2_DE takes the following arguments as hash values (see SYNOPSIS):

autotruncate (OPTIONAL)

O2 has a upper limit on the length of the message (1800). If autotruncate is true, message is truncated to 1800 if the sum of the length exceeds 1800. The default for this is false.

notruncate (OPTIONAL)

Of course, if you don't believe the O2 web interface about maximum character length, then you can set this option.

username (REQUIRED)

The O2 username for the user (assuming that the user is already registered at http://www.o2.de/. Normally your phone number (eg. 017801234567)

password (REQUIRED)

The O2 password for the user (assuming that the user is already registered at http://www.o2.de/.

sender (OPTIONAL)

The sender of the sms. You can set a string value which the recipient sees as sender. Defaults to undefined which means your number is set as sender or if anonymous is set the message is sent by anonymous.

anonymous (OPTIONAL)

If anonymous is set and sender is undef the sms will be sent as anonymous

recipient (REQUIRED)

Mobile number for the intended SMS recipient. Format must be international (eg. +4917801234567)

message (REQUIRED)

SMS message body.

verbose (OPTIONAL)

If true, various soothing messages are sent to STDERR. Defaults to false.

flash_sms (OPTIONAL)

If true uses FlashSMS. Defaults to undef which means FlashSMS is off.

schedule_start (OPTIONAL)

If you want to schedule the sms set the parameter frequency to desired value. This is the start time using epoch time of the scheduling. The value is given in seconds from epoch (eg. use time function). ATTENTION: Must be multiple of 900 sekonds (=15 minutes). if not the value will be round up internally to the next quarter of the hour.

Example: If schedule_start is set to the time value which represents in localtime:

20.07.2011 20:05:12 it will be round up to 20.07.2011 20:15:00

So the first sms is sent at 20:15:00

schedule_end (OPTIONAL)

If you want to schedule the sms set the parameter frequency to desired value. This is the end time using epoch time of the scheduling. The value is given in seconds from epoch (eg. use time function). ATTENTION: Must be multiple of 900 sekonds (=15 minutes). if not the value will be round up internally to the next quarter of the hour.

Example: If schedule_end is set to the time value which represents in localtime:

20.07.2011 21:05:12 it will be round up to 20.07.2011 21:15:00

So the last sms is sent at exactly 21:15:00

frequency (OPTIONAL)

Frequency for scheduled sms. Use one of the following values (default is 5):

        5 : only once
        6 : hourly
        1 : dayly
        2 : weekly
        3 : monthly
        4 : each year

Don't forget to set schedule_end otherwise there you may not be able to stop the sms sending.

new The constructor. For parameter explanation see CONSTRUCTOR parameters

AUTOLOAD

All of the constructor arguments can be got / set using accessor methods. E.g.:

        $old_message = $self->message;
        $self->message( $new_message );

get_flow_execution_key

Calls the page to get the FlowExecutionKey for handling login and sending sms. Called by login.

login

Logs in with specified username and password. Calls get_flow_execution_key which is required for the whole communication. After login changes from the login page to the SMS-Center page to set cookies properly.

If already login was already called and not yet logout, this function returns immediatly because assumes that you are already logged in. If you want to force a new login, call logout first.

logout

Logs you out from the current session. Use login to relogon. There can be a parameter with '1' to force logging out

sms_count

Returns the number of needed SMS to send with current settings. Eg: If your message contains 200 characters, it will you cost 2 sms because 1 sms can hold only 160 chars. So this function will return 2.

If you scheduled the sms for eg. each hour in the next three hours, this function will return 3.

Combining of long messages and scheduling will also be calculated correctly.

If you have scheduled a sms but no end date there will be send an infinite mount of sms so this function returns -1 for infinite

quota

Returns the current available free sms.

send_sms

This method is invoked to actually send the SMS message that corresponds to the constructor arguments an set member variables. Returns 1 on success. Otherwise croak will be called with the error message. Login will be automatically performed if not yet called. You have to call logout manually if you want to close the current session.

SEE ALSO

Net::SMS::Web. Net::SMS::O2.

AUTHOR

Stefan Profanter, <profanter@cpan.org>

BUGS

Please report any bugs or feature requests to bug-net-sms-o2_de at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-SMS-O2_DE. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::SMS::O2_DE

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2011 Stefan Profanter.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.