Debian Codegraph @

src/modules/sms/README

raw
1 SMS Module
2
3 Bogdan Iancu
4
5 FhG FOKUS
6
7 Copyright © 2003 FhG FOKUS
8 __________________________________________________________________
9
10 Table of Contents
11
12 1. Admin Guide
13
14 1. Overview
15
16 1.1. Hardware Requirements
17 1.2. Numbering Plan
18 1.3. Address Mapping
19
20 2. Dependencies
21 3. Parameters
22
23 3.1. modems (string)
24 3.2. networks (string)
25 3.3. links (string)
26 3.4. default_net (string)
27 3.5. max_sms_parts (integer)
28 3.6. domain (string)
29 3.7. use_contact (integer)
30 3.8. sms_report_type (integer)
31
32 4. Functions
33
34 4.1. sms_send_msg_to_net(network_name)
35 4.2. sms_send_msg()
36
37 List of Examples
38
39 1.1. Set modems parameter
40 1.2. Set networks parameter
41 1.3. Set links parameter
42 1.4. Set default_net parameter
43 1.5. Set max_sms_parts parameter
44 1.6. Set domain parameter
45 1.7. Set use_contact parameter
46 1.8. Set sms_report_type parameter
47 1.9. sms_send_msg_to_net usage
48 1.10. sms_send_msg usage
49
50 Chapter 1. Admin Guide
51
52 Table of Contents
53
54 1. Overview
55
56 1.1. Hardware Requirements
57 1.2. Numbering Plan
58 1.3. Address Mapping
59
60 2. Dependencies
61 3. Parameters
62
63 3.1. modems (string)
64 3.2. networks (string)
65 3.3. links (string)
66 3.4. default_net (string)
67 3.5. max_sms_parts (integer)
68 3.6. domain (string)
69 3.7. use_contact (integer)
70 3.8. sms_report_type (integer)
71
72 4. Functions
73
74 4.1. sms_send_msg_to_net(network_name)
75 4.2. sms_send_msg()
76
77 1. Overview
78
79 1.1. Hardware Requirements
80 1.2. Numbering Plan
81 1.3. Address Mapping
82
83 This module provides a way of communication between SIP network (via
84 SIP MESSAGE) and GSM networks (via ShortMessageService). Communication
85 is possible from SIP to SMS and vice versa. The module provides
86 facilities like SMS confirmation--the gateway can confirm to the SIP
87 user if his message really reached its destination as a SMS--or
88 multi-part messages--if a SIP messages is too long it will be split and
89 sent as multiple SMS.
90
91 Errors occurred because of an invalid number or a too long message or
92 because of an internal modem malfunction are reported back to the SIP
93 user via a SIP message containing explanations regarding the error.
94
95 1.1. Hardware Requirements
96
97 The SMS module needs a GSM modem to be able to send/receive the SMS
98 messages. Usually, this kind of modems are externals, linked to the
99 machine via serial cable. The modem can be a dedicated one (as the ones
100 provided by FALCOM) or can be a GSM telephone that has an internal
101 modem (as the latest mobile phones from NOKIA and ERICSSON).
102
103 1.2. Numbering Plan
104
105 The gateway accepts and advertises phone numbers in international
106 format, more specific like: +(international code)(area code)(number).
107 Ex: Germany, D1 = +49 170 5678181 Romania, Connex = +40 722 123456 A
108 number in this format is expected to be placed as username into RURI or
109 in the To header. If RURI misses the username, the To header will be
110 considered. Also, the gateway will advertise in this format the
111 username in Contact headers (in SIP replies and requests) and in From
112 headers (in SIP requests).
113
114 1.3. Address Mapping
115
116 To identify the destination number of the SMS, the gateway expects to
117 have a mobile number in username of the SIP destination address (for
118 example sip:[email protected]). For the reverse direction,
119 because the gateway has only one GSM number, the destination SIP
120 address has to be encapsulated into the SMS body. The gateway expects
121 to find a SIP address at the beginning of the SMS body in
122 "sip:user.host" format. Everything before the SIP address will be
123 discarded, the useful text begins exactly after the address (for
124 example SMS="For sip:user@host hello world!!" -> SIP="hello world"),
125 view configuration for disable this behavior (modems parameters 's' y
126 't'). In order to facilitate replying, the gateway sends all the SMS
127 messages with a header containing the source SIP address in the
128 following format: "From sip:user@host (if you reply DONOT remove
129 it)<new_line>". When an SMS-reply is received having this header (all
130 of it or truncated at the end), the header will be left out (it will
131 not be in the SIP message).
132
133 2. Dependencies
134
135 The following modules must be loaded before this module:
136 * tm - Transaction Manager.
137
138 3. Parameters
139
140 3.1. modems (string)
141 3.2. networks (string)
142 3.3. links (string)
143 3.4. default_net (string)
144 3.5. max_sms_parts (integer)
145 3.6. domain (string)
146 3.7. use_contact (integer)
147 3.8. sms_report_type (integer)
148
149 3.1. modems (string)
150
151 Define and configure one or more GSM modems.
152 modems_value = modem_definition *( ";" modem_definition )
153 modem_definition = modem_name "[" list_of_params "]"
154 list_of_params = modem_param *( ";" modem_param )
155 modem_param = name "=" value
156
157 The following parameters can be used:
158 * d=device (mandatory) - Device associated with modem (/dev/ttyS0,
159 /dev/modem, etc.).
160 * p=pin (optional) - SIM PIN - default is NULL.
161 * m=mode (optional) - Modem working mode
162 ("ASCII","OLD","DIGICOM","NEW"). Default value is "NEW".
163 * c=SMS_Center (optional) - SMS center number for that modem. Default
164 is the SMS center set on the SIM card.
165 * b=baudrate (optional) - Default is 19600.
166 * r=retry (optional) - How many times to try to re-send an SMS that
167 reported error. Default is twice.
168 * l=looping (optional) - Time for modem to wait before performing a
169 new check for incoming/outgoing SMS/SIP_MSG. Default is 20.
170 * t=to (optional) - uri for sip header TO. Default is NULL.
171 * s=scan (optional) - Values: 0: NOT SCAN uri from body sms, use URI
172 in t=to. 1: SCAN uri from body sms (normal mode, default mode,
173 classic mode) 2: SCAN MIX (both modes), First SCAN Default is 1
174 (SCAN).
175
176 Note
177
178 No default value, the parameter is mandatory.
179
180 Example 1.1. Set modems parameter
181 ...
182 modparam("sms", "modems", "Nokia[d=/dev/ttyS1;s=0;t=sip:[email protected]]")
183 modparam("sms", "modems", "Nokia [d=/dev/ttyS1;b=9600;m=new;l=30] ")
184 modparam("sms", "modems", "Nokia[d=/dev/ttyS1];Siemens[d=/dev/ttyS2]")
185 ...
186
187 3.2. networks (string)
188
189 Define and configure used GSM networks.
190 networks_value = net_definition *( ";" net_definition )
191 net_definition = net_name "[" list_of_params "]"
192 list_of_params = set_param *( ";" set_param )
193 set_param = name "=" value
194
195 The following parameters can be used:
196 * m=msx_sms_per_call (optional) - Maximum number of SMS send /
197 received from that net in one modem loop. Default is 10. This
198 parameter was introduced to avoid starvation.
199 Example of the starvation--a modem can send SMS for more than 1
200 networks. If you have a huge number of SMS for the first network
201 and the number of incoming SIP messages is equal to the sent SMS
202 per same unit of time, the modem will never get to send SMS for the
203 next networks.
204
205 Note
206
207 No default value, the parameter is mandatory.
208
209 Example 1.2. Set networks parameter
210 ...
211 modparam("sms", "networks", "D1 [m=10] ;d2[ m=20]")
212 ...
213
214 3.3. links (string)
215
216 Define from which network each modem should send SMS.
217 links_value = modem_assoc *( ";" modem_assoc )
218 modem_assoc = modem_name "[" list_of_networks "]"
219 list_of_networks = network *( ";" network )
220
221 Note
222
223 No default value, the parameter is mandatory.
224
225 Example 1.3. Set links parameter
226 ...
227 modparam("sms", "links", "NOKIA[D1;d2]")
228 ...
229
230 The modem NOKIA will send SMS from D1 and D2 net (in this order !). If
231 in a net queue are more than max_sms_per_call SMS the modem will not
232 sleep before starting the next loop ! Shortly, if messages are waiting
233 to be sent, the modem will not go in sleep.
234
235 3.4. default_net (string)
236
237 The default network to use. If no one specified, the first defined
238 network is used. This parameter is useful only if the "sms_send_msg"
239 exported function is used (see Section 4, “Functions”).
240
241 Example 1.4. Set default_net parameter
242 ...
243 modparam("sms", "default_net", "D1")
244 ...
245
246 3.5. max_sms_parts (integer)
247
248 Shows in how many parts (SMS messages) a SIP message can be split. If
249 exceeded, the SIP message will be sent truncated and the SIP user will
250 get back another message containing the unsent part.
251
252 Default value is 4.
253
254 Example 1.5. Set max_sms_parts parameter
255 ...
256 modparam("sms", "max_sms_parts", 10)
257 ...
258
259 3.6. domain (string)
260
261 Specify a fake domain name to be used by the gateway. The Contact
262 headers and the From header from the request will be constructed based
263 on this fake domain name. It's useful when the gateway is transparently
264 hidden behind a proxy/register (located on different machines).
265
266 Default is the name of the machine the gateway is running on.
267
268 Example 1.6. Set domain parameter
269 ...
270 modparam("sms", "domain", "foo.bar")
271 ...
272
273 3.7. use_contact (integer)
274
275 If a contact header should be added to the outgoing SIP messages. Even
276 if the SIP draft forbids this, some UAS require it.
277
278 Default is 0 (no).
279
280 Example 1.7. Set use_contact parameter
281 ...
282 modparam("sms", "use_contact", 1)
283 ...
284
285 3.8. sms_report_type (integer)
286
287 If the modem should ask for SMS confirmation from the SMS Center. If
288 the SMSC reply with an error code, the gateway will send back to SIP
289 user a SIP message containing the text (or part of it) that couldn't be
290 sent. Two report mechanisms are implemented:
291 * 1 - the reports are delivered by the GSM device as SMS reports (so
292 far supported only by Nokia modems);
293 * 2 - the reports are delivered as async. CDS responses (supported by
294 almost all modems, except Ericsson).
295
296 Default is 0 (no report).
297
298 Example 1.8. Set sms_report_type parameter
299 ...
300 modparam("sms", "sms_report_type", 1)
301 ...
302
303 4. Functions
304
305 4.1. sms_send_msg_to_net(network_name)
306 4.2. sms_send_msg()
307
308 4.1. sms_send_msg_to_net(network_name)
309
310 Put the SIP msg in the specified network queue. The function return
311 error if the number encapsulated into SIP message is malformed, if the
312 content_type is incorrect or because of some internal failures.
313
314 Meaning of the parameters is as follows:
315 * network_name - Name of network.
316
317 Example 1.9. sms_send_msg_to_net usage
318 ...
319 if (sms_send_msg_to_net("D1"))
320 {
321 if (!t_reply("202", "yes sir, SMS sent over"))
322 {
323 # if replying failed, retry statelessly
324 sl_reply_error();
325 };
326 } else {
327 if (!t_reply("502", "Bad gateway - SMS error"))
328 {
329 # if replying failed, retry statelessly
330 sl_reply_error();
331 };
332 break;
333 };
334 ...
335
336 4.2. sms_send_msg()
337
338 The same as the previous one, but use the default network queue.
339
340 Example 1.10. sms_send_msg usage
341 ...
342 if (sms_send_msg_to_net())
343 {
344 if (!t_reply("202", "yes sir, SMS sent over"))
345 {
346 # if replying failed, retry statelessly
347 sl_reply_error();
348 };
349 } else {
350 if (!t_reply("502", "Bad gateway - SMS error"))
351 {
352 # if replying failed, retry statelessly
353 sl_reply_error();
354 };
355 break;
356 };
357 ...