NetSDS::Kannel(3pm)					User Contributed Perl Documentation				       NetSDS::Kannel(3pm)

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

       o   NetSDS::Class::Abstract - base NetSDS class

       o   http://www.kannel.org/download/1.4.3/userguide-1.4.3/userguide.html
	   <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

perl v5.12.3							    2011-05-13						       NetSDS::Kannel(3pm)