File: README

package info (click to toggle)
libnetsds-kannel-perl 1.300-6
  • links: PTS, VCS
  • area: main
  • in suites: buster, stretch
  • size: 240 kB
  • ctags: 172
  • sloc: perl: 482; makefile: 12
file content (251 lines) | stat: -rw-r--r-- 7,415 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
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:

                $kannel->send_sms(
                        from => '1234',
                        to => '380672206770',
                        text => 'Wake up!!!',
                        smsc => 'nokia_modem',
                );

    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