Debian Codegraph @

README

raw
1 NAME
2 NetSDS::Kannel - Kannel SMS gateway API
3
4 SYNOPSIS
5 #!/usr/bin/env perl
6
7 use 5.8.0;
8 use warnings;
9 use strict;
10
11 use NetSDS::Kannel;
12
13 my $kannel = NetSDS::Kannel->new(
14 sendsms_url => 'http://localhost:1234/sendsms',
15 sendsms_user => 'sender',
16 sendsms_passwd => 'secret',
17 default_smsc => 'esme-megafon',
18 );
19
20 $res = $kannel->send(
21 from => '1234',
22 to => '380672222111',
23 text => 'Hallo there!',
24 smsc => 'emse-mts',
25 priority => 3,
26 );
27
28 1;
29
30 DESCRIPTION
31 "NetSDS::Kannel" module provides API to Kannel SMS gateway.
32
33 To decrease innecessary problems we use a lot of predefined parameters
34 while sending and receiving messages via Kannel HTTP API. It's not so
35 flexible as direct HTTP processing but less expensive in development
36 time ;-)
37
38 This modules uses LWP to send messages and CGI.pm to process messages
39 from Kannel.
40
41 CLASS API
42 new(%params) - class constructor
43 Constructor creates Kannel API handler and set it's configuration.
44 Most of these parameters may be overriden while object method calls.
45
46 Admin API parameters:
47
48 * admin_url - Kannel admin API URL
49
50 * admin_passwd - password to admin API
51
52 Sending SMS API parameters:
53
54 * sendsms_url - URL of Kannel sendsms HTTP API
55
56 * sendsms_user - user name for sending SMS
57
58 * sendsms_passwd - password for sending SMS
59
60 * dlr_url - base URL for DLR retrieving
61
62 * default_smsc - default SMSC identifier for sending SMS
63
64 * default_timeout - default sending TCP timeout
65
66 OBJECT METHODS
67 send(%parameters) - send MT SM message to Kannel
68 This method allows to send SMS message via Kannel SMS gateway.
69
70 Parameters (mostly the same as in Kannel sendsms API):
71
72 * from - source address (overrides message)
73
74 * to - destination address (overrides message)
75
76 * text - message text (byte string)
77
78 * udh - user data header (byte string)
79
80 * charset - charset of text
81
82 * coding - 0 for GSM 03.38, 1 for binary, 2 for UCS2
83
84 * smsc - target SMSC (overrides default one)
85
86 * mclass - message class if necessary (0 for flash sms)
87
88 * validity - TTL for MO SM in minutes
89
90 * deferred - timeout for delayed delivery
91
92 Example:
93
94 $kannel->send_sms(
95 from => '1234',
96 to => '380672206770',
97 text => 'Wake up!!!',
98 smsc => 'nokia_modem',
99 );
100
101 receive($cgi) - receive MO or DLR from CGI object
102 This method provides import message structure from CGI request .
103 This method is just wrapper around "receive_mo()" and
104 "receive_dlr()" methods.
105
106 Message type (MO or DLR) recognized by "type" CGI parameter that may
107 be "mo" or "dlr".
108
109 my $cgi = CGI::Fast->new();
110 my %ret = $kannel->receive($cgi);
111
112 receive_mo($cgi) - import MO message from CGI object
113 This method provides import message structure from CGI request .
114
115 Imported MO message parameters returned as hash with the following
116 keys:
117
118 * smsc - Kannel's SMSC Id
119
120 * smsid - SMSC message ID
121
122 * from - subscriber's MSISDN
123
124 * to - service address (short code)
125
126 * time - SMS receive time
127
128 * unixtime SMS receive time as UNIX timestamp
129
130 * text - MO SM text
131
132 * bin - MO SM as binary string
133
134 * udh - SMS UDH (User Data Headers)
135
136 * coding - SMS encoding (0 - 7 bit GSM 03.38; 2 - UCS2-BE)
137
138 * charset - charset of MO SM text while receiving from Kannel
139
140 * binfo - SMPP "service_type" parameter for billing puroses
141
142 receive_dlr($cgi) - import message from CGI object
143 This method provides import message structure from CGI request .
144
145 "receive_dlr" method returns hash with the following keys:
146
147 * smsc - kannel SMSC id
148
149 * msgid - original MT SM message id for DLR identification
150
151 * smsid - SMSC message ID
152
153 * from - subscriber's MSISDN (phone number)
154
155 * to - service address (short code)
156
157 * time - delivery time
158
159 * unixtime - delivery time as UNIX timestamp
160
161 * dlr - DLR state
162
163 * dlrmsg - DLR message from SMSC
164
165 Example:
166
167 my $cgi = CGI->new();
168
169 my %dlr = $kannel->receive_dlr($cgi);
170
171 print "DLR received for MSISDN: " . $dlr{from};
172
173 make_dlr_url(%params) - prepare DLR URL
174 This method creates URI escaped string with URL template for DLR
175 notification.
176
177 Paramters: hash (dlr_url, msgid)
178
179 Returns: URI escaped DLR URL
180
181 make_meta(%params) - prepare SMPP optional TLV
182 This method creates URI escaped string with optional SMPP
183 tag-lenght-value (TLV) parameters to send them in "meta-data" CGI
184 paramter of Kannel's "sendsms" HTTP API.
185
186 Format of "meta-data" parameter value:
187
188 ?smpp?tag1=value1&tag2=value2&...tagN=valueN
189
190 Paramters: hash of TLV pairs
191
192 Returns: URI escaped string
193
194 Example:
195
196 my $meta = $self->make_meta(
197 charging_id => '0',
198 );
199
200 This will return: %3Fsmpp%3Fcharging_id%3D0
201
202 status() - retrieve Kannel status
203 store_status() - retrieve message queue status
204 Not implemented yet.
205
206 shutdown() - bring down Kannel
207 suspend() - switch Kannel to 'suspended' state
208 isolate() - switch Kannel to 'isolated' state
209 resume() - resume Kannel to 'online' state
210 restart() - whole bearerbox restart
211 flush_dlr() - flush queued DLR if Kannel in 'suspended' state
212 reload_lists() - reload black/white lists
213 log_level($level) - change Kannel log-level
214 start_smsc($smsc) - switch on SMSC connection
215 stop_smsc($smsc) - switch off SMSC connection
216 add_smsc($smsc) - add new SMSC connection
217 remove_smsc($smsc) - remove SMSC connection
218
219 EXAMPLES
220 See Nibelite kannel API
221
222 SEE ALSO
223 * NetSDS::Class::Abstract - base NetSDS class
224 * <http://www.kannel.org/download/1.4.3/userguide-1.4.3/userguide.html>
225 - Kannel User Guide
226
227 TODO
228 1. Add PPG support.
229
230 2. Add OTA support.
231
232 AUTHOR
233 Michael Bochkaryov <[email protected]>
234
235 LICENSE
236 Copyright (C) 2008-2009 Net Style Ltd.
237
238 This program is free software; you can redistribute it and/or modify it
239 under the terms of the GNU General Public License as published by the
240 Free Software Foundation; either version 2 of the License, or (at your
241 option) any later version.
242
243 This program is distributed in the hope that it will be useful, but
244 WITHOUT ANY WARRANTY; without even the implied warranty of
245 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
246 Public License for more details.
247
248 You should have received a copy of the GNU General Public License along
249 with this program; if not, write to the Free Software Foundation, Inc.,
250 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
251