Provided by: libnetsds-kannel-perl_1.300-7_all bug

NAME

       NetSDS::Kannel - Kannel SMS gateway API

SYNOPSIS

               #!/usr/bin/env perl

               use 5.8.0;
               use warnings;
               use strict;

               use NetSDS::Kannel;

               my $kannel = NetSDS::Kannel->new(
                       sendsms_url    => 'http://localhost:1234/sendsms',
                       sendsms_user   => 'sender',
                       sendsms_passwd => 'secret',
                       default_smsc   => 'esme-megafon',
               );

               $res = $kannel->send(
                       from     => '1234',
                       to       => '380672222111',
                       text     => 'Hallo there!',
                       smsc     => 'emse-mts',
                       priority => 3,
               );

               1;

DESCRIPTION

       "NetSDS::Kannel" module provides API to Kannel SMS gateway.

       To decrease innecessary problems we use a lot of predefined parameters while sending and
       receiving messages via Kannel HTTP API. It's not so flexible as direct HTTP processing but
       less expensive in development time ;-)

       This modules uses LWP to send messages and CGI.pm to process messages from Kannel.

CLASS API

       new(%params) - class constructor
           Constructor creates Kannel API handler and set it's configuration.  Most of these
           parameters may be overriden while object method calls.

           Admin API parameters:

           * admin_url - Kannel admin API URL

           * admin_passwd - password to admin API

           Sending SMS API parameters:

           * sendsms_url - URL of Kannel sendsms HTTP API

           * sendsms_user - user name for sending SMS

           * sendsms_passwd - password for sending SMS

           * dlr_url - base URL for DLR retrieving

           * default_smsc - default SMSC identifier for sending SMS

           * default_timeout - default sending TCP timeout

OBJECT METHODS

       send(%parameters) - send MT SM message to Kannel
           This method allows to send SMS message via Kannel SMS gateway.

           Parameters (mostly the same as in Kannel sendsms API):

           * from - source address (overrides message)

           * to - destination address (overrides message)

           * text - message text (byte string)

           * udh - user data header (byte string)

           * charset - charset of text

           * coding - 0 for GSM 03.38, 1 for binary, 2 for UCS2

           * smsc - target SMSC (overrides default one)

           * mclass - message class if necessary (0 for flash sms)

           * validity - TTL for MO SM in minutes

           * deferred - timeout for delayed delivery

           Example:

                   use NetSDS::Kannel;
                   use NetSDS::Util::Misc;

                   my $kannel = NetSDS::Kannel->new(...);
                   $kannel->send_sms(
                           from => '1234',
                           to => '380672206770',
                           text => 'Wake up!!!',
                           smsc => 'nokia_modem',
                           msgid => make_uuid,
                   );

       receive($cgi) - receive MO or DLR from CGI object
           This method provides import message structure from CGI request .  This method is just
           wrapper around "receive_mo()" and "receive_dlr()" methods.

           Message type (MO or DLR) recognized by "type" CGI parameter that may be "mo" or "dlr".

                   my $cgi = CGI::Fast->new();
                   my %ret = $kannel->receive($cgi);

       receive_mo($cgi) - import MO message from CGI object
           This method provides import message structure from CGI request .

           Imported MO message parameters returned as hash with the following keys:

           * smsc - Kannel's SMSC Id

           * smsid - SMSC message ID

           * from - subscriber's MSISDN

           * to - service address (short code)

           * time - SMS receive time

           * unixtime SMS receive time as UNIX timestamp

           * text - MO SM text

           * bin - MO SM as binary string

           * udh - SMS UDH (User Data Headers)

           * coding - SMS encoding (0 - 7 bit GSM 03.38; 2 - UCS2-BE)

           * charset - charset of MO SM text while receiving from Kannel

           * binfo - SMPP "service_type" parameter for billing puroses

       receive_dlr($cgi) - import message from CGI object
           This method provides import message structure from CGI request .

           "receive_dlr" method returns hash with the following keys:

           * smsc - kannel SMSC id

           * msgid - original MT SM message id for DLR identification

           * smsid - SMSC message ID

           * from - subscriber's MSISDN (phone number)

           * to - service address (short code)

           * time - delivery time

           * unixtime - delivery time as UNIX timestamp

           * dlr - DLR state

           * dlrmsg - DLR message from SMSC

           Example:

                   my $cgi = CGI->new();

                   my %dlr = $kannel->receive_dlr($cgi);

                   print "DLR received for MSISDN: " . $dlr{from};

       make_dlr_url(%params) - prepare DLR URL
           This method creates URI escaped string with URL template for DLR notification.

           Paramters: hash (dlr_url, msgid)

           Returns: URI escaped DLR URL

       make_meta(%params) - prepare SMPP optional TLV
           This method creates URI escaped string with optional SMPP tag-lenght-value (TLV)
           parameters to send them in "meta-data" CGI paramter of Kannel's "sendsms" HTTP API.

           Format of "meta-data" parameter value:

                   ?smpp?tag1=value1&tag2=value2&...tagN=valueN

           Paramters: hash of TLV pairs

           Returns: URI escaped string

           Example:

                   my $meta = $self->make_meta(
                           charging_id => '0',
                   );

           This will return: %3Fsmpp%3Fcharging_id%3D0

       status() - retrieve Kannel status
       store_status() - retrieve message queue status
           Not implemented yet.

       shutdown() - bring down Kannel
       suspend() - switch Kannel to 'suspended' state
       isolate() - switch Kannel to 'isolated' state
       resume() - resume Kannel to 'online' state
       restart() - whole bearerbox restart
       flush_dlr() - flush queued DLR if Kannel in 'suspended' state
       reload_lists() - reload black/white lists
       log_level($level) - change Kannel log-level
       start_smsc($smsc) - switch on SMSC connection
       stop_smsc($smsc) - switch off SMSC connection
       add_smsc($smsc) - add new SMSC connection
       remove_smsc($smsc) - remove SMSC connection

EXAMPLES

       See Nibelite kannel API

SEE ALSO

       •   NetSDS::Class::Abstract - base NetSDS class

       •   <http://www.kannel.org/download/1.4.3/userguide-1.4.3/userguide.html> - Kannel User
           Guide

TODO

       1. Add PPG support.

       2. Add OTA support.

AUTHOR

       Michael Bochkaryov <misha@rattler.kiev.ua>

LICENSE

       Copyright (C) 2008-2009 Net Style Ltd.

       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
       MA  02111-1307  USA