Browse code

modules/mohqueue: created text README file from doc source

Peter Dunkley authored on 08/10/2013 01:27:24
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,406 @@
0
+mohqueue Module
1
+
2
+Robert Boisvert
3
+
4
+   Copyright © 2013 Robert Boisvert, rdbprog@gmail.com
5
+     __________________________________________________________________
6
+
7
+   Table of Contents
8
+
9
+   1. Admin Guide
10
+
11
+        1. Overview
12
+        2. Dependencies
13
+
14
+              2.1. Kamailio Modules
15
+              2.2. External Libraries or Applications
16
+
17
+        3. Parameters
18
+
19
+              3.1. db_url (str)
20
+              3.2. db_qtable and db_ctable (str)
21
+              3.3. mohdir (str)
22
+              3.4. moh_maxcalls (integer)
23
+
24
+        4. Functions
25
+
26
+              4.1. mohq_process ()
27
+              4.2. mohq_send (queue_name)
28
+              4.3. mohq_retrieve (queue_name, URI)
29
+              4.4. mohq_count (queue_name, pvar)
30
+
31
+        5. Database Schema
32
+
33
+              5.1. MOHQUEUES Table
34
+              5.2. MOHQCALLS Table
35
+
36
+        6. Audio Files
37
+
38
+   List of Examples
39
+
40
+   1.1. Set db_url:
41
+   1.2. Set table names:
42
+   1.3. Set default directory for audio files:
43
+   1.4. Set default directory for audio files:
44
+   1.5. mohq_process usage:
45
+   1.6. mohq_send usage:
46
+   1.7. mohq_retrieve usage:
47
+   1.8. mohq_count usage:
48
+
49
+Chapter 1. Admin Guide
50
+
51
+   Table of Contents
52
+
53
+   1. Overview
54
+   2. Dependencies
55
+
56
+        2.1. Kamailio Modules
57
+        2.2. External Libraries or Applications
58
+
59
+   3. Parameters
60
+
61
+        3.1. db_url (str)
62
+        3.2. db_qtable and db_ctable (str)
63
+        3.3. mohdir (str)
64
+        3.4. moh_maxcalls (integer)
65
+
66
+   4. Functions
67
+
68
+        4.1. mohq_process ()
69
+        4.2. mohq_send (queue_name)
70
+        4.3. mohq_retrieve (queue_name, URI)
71
+        4.4. mohq_count (queue_name, pvar)
72
+
73
+   5. Database Schema
74
+
75
+        5.1. MOHQUEUES Table
76
+        5.2. MOHQCALLS Table
77
+
78
+   6. Audio Files
79
+
80
+1. Overview
81
+
82
+   The mohqueue module diverts INVITE requests into a Music On Hold (MOH)
83
+   queue where the caller can listen to recorded audio until an operator
84
+   is available to take the call. When an operator is available, a
85
+   function can be used to transfer the oldest call in a queue to an
86
+   operator using an unattended transfer (REFER) to a specified URI. If
87
+   successful, the call is removed from the queue.
88
+
89
+   While in queue, recorded audio is streamed to the caller in an endless
90
+   loop using the rtpproxy module and application. Each queue can be
91
+   configured to use different audio files.
92
+
93
+   The queues are defined in the database which allows for dynamic
94
+   configuration of the queues. Each queue is assigned a specific URI to
95
+   respond to and a location for the audio files.
96
+
97
+   As each call arrives the database is updated to show the call status
98
+   which allows outside processes to inspect the queue. It can also be
99
+   inspected using a function to see how many calls are currently in
100
+   queue.
101
+
102
+   While in queue, all SIP messages for a call must pass through the
103
+   mohqueue module so that it can accurately detect the call status.
104
+
105
+2. Dependencies
106
+
107
+   2.1. Kamailio Modules
108
+   2.2. External Libraries or Applications
109
+
110
+2.1. Kamailio Modules
111
+
112
+   The following modules must be loaded before this module:
113
+     * a database module
114
+     * sl module
115
+     * tm module
116
+     * rtpproxy module
117
+
118
+2.2. External Libraries or Applications
119
+
120
+   The rtpproxy applications supported by the rtpproxy module (e.g.
121
+   http://www.b2bua.org/wiki/RTPproxy).
122
+
123
+3. Parameters
124
+
125
+   3.1. db_url (str)
126
+   3.2. db_qtable and db_ctable (str)
127
+   3.3. mohdir (str)
128
+   3.4. moh_maxcalls (integer)
129
+
130
+3.1. db_url (str)
131
+
132
+   The URL to connect to the database for the mohqueue tables.
133
+
134
+   Default value for Kamailio.
135
+
136
+   Example 1.1. Set db_url:
137
+...
138
+modparam ("mohqueue", "db_url", "mysql://kamailio:kamailiorw@localhost/kamailio
139
+")
140
+...
141
+
142
+3.2. db_qtable and db_ctable (str)
143
+
144
+   db_qtable is the name of the table that defines the queues and
145
+   db_ctable is the table that maintains the call status.
146
+
147
+   "MOHQUEUES" for db_qtable and "MOHQCALLS" for db_ctable.
148
+
149
+   Example 1.2. Set table names:
150
+...
151
+modparam ("mohqueue", "db_qtable", "mqueues")
152
+modparam ("mohqueue", "db_ctable", "mcalls")
153
+...
154
+
155
+3.3. mohdir (str)
156
+
157
+   Path to the directory where the audio files are stored. Audio files are
158
+   usually relative to this directory although the value can be overridden
159
+   by a directory specified in the queues table.
160
+
161
+   None. If not set by the module it must be defined in the queues table.
162
+
163
+   Example 1.3. Set default directory for audio files:
164
+...
165
+modparam ("mohqueue", "mohdir", "/var/kamailio/MOH")
166
+...
167
+
168
+3.4. moh_maxcalls (integer)
169
+
170
+   Defines the maximum number of calls that can be placed in queue. It is
171
+   the sum of all calls in all queues. It must be in the range of 1 to
172
+   5000. NOTE: it may be limited by the processing power of the server or
173
+   the number of available rtpproxy ports.
174
+
175
+   None. If not set by the module it must be defined in the queues table.
176
+
177
+   Example 1.4. Set default directory for audio files:
178
+...
179
+modparam ("mohqueue", "mohdir", "/var/kamailio/MOH")
180
+...
181
+
182
+4. Functions
183
+
184
+   4.1. mohq_process ()
185
+   4.2. mohq_send (queue_name)
186
+   4.3. mohq_retrieve (queue_name, URI)
187
+   4.4. mohq_count (queue_name, pvar)
188
+
189
+4.1.  mohq_process ()
190
+
191
+   Checks to see if the current SIP message involves a queue. If it does
192
+   it will process the message and return a TRUE value.
193
+
194
+   In order for mohqueue to detect changes in the call it is necessary
195
+   that all messages involving the call be processed through this
196
+   function. The easiest way is to accomplish this is to place it at the
197
+   beginning of the main route of the script.
198
+
199
+   mohqueue calls are identified by an RURI that matches a queue URI. Once
200
+   a call is placed in queue it checks the To header field along with the
201
+   RURI to find a match, except in the case of a CANCEL which matches only
202
+   on the RURI.
203
+
204
+   This function has no parameters and must be called from a request
205
+   route.
206
+
207
+   Return code:
208
+     * TRUE=successful and call in queue
209
+     * FALSE=failed, unrecognized URI or unable to place in queue
210
+
211
+   Example 1.5. mohq_process usage:
212
+...
213
+request_route {
214
+  # main route with limited processing
215
+...
216
+  # MOH queue?
217
+  if (mohq_process ()) {
218
+    xlog ("L_DBG", "Handled by mohqueue");
219
+    exit;
220
+  }
221
+  # An error or not a MOH queue message; continue processing
222
+...
223
+}
224
+...
225
+
226
+4.2.  mohq_send (queue_name)
227
+
228
+   Normally calls enter the queue with an initial INVITE message that 1)
229
+   has a RURI that matches a queue URI and 2) is passed through mohq_proc
230
+   (), which is the preferred method.
231
+
232
+   This function is used when you wish to send a call into a queue that
233
+   does not match the queue URI.
234
+
235
+   It has only one parameter, the name of the queue, and must be called
236
+   from the request route with an initial INVITE message. The queue name
237
+   can be passed as a literal or pseudo-variable.
238
+
239
+   Return code:
240
+     * TRUE=successful and call in queue
241
+     * FALSE=failed, unable to place in queue
242
+
243
+   Example 1.6. mohq_send usage:
244
+...
245
+  # call is initial INVITE and ready for queue?
246
+  if (some test) {
247
+    if (mohq_send ("main")) {
248
+      xlog ("L_DBG", "Sent call to main mohqueue");
249
+      exit;
250
+    }
251
+    # failed to enter queue!
252
+    ...
253
+  }
254
+...
255
+
256
+4.3.  mohq_retrieve (queue_name, URI)
257
+
258
+   Retrieves the oldest call in a queue and redirects it to a URI.
259
+   Although the function returns, the transfer of the call may not have
260
+   completed since the new URI (operator) must answer the call.
261
+
262
+   It has two parameters, the queue name and the URI to REFER the call to,
263
+   both which can be passed as literals or pseudo-variables. It can be
264
+   called from any route.
265
+
266
+   Return code:
267
+     * TRUE=successful, transfer started
268
+     * FALSE=failed, parameters are incorrect or there are no calls in
269
+       queue
270
+
271
+   Example 1.7. mohq_retrieve usage:
272
+...
273
+#!define MOHQNAME "operators"
274
+#!define CGROUP   "sip:operators@10.211.64.5"
275
+...
276
+  # redirect oldest call to operator call group
277
+  if (mohq_retrieve (MOHQNAME, CGROUP)) {
278
+      xlog ("L_DBG", "Retrieved call from mohqueue");
279
+      exit;
280
+    }
281
+  # queue is empty or something went wrong
282
+  }
283
+...
284
+
285
+4.4.  mohq_count (queue_name, pvar)
286
+
287
+   Finds the number of calls that are in a queue. It will not count calls
288
+   that are in the process of entering or exiting the queue.
289
+
290
+   The function has two parameters, the name of the queue and the
291
+   pseudo-variable which receives the count. The queue name can be passed
292
+   as a literal or a pseudo-variable. It can be called from any route.
293
+
294
+   Return code:
295
+     * TRUE=successful, pseudo-variable contains count
296
+     * FALSE=failed, parameters are incorrect
297
+
298
+   Example 1.8. mohq_count usage:
299
+...
300
+$var(mohq) = "operators";
301
+...
302
+  # more than 10 calls?
303
+  mohq_count ("$var(mohq)", "$var(mohqcnt)");
304
+  if ($var(mohqcnt) > 10) {
305
+    xlog ("L_WARN", "$var(mohq) queue has $var(mohqcnt) calls!");
306
+  }
307
+...
308
+
309
+5. Database Schema
310
+
311
+   5.1. MOHQUEUES Table
312
+   5.2. MOHQCALLS Table
313
+
314
+   mohqueue uses two external database tables to manage the queues and
315
+   provide status information to outside processes. Internally, it keeps a
316
+   volatile database in memory of call status. If the module is restarted
317
+   it loses the internal database and clears the external one.
318
+
319
+   On a reqular basis it checks the external table that defines the queues
320
+   to see if the definition has changed. It makes this check under the
321
+   following conditions: the queue has not been checked in the last 60
322
+   seconds AND no call is currently in queue or transitioning in or out.
323
+   The last condition prevents existing calls from being adversely
324
+   affected by queue redefinitions.
325
+
326
+5.1. MOHQUEUES Table
327
+
328
+   This table controls the definition of the queue. The name is set by the
329
+   db_qtable parameter. There is no internal function to modify the table
330
+   so it must be configured externally. It contains the following fields:
331
+     * id (integer): unique identifier that is created automatically. Do
332
+       not attempt to change this value.
333
+     * name (25-character string, required): the queue name. Duplicate
334
+       names are not allowed.
335
+     * uri (100-character string, required): the URI of the queue. It
336
+       should not include any parameters or headers (e.g.
337
+       "sip:user@host;maddr=239.255.255.1" or
338
+       "sip:user@host?subject=project") although it will match any RURI
339
+       that contains this URI even if the RURI has parameters or headers.
340
+       Duplicates are not allowed.
341
+     * mohdir (100-character string, optional): path to the directory
342
+       where the audio files for the queue are stored. This path overrides
343
+       the one provided by the mohdir parameter. If the directory is not
344
+       accessible by the module the queue is not activated.
345
+     * mohfile (100-character string, required): the base name of the
346
+       audio file. See the section about audio files for more information
347
+       about file names. If no files matching this name are found in the
348
+       directory the queue is not activated.
349
+     * debug (integer, required): enables debugging messages for the
350
+       queue. If non-zero, it will send debugging messages to the log for
351
+       conditions that involve the queue, whether or not Kamailio has
352
+       logging enabled for debugging. If zero, it depends on Kamailio's
353
+       log level.
354
+
355
+5.2. MOHQCALLS Table
356
+
357
+   This table contains the status of calls that are in queue, or
358
+   transitioning in or out of a queue. The name is set by the db_ctable
359
+   parameter. This table is read-only for external processes and its
360
+   contents should not be modified. It contains the following fields:
361
+     * id (integer): unique identifier that is created automatically.
362
+     * mohq_id (integer, required): the id value of the queue.
363
+     * call_status (integer, required): the status of the call.
364
+       1=entering; 2=in queue (listening to MOH); 3=leaving
365
+     * call_from (100-character string, required): the contents of the
366
+       From header field.
367
+     * call_id (100-character string, required): the contents of the
368
+       Call-ID header field.
369
+     * call_contact (100-character string, optional): the contents of the
370
+       Contact header field, if it exists.
371
+     * call_time (datetime, required): time the call entered the queue. If
372
+       a retrieve fails this time is not changed.
373
+
374
+6. Audio Files
375
+
376
+   When rtpproxy negotiates to determine which media to use in the audio
377
+   stream it uses the files in the MOH directory as defined by the
378
+   MOHQUEUES table. The table defines the location of the files and the
379
+   base name used to identify each. The actual stream type depends on the
380
+   RTP payload number that is part of the name. The complete file name for
381
+   each stream is composed of mohdir/mohfile.type. For example,
382
+   /var/kamailio/MOH/HeWillCall.8 would be the file for payload type 8
383
+   (PCMA/8000).
384
+
385
+   The supported types and their order of preference are:
386
+     * 9: G722/8000
387
+     * 0: PCMU/8000
388
+     * 8: PCMA/8000
389
+     * 18: G729/8000
390
+     * 3: GSM/8000
391
+     * 4: G723/8000
392
+     * 15: G728/8000
393
+     * 5: DVI4/8000
394
+     * 7: LPC/8000
395
+     * 12: QCELP/8000
396
+     * 13: CN/8000
397
+     * 16: DVI4/11025
398
+     * 6: DVI4/16000
399
+     * 17: DVI4/22050
400
+     * 10: L16/44100
401
+     * 11: L16/44100
402
+     * 14: MPA/90000
403
+
404
+   See RTP Audio Video Profile for more information about RTP payload
405
+   types.