Browse code

modules: readme files regenerated - htable ... [skip ci]

Kamailio Dev authored on 23/01/2022 19:01:22
Showing 1 changed files
... ...
@@ -1 +1,1304 @@
1
+HTable Module
1 2
 
3
+Elena-Ramona Modroiu
4
+
5
+   asipto.com
6
+   <ramona@rosdev.ro>
7
+
8
+Edited by
9
+
10
+Elena-Ramona Modroiu
11
+
12
+   <ramona@rosdev.ro>
13
+
14
+Alex Balashov
15
+
16
+   <abalashov@evaristesys.com>
17
+
18
+Ovidiu Sas
19
+
20
+   <osas@voipembedded.com>
21
+
22
+   Copyright © 2008-2011 http://www.asipto.com
23
+     __________________________________________________________________
24
+
25
+   Table of Contents
26
+
27
+   1. Admin Guide
28
+
29
+        1. Overview
30
+        2. Dependencies
31
+
32
+              2.1. Kamailio Modules
33
+              2.2. External Libraries or Applications
34
+              2.3. Loading from database
35
+
36
+        3. Parameters
37
+
38
+              3.1. htable (str)
39
+              3.2. db_url (str)
40
+              3.3. key_name_column (str)
41
+              3.4. key_type_column (str)
42
+              3.5. value_type_column (str)
43
+              3.6. key_value_column (str)
44
+              3.7. expires_column (str)
45
+              3.8. array_size_suffix (str)
46
+              3.9. fetch_rows (integer)
47
+              3.10. timer_interval (integer)
48
+              3.11. db_expires (integer)
49
+              3.12. enable_dmq (integer)
50
+              3.13. dmq_init_sync (integer)
51
+              3.14. timer_procs (integer)
52
+              3.15. event_callback (str)
53
+              3.16. event_callback_mode (int)
54
+
55
+        4. Functions
56
+
57
+              4.1. sht_print()
58
+              4.2. sht_rm(htname, itname)
59
+              4.3. sht_rm_name_re(htable=>regexp)
60
+              4.4. sht_rm_value_re(htable=>regexp)
61
+              4.5. sht_rm_name(htable, op, val)
62
+              4.6. sht_rm_value(htable, op, val)
63
+              4.7. sht_reset(htable)
64
+              4.8. sht_lock(htable=>key)
65
+              4.9. sht_unlock(htable=>key)
66
+              4.10. sht_iterator_start(iname, hname)
67
+              4.11. sht_iterator_end(iname)
68
+              4.12. sht_iterator_next(iname)
69
+              4.13. sht_iterator_rm(iname)
70
+              4.14. sht_iterator_sets(iname, sval)
71
+              4.15. sht_iterator_seti(iname, ival)
72
+              4.16. sht_iterator_setex(iname, exval)
73
+              4.17. sht_match_name(htable, op, mval)
74
+              4.18. sht_has_name(htable, op, mval)
75
+              4.19. sht_match_str_value(htable, op, mval)
76
+              4.20. sht_has_str_value(htable, op, mval)
77
+
78
+        5. Exported pseudo-variables
79
+        6. RPC Commands
80
+
81
+              6.1. htable.get htable key
82
+              6.2. htable.delete htable key
83
+              6.3. htable.sets htable key value
84
+              6.4. htable.seti htable key value
85
+              6.5. htable.setex htable key expire
86
+              6.6. htable.dump htable
87
+              6.7. htable.reload htable
88
+              6.8. htable.store htable
89
+              6.9. htable.flush htable
90
+              6.10. htable.listTables
91
+              6.11. htable.stats
92
+
93
+        7. Event routes
94
+
95
+              7.1. htable:mod-init
96
+              7.2. htable:expired:<table>
97
+
98
+   List of Examples
99
+
100
+   1.1. Accessing $sht(htname=>key)
101
+   1.2. Dictionary attack limitation
102
+   1.3. Storing array values
103
+   1.4. Set htable parameter
104
+   1.5. Set db_url parameter
105
+   1.6. Set key_name_column parameter
106
+   1.7. Set key_type_column parameter
107
+   1.8. Set value_type_column parameter
108
+   1.9. Set key_value_column parameter
109
+   1.10. Set expires_column parameter
110
+   1.11. Set array_size_suffix parameter
111
+   1.12. Set fetch_rows parameter
112
+   1.13. Set timer_interval parameter
113
+   1.14. Set db_expires parameter
114
+   1.15. Set enable_dmq parameter
115
+   1.16. Set dmq_init_sync parameter
116
+   1.17. Set timer_procs parameter
117
+   1.18. Set event_callback parameter
118
+   1.19. Set event_callback_mode parameter
119
+   1.20. sht_print usage
120
+   1.21. sht_rm usage
121
+   1.22. sht_rm_name_re usage
122
+   1.23. sht_rm_value_re usage
123
+   1.24. sht_rm_name usage
124
+   1.25. sht_rm_value usage
125
+   1.26. sht_reset usage
126
+   1.27. sht_lock usage
127
+   1.28. sht_unlock usage
128
+   1.29. sht_iterator_start usage
129
+   1.30. sht_iterator_end usage
130
+   1.31. sht_iterator_next usage
131
+   1.32. sht_iterator_rm usage
132
+   1.33. sht_iterator_sets usage
133
+   1.34. sht_iterator_seti usage
134
+   1.35. sht_iterator_setex usage
135
+   1.36. sht_match_name usage
136
+   1.37. sht_match_name usage
137
+
138
+Chapter 1. Admin Guide
139
+
140
+   Table of Contents
141
+
142
+   1. Overview
143
+   2. Dependencies
144
+
145
+        2.1. Kamailio Modules
146
+        2.2. External Libraries or Applications
147
+        2.3. Loading from database
148
+
149
+   3. Parameters
150
+
151
+        3.1. htable (str)
152
+        3.2. db_url (str)
153
+        3.3. key_name_column (str)
154
+        3.4. key_type_column (str)
155
+        3.5. value_type_column (str)
156
+        3.6. key_value_column (str)
157
+        3.7. expires_column (str)
158
+        3.8. array_size_suffix (str)
159
+        3.9. fetch_rows (integer)
160
+        3.10. timer_interval (integer)
161
+        3.11. db_expires (integer)
162
+        3.12. enable_dmq (integer)
163
+        3.13. dmq_init_sync (integer)
164
+        3.14. timer_procs (integer)
165
+        3.15. event_callback (str)
166
+        3.16. event_callback_mode (int)
167
+
168
+   4. Functions
169
+
170
+        4.1. sht_print()
171
+        4.2. sht_rm(htname, itname)
172
+        4.3. sht_rm_name_re(htable=>regexp)
173
+        4.4. sht_rm_value_re(htable=>regexp)
174
+        4.5. sht_rm_name(htable, op, val)
175
+        4.6. sht_rm_value(htable, op, val)
176
+        4.7. sht_reset(htable)
177
+        4.8. sht_lock(htable=>key)
178
+        4.9. sht_unlock(htable=>key)
179
+        4.10. sht_iterator_start(iname, hname)
180
+        4.11. sht_iterator_end(iname)
181
+        4.12. sht_iterator_next(iname)
182
+        4.13. sht_iterator_rm(iname)
183
+        4.14. sht_iterator_sets(iname, sval)
184
+        4.15. sht_iterator_seti(iname, ival)
185
+        4.16. sht_iterator_setex(iname, exval)
186
+        4.17. sht_match_name(htable, op, mval)
187
+        4.18. sht_has_name(htable, op, mval)
188
+        4.19. sht_match_str_value(htable, op, mval)
189
+        4.20. sht_has_str_value(htable, op, mval)
190
+
191
+   5. Exported pseudo-variables
192
+   6. RPC Commands
193
+
194
+        6.1. htable.get htable key
195
+        6.2. htable.delete htable key
196
+        6.3. htable.sets htable key value
197
+        6.4. htable.seti htable key value
198
+        6.5. htable.setex htable key expire
199
+        6.6. htable.dump htable
200
+        6.7. htable.reload htable
201
+        6.8. htable.store htable
202
+        6.9. htable.flush htable
203
+        6.10. htable.listTables
204
+        6.11. htable.stats
205
+
206
+   7. Event routes
207
+
208
+        7.1. htable:mod-init
209
+        7.2. htable:expired:<table>
210
+
211
+1. Overview
212
+
213
+   The module adds a hash table container to the configuration language.
214
+   The hash table is stored in shared memory and the access to it can be
215
+   done via pseudo-variables: $sht(htname=>name). The module supports
216
+   definition of many hash tables and can load values at startup from a
217
+   database table.
218
+
219
+   A typical use case for the SIP server is to implement a cache system in
220
+   configuration file - if a value is not found in hash table, load it
221
+   from database and store it in hash table so next time the access to it
222
+   is very fast. In the definition of the table you can define the default
223
+   expiration time of cached items. The expiration time can be adjusted
224
+   per item via assignment operation at runtime.
225
+
226
+   Replication between multiple servers is performed automatically (if
227
+   enabled) via the DMQ module.
228
+
229
+   You can read more about hash tables at:
230
+   http://en.wikipedia.org/wiki/Hash_table.
231
+
232
+   The “name” can be a static string or can include pseudo- variables that
233
+   will be replaced at runtime.
234
+
235
+   Example 1.1. Accessing $sht(htname=>key)
236
+...
237
+modparam("htable", "htable", "a=>size=8;")
238
+...
239
+$sht(a=>test) = 1;
240
+$sht(a=>$ci::srcip) = $si;
241
+...
242
+
243
+   The next example shows a way to protect against dictionary attacks. If
244
+   someone fails to authenticate 3 times, it is forbidden for 15 minutes.
245
+   Authentication against database is expensive as it does a select on the
246
+   “subscriber” table. By disabling the DB auth for 15 minutes, resources
247
+   on the server are saved and time to discover the password is increased
248
+   substantially. Additional alerting can be done by writing a message to
249
+   syslog or sending email, etc.
250
+
251
+   To implement the logic, two hash table variables are used: one counting
252
+   the failed authentications per user and one for storing the time of the
253
+   last authentication attempt. To ensure a unique name per user, the hash
254
+   table uses a combination of authentication username and text
255
+   “::auth_count” and “::last_auth”.
256
+
257
+   Example 1.2. Dictionary attack limitation
258
+...
259
+modparam("htable", "htable", "a=>size=8;")
260
+...
261
+if(is_present_hf("Authorization"))
262
+{
263
+    if($sht(a=>$au::auth_count)==3)
264
+    {
265
+                $var(exp) = $Ts - 900;
266
+        if($sht(a=>$au::last_auth) > $var(exp))
267
+        {
268
+            sl_send_reply("403", "Try later");
269
+            exit;
270
+        } else {
271
+            $sht(a=>$au::auth_count) = 0;
272
+        }
273
+    }
274
+    if(!www_authenticate("$td", "subscriber"))
275
+    {
276
+        switch ($retcode) {
277
+            case -1:
278
+                sl_send_reply("403", "Forbidden");
279
+            exit;
280
+            case -2:
281
+                if($sht(a=>$au::auth_count) == $null)
282
+                    $sht(a=>$au::auth_count) = 0;
283
+                $sht(a=>$au::auth_count) = $sht(a=>$au::auth_count) + 1;
284
+                if($sht(a=>$au::auth_count) == 3)
285
+                    xlog("auth failed 3rd time - src ip: $si\n");
286
+                $sht(a=>$au::last_auth) = $Ts;
287
+            break;
288
+        }
289
+        www_challenge("$td"/*realm*/,"0"/*qop*/);
290
+        exit;
291
+    }
292
+    $sht(a=>$au::auth_count) = 0;
293
+} else {
294
+    www_challenge("$td","0");
295
+    exit;
296
+}
297
+...
298
+
299
+   The module also provides a way to store multiple values for a single
300
+   key. This is emulated by storing individual keys as 'key_name[n]',
301
+   where n is incremented for each key. The total number of keys is stored
302
+   in a dedicated key, by default: 'key_name::size'.
303
+
304
+   The array is built when the table is loaded in memory and afterwards
305
+   all the keys are treated as individual keys. If a particular entry in
306
+   the array is deleted, it is the administrator's responsibility to
307
+   update the size of the array and any other elements (if required).
308
+
309
+   Example 1.3. Storing array values
310
+# Example of dbtext with multiple keys
311
+$ cat /usr/local/etc/kamailio/dbtext/htable
312
+1:key:1:0:value3:0
313
+2:key:1:0:value2:0
314
+3:key:1:0:value1:0
315
+
316
+# The array key will be loaded in memory in the following format:
317
+$ kamcmd htable.dump htable
318
+{
319
+        entry: 35
320
+        size: 1
321
+        slot: {
322
+                item: {
323
+                        name: key[0]
324
+                        value: value1
325
+                }
326
+        }
327
+}
328
+{
329
+        entry: 50
330
+        size: 1
331
+        slot: {
332
+                item: {
333
+                        name: key::size
334
+                        value: 3
335
+                }
336
+        }
337
+}
338
+{
339
+        entry: 67
340
+        size: 1
341
+        slot: {
342
+                item: {
343
+                        name: key[1]
344
+                        value: value2
345
+                }
346
+        }
347
+}
348
+{
349
+        entry: 227
350
+        size: 1
351
+        slot: {
352
+                item: {
353
+                        name: key[2]
354
+                        value: value3
355
+                }
356
+        }
357
+}
358
+
359
+# Now let's delete a particular entry in the array: key[0].
360
+$ kamcmd htable.delete htable key[0]
361
+
362
+# The array key will look like this after a key was deleted:
363
+$ kamcmd htable.dump htable
364
+{
365
+        entry: 50
366
+        size: 1
367
+        slot: {
368
+                item: {
369
+                        name: key::size
370
+                        value: 3
371
+                }
372
+        }
373
+}
374
+{
375
+        entry: 67
376
+        size: 1
377
+        slot: {
378
+                item: {
379
+                        name: key[1]
380
+                        value: value2
381
+                }
382
+        }
383
+}
384
+{
385
+        entry: 227
386
+        size: 1
387
+        slot: {
388
+                item: {
389
+                        name: key[2]
390
+                        value: value3
391
+                }
392
+        }
393
+}
394
+
395
+2. Dependencies
396
+
397
+   2.1. Kamailio Modules
398
+   2.2. External Libraries or Applications
399
+   2.3. Loading from database
400
+
401
+2.1. Kamailio Modules
402
+
403
+   The following modules must be loaded before this module:
404
+     * If DMQ replication is enabled, the DMQ module must be loaded
405
+       first..
406
+
407
+2.2. External Libraries or Applications
408
+
409
+   The following libraries or applications must be installed before
410
+   running Kamailio with this module loaded:
411
+     * None.
412
+
413
+2.3. Loading from database
414
+
415
+   The module is able to load values in a hash table at startup upon
416
+   providing a DB URL and table name.
417
+
418
+   The structure of the table must contain:
419
+     * key name - string containing the name of the key.
420
+     * key type - the type of the key
421
+          + 0 - simple key - the key is added as 'key_name'.
422
+          + 1 - array key - the key is added as 'key_name[n]' - n is
423
+            incremented for each key with this name to build an array in
424
+            hash table. In addition, an additional key is built to hold
425
+            the total number of key in the array, by default
426
+            key_name::size (see array_size_suffix parameter).
427
+     * value type - the type of the key value
428
+          + 0 - value is string.
429
+          + 1 - value is integer.
430
+     * key value - string containing the value of the key.
431
+
432
+3. Parameters
433
+
434
+   3.1. htable (str)
435
+   3.2. db_url (str)
436
+   3.3. key_name_column (str)
437
+   3.4. key_type_column (str)
438
+   3.5. value_type_column (str)
439
+   3.6. key_value_column (str)
440
+   3.7. expires_column (str)
441
+   3.8. array_size_suffix (str)
442
+   3.9. fetch_rows (integer)
443
+   3.10. timer_interval (integer)
444
+   3.11. db_expires (integer)
445
+   3.12. enable_dmq (integer)
446
+   3.13. dmq_init_sync (integer)
447
+   3.14. timer_procs (integer)
448
+   3.15. event_callback (str)
449
+   3.16. event_callback_mode (int)
450
+
451
+3.1. htable (str)
452
+
453
+   The definition of a hash table. The value of the parameter may have the
454
+   following format:
455
+     * "htname=>size=_number_;autoexpire=_number_;dbtable=_string_"
456
+
457
+   The parameter can be set multiple times to get more hash tables in same
458
+   configuration file.
459
+     * htname - string specifying the name of the hash table. This string
460
+       is used by $sht(...) to refer to the hash table.
461
+     * size - number to control how many slots (buckets) to create for the
462
+       hash table. Larger value means more slots with higher probability
463
+       for less collisions. The actual number slots (or buckets) created
464
+       for the table is 2^size. The possible range for this value is from
465
+       2 to 31, smaller or larger values will be increased to 3 (8 slots)
466
+       or decreased to 14 (16384 slots). Note that each slot can store
467
+       more than one item, when there are collisions of hash ids computed
468
+       for keys. The items in the same slot are stored in a linked list.
469
+       In other words, the size is not setting a limit of how many items
470
+       can be stored in a hash table, as long as there is enough free
471
+       shared memory, new items can be added.
472
+     * autoexpire -time in seconds to delete an item from a hash table if
473
+       no update was done to it. If is missing or set to 0, the items
474
+       won't expire.
475
+     * dbtable - name of database to be loaded at startup in hash table.
476
+       If empty or missing, no data will be loaded.
477
+     * cols - the column names of the database table. They must be
478
+       enclosed in quotes in order to form a valid SIP parameter value and
479
+       be separated by comma. The first column corresponds to key_name.
480
+       When specified, there must be at least two columns. If this
481
+       attribute is not specified, then the global module parameters for
482
+       column names are used. If more than one value columns are
483
+       specified, the hash table will pack the column values in a comma
484
+       separated string, which will be associated with the key (string
485
+       transformation {s.select,...} can be used in configuration file to
486
+       extract a specific column value). When cols attribute is present,
487
+       writing back to database table is disabled.
488
+     * dbmode - if set to 1, the content of hash table is written to
489
+       database table when the SIP server is stopped (i.e., ensure
490
+       persistency over restarts). Default value is 0 (no write back to db
491
+       table).
492
+     * initval - the integer value to be returned instead of $null when a
493
+       requested key is not set.
494
+     * updateexpire - if set to 1 (default), the time until expiration of
495
+       an item is reset when that item is updated. Certain uses of htable
496
+       may dictate that updates should not reset the expiration timeout,
497
+       however, in which case this attribute can be set to 0.
498
+     * dmqreplicate - if set to 1, any actions (set, update, delete etc.)
499
+       performed upon entries in this table will be replicated to other
500
+       nodes (htable peers). Please note, module parameter “enable_dmq”
501
+       must also be set in order for this to apply (see below). Default is
502
+       0 (no replication).
503
+
504
+   Default value is NULL.
505
+
506
+   Example 1.4. Set htable parameter
507
+...
508
+modparam("htable", "htable", "a=>size=4;autoexpire=7200;dbtable=htable_a;")
509
+modparam("htable", "htable", "b=>size=5;")
510
+modparam("htable", "htable", "c=>size=4;autoexpire=7200;initval=1;dmqreplicate=1
511
+;")
512
+...
513
+
514
+3.2. db_url (str)
515
+
516
+   The URL to connect to database for loading values in hash table at
517
+   start up.
518
+
519
+   Default value is NULL (do not connect).
520
+
521
+   Example 1.5. Set db_url parameter
522
+...
523
+modparam("htable", "db_url", "mysql://kamailio:kamailiorw@localhost/kamailio")
524
+...
525
+
526
+3.3. key_name_column (str)
527
+
528
+   The name of the column containing the hash table key name.
529
+
530
+   Default value is 'key_name'.
531
+
532
+   Example 1.6. Set key_name_column parameter
533
+...
534
+modparam("htable", "key_name_column", "kname")
535
+...
536
+
537
+3.4. key_type_column (str)
538
+
539
+   The name of the column containing the hash table key type.
540
+
541
+   Default value is 'key_type'.
542
+
543
+   Example 1.7. Set key_type_column parameter
544
+...
545
+modparam("htable", "key_type_column", "ktype")
546
+...
547
+
548
+3.5. value_type_column (str)
549
+
550
+   The name of the column containing the hash table value type.
551
+
552
+   Default value is 'value_type'.
553
+
554
+   Example 1.8. Set value_type_column parameter
555
+...
556
+modparam("htable", "value_type_column", "vtype")
557
+...
558
+
559
+3.6. key_value_column (str)
560
+
561
+   The name of the column containing hash table key value.
562
+
563
+   Default value is 'key_value'.
564
+
565
+   Example 1.9. Set key_value_column parameter
566
+...
567
+modparam("htable", "key_value_column", "kvalue")
568
+...
569
+
570
+3.7. expires_column (str)
571
+
572
+   The name of the column containing the expires value.
573
+
574
+   Default value is 'expires'.
575
+
576
+   Example 1.10. Set expires_column parameter
577
+...
578
+modparam("htable", "expires_column", "expiry")
579
+...
580
+
581
+3.8. array_size_suffix (str)
582
+
583
+   The suffix to be added to store the number of items in an array (see
584
+   key type).
585
+
586
+   Default value is '::size'.
587
+
588
+   Example 1.11. Set array_size_suffix parameter
589
+...
590
+modparam("htable", "array_size_suffix", "-count")
591
+...
592
+
593
+3.9. fetch_rows (integer)
594
+
595
+   How many rows to fetch at once from database.
596
+
597
+   Default value is 100.
598
+
599
+   Example 1.12. Set fetch_rows parameter
600
+...
601
+modparam("htable", "fetch_rows", 1000)
602
+...
603
+
604
+3.10. timer_interval (integer)
605
+
606
+   Interval in seconds to check for expired htable values.
607
+
608
+   Default value is 20.
609
+
610
+   Example 1.13. Set timer_interval parameter
611
+...
612
+modparam("htable", "timer_interval", 10)
613
+...
614
+
615
+3.11. db_expires (integer)
616
+
617
+   If set to 1, the module loads/saves the value for expire of the items
618
+   in hash table from/to database. It applies only to hash tables that
619
+   have the auto-expires attribute defined. If set to 0, only the key name
620
+   and the value are loaded, the expires for each item being set to 0.
621
+
622
+   Note that the module is not reloading automatically the items from
623
+   database when they expire, the reloading can be done only via RPC
624
+   command.
625
+
626
+   Default value is 0.
627
+
628
+   Example 1.14. Set db_expires parameter
629
+...
630
+modparam("htable", "db_expires", 1)
631
+...
632
+
633
+3.12. enable_dmq (integer)
634
+
635
+   If set to 1, will enable DMQ replication of actions performed upon
636
+   entries in all tables having "dmqreplicate" parameter set. Any update
637
+   action performed via pseudo-variables and RPC commands will be repeated
638
+   on all other nodes. Therefore, it is important to ensure the table
639
+   definition (size, autoexpire etc.) is identical across all instances.
640
+
641
+   Important: If this parameter is enabled, the DMQ module must be loaded
642
+   first - otherwise, startup will fail.
643
+
644
+   Currently, values are not replicated on load from DB as it is expected
645
+   that in these cases, all servers will load their values from the same
646
+   DB.
647
+
648
+   Default value is 0.
649
+
650
+   Example 1.15. Set enable_dmq parameter
651
+...
652
+modparam("htable", "enable_dmq", 1)
653
+...
654
+
655
+3.13. dmq_init_sync (integer)
656
+
657
+   If set to 1, will request synchronization from other nodes at startup.
658
+   It applies to all tables having the "dmqreplicate" parameter set. As
659
+   above, it is important to ensure the definition (size, autoexpire etc.)
660
+   of replicated tables is identical across all instances.
661
+
662
+   Default value is 0.
663
+
664
+   Example 1.16. Set dmq_init_sync parameter
665
+...
666
+modparam("htable", "dmq_init_sync", 1)
667
+...
668
+
669
+3.14. timer_procs (integer)
670
+
671
+   If set to 1 or greater, the module will create its own timer processes
672
+   to scan for expired items in hash tables. If set to zero, it will use
673
+   the core timer for this task. Set it to 1 if you store a lot of items
674
+   with autoexpire property.
675
+
676
+   Default value is 0.
677
+
678
+   Example 1.17. Set timer_procs parameter
679
+...
680
+modparam("htable", "timer_procs", 4)
681
+...
682
+
683
+3.15. event_callback (str)
684
+
685
+   The name of the function in the kemi configuration file (embedded
686
+   scripting language such as Lua, Python, ...) to be executed instead of
687
+   event_route[...] blocks.
688
+
689
+   The function receives a string parameter with the name of the event,
690
+   the values can be: 'htable:mod-init', 'htable:expired:htname' ('htname'
691
+   being the name of hash table).
692
+
693
+   Default value is 'empty' (no function is executed for events).
694
+
695
+   Example 1.18. Set event_callback parameter
696
+...
697
+modparam("htable", "event_callback", "ksr_htable_event")
698
+...
699
+-- event callback function implemented in Lua
700
+function ksr_htable_event(evname)
701
+        KSR.info("===== htable module triggered event: " .. evname .. "\n");
702
+        return 1;
703
+end
704
+...
705
+
706
+3.16. event_callback_mode (int)
707
+
708
+   Control when event_route[htable:init] is executed: 0 - after all
709
+   modules were initialized; 1 - in first worker process.
710
+
711
+   Set it to 1 if used in a KEMI script or when needing to use database
712
+   (e.g., via sqlops) inside event_route[htable:init].
713
+
714
+   Default value is 0.
715
+
716
+   Example 1.19. Set event_callback_mode parameter
717
+...
718
+modparam("htable", "event_callback_mode", 1)
719
+...
720
+
721
+4. Functions
722
+
723
+   4.1. sht_print()
724
+   4.2. sht_rm(htname, itname)
725
+   4.3. sht_rm_name_re(htable=>regexp)
726
+   4.4. sht_rm_value_re(htable=>regexp)
727
+   4.5. sht_rm_name(htable, op, val)
728
+   4.6. sht_rm_value(htable, op, val)
729
+   4.7. sht_reset(htable)
730
+   4.8. sht_lock(htable=>key)
731
+   4.9. sht_unlock(htable=>key)
732
+   4.10. sht_iterator_start(iname, hname)
733
+   4.11. sht_iterator_end(iname)
734
+   4.12. sht_iterator_next(iname)
735
+   4.13. sht_iterator_rm(iname)
736
+   4.14. sht_iterator_sets(iname, sval)
737
+   4.15. sht_iterator_seti(iname, ival)
738
+   4.16. sht_iterator_setex(iname, exval)
739
+   4.17. sht_match_name(htable, op, mval)
740
+   4.18. sht_has_name(htable, op, mval)
741
+   4.19. sht_match_str_value(htable, op, mval)
742
+   4.20. sht_has_str_value(htable, op, mval)
743
+
744
+4.1.  sht_print()
745
+
746
+   Dump content of hash table to L_ERR log level. Intended for debug
747
+   purposes.
748
+
749
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
750
+   ONREPLY_ROUTE, BRANCH_ROUTE.
751
+
752
+   Example 1.20. sht_print usage
753
+...
754
+sht_print();
755
+...
756
+
757
+4.2.  sht_rm(htname, itname)
758
+
759
+   Delete the item with the name 'itname' from hash table 'htname'. This
760
+   API function equivaluent to '$sht(htname=>itname) = $null'.
761
+
762
+   This function can be used from ANY_ROUTE.
763
+
764
+   Example 1.21. sht_rm usage
765
+...
766
+sht_rm("ha", "test"");
767
+...
768
+
769
+4.3.  sht_rm_name_re(htable=>regexp)
770
+
771
+   Delete all entries in the htable that match the name against regular
772
+   expression.
773
+
774
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
775
+   ONREPLY_ROUTE, BRANCH_ROUTE.
776
+
777
+   Example 1.22. sht_rm_name_re usage
778
+...
779
+sht_rm_name_re("ha=>.*");
780
+...
781
+
782
+4.4.  sht_rm_value_re(htable=>regexp)
783
+
784
+   Delete all entries in the htable that match the value against regular
785
+   expression.
786
+
787
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
788
+   ONREPLY_ROUTE, BRANCH_ROUTE.
789
+
790
+   Example 1.23. sht_rm_value_re usage
791
+...
792
+sht_rm_value_re("ha=>.*");
793
+...
794
+
795
+4.5.  sht_rm_name(htable, op, val)
796
+
797
+   Delete all entries in the htable that match the name against the val
798
+   parameter.
799
+
800
+   The op parameter can be:
801
+     * re - match the val parameter as regular expression.
802
+     * sw - match the val parameter as 'starts with'.
803
+
804
+   All parameters can be static strings or contain variables.
805
+
806
+   This function can be used from ANY_ROUTE.
807
+
808
+   Example 1.24. sht_rm_name usage
809
+...
810
+sht_rm_name("ha", "re", ".*");
811
+...
812
+
813
+4.6.  sht_rm_value(htable, op, val)
814
+
815
+   Delete all entries in the htable that match the value against the val
816
+   parameter.
817
+
818
+   The op parameter can be:
819
+     * re - match the val parameter as regular expression.
820
+     * sw - match the val parameter as 'starts with'.
821
+
822
+   All parameters can be static strings or contain variables.
823
+
824
+   This function can be used from ANY_ROUTE.
825
+
826
+   Example 1.25. sht_rm_value usage
827
+...
828
+sht_rm_value("ha", "re", ".*");
829
+...
830
+
831
+4.7.  sht_reset(htable)
832
+
833
+   Delete all entries in the htable. The name of the hash table can be a
834
+   dynamic string with variables.
835
+
836
+   This function can be used from ANY_ROUTE.
837
+
838
+   Example 1.26. sht_reset usage
839
+...
840
+sht_reset("ha$var(x)");
841
+...
842
+
843
+4.8.  sht_lock(htable=>key)
844
+
845
+   Lock the slot in htable corresponding to the key item. Note that the
846
+   locking is re-entrant for the process, therefore the lock and unlock
847
+   should be done by the same process.
848
+
849
+   This function can be used from ANY_ROUTE.
850
+
851
+   Example 1.27. sht_lock usage
852
+...
853
+sht_lock("ha=>test");
854
+...
855
+
856
+4.9.  sht_unlock(htable=>key)
857
+
858
+   Unlock the slot in htable corresponding to the key item. Note that the
859
+   locking is re-entrant for the process, therefore the lock and unlock
860
+   should be done by the same process.
861
+
862
+   This function can be used from ANY_ROUTE.
863
+
864
+   Example 1.28. sht_unlock usage
865
+...
866
+sht_lock("ha=>test");
867
+$sht(ha=>test) = $sht(ha=>test) + 10;
868
+sht_unlock("ha=>test");
869
+...
870
+
871
+4.10.  sht_iterator_start(iname, hname)
872
+
873
+   Start an iterator for hash table named by the value of parameter hname.
874
+   The parameter iname is used to identify the iterator. There can be up
875
+   to 4 iterators at the same time, with different name.
876
+
877
+   Both parameters can be dynamic strings with variables.
878
+
879
+   IMPORTANT: the slot of the hash table is left locked when retrieving in
880
+   item. Therefore be sure you do not update the content of the hash table
881
+   in between sht_iterator_start() and sht_iterator_end(), because it may
882
+   end up in dead lock.
883
+
884
+   This function can be used from ANY_ROUTE.
885
+
886
+   Example 1.29. sht_iterator_start usage
887
+...
888
+sht_iterator_start("i1", "h1");
889
+...
890
+
891
+4.11.  sht_iterator_end(iname)
892
+
893
+   Close the iterator identified by iname parameter and release the hash
894
+   table slot acquired by the iterator. The iname value must be the same
895
+   used for sht_iterator_start().
896
+
897
+   The parameter can be dynamic string with variables.
898
+
899
+   This function can be used from ANY_ROUTE.
900
+
901
+   Example 1.30. sht_iterator_end usage
902
+...
903
+sht_iterator_end("i1");
904
+...
905
+
906
+4.12.  sht_iterator_next(iname)
907
+
908
+   Move the iterator to the next item in hash table. It must be called
909
+   also after sht_iterator_start() to get the first item in the hash
910
+   table. Items are returned as they are found in the hash table slot,
911
+   starting with the first slot.
912
+
913
+   The return code is false when there is no (more) item in the hash
914
+   table.
915
+
916
+   The item name and value are accessible via variables: $shtitkey(iname)
917
+   and $shtitval(iname).
918
+
919
+   The parameter can be dynamic string with variables.
920
+
921
+   This function can be used from ANY_ROUTE.
922
+
923
+   Example 1.31. sht_iterator_next usage
924
+...
925
+    sht_iterator_start("i1", "h1");
926
+    while(sht_iterator_next("i1")) {
927
+        xlog("h1[$shtitkey(i1)] is: $shtitval(i1)\n");
928
+    }
929
+    sht_iterator_end("i1");
930
+...
931
+
932
+4.13.  sht_iterator_rm(iname)
933
+
934
+   Remove the current item in the iterator and move the iterator to the
935
+   next one.
936
+
937
+   The return code is 1 (true) if the item was removed and next item
938
+   exists; -2 (false) if the item was removed and there is no next item
939
+   (end of items); other negative value (false) can be returned on error
940
+   (e.g., iterator or item not found).
941
+
942
+   The parameter can be dynamic string with variables.
943
+
944
+   This function can be used from ANY_ROUTE.
945
+
946
+   Example 1.32. sht_iterator_rm usage
947
+...
948
+    sht_iterator_start("i1", "h1");
949
+    while(sht_iterator_next("i1")) {
950
+        while($shtitkey(i1) =~ "xyz" and sht_iterator_rm("i1")) {
951
+            xdbg("item removed\n");
952
+        }
953
+    }
954
+    sht_iterator_end("i1");
955
+...
956
+
957
+4.14.  sht_iterator_sets(iname, sval)
958
+
959
+   Set the value of the current item to the string in the sval.
960
+
961
+   The parameters can be dynamic strings with variables.
962
+
963
+   This function can be used from ANY_ROUTE.
964
+
965
+   Example 1.33. sht_iterator_sets usage
966
+...
967
+    sht_iterator_start("i1", "h1");
968
+    sht_iterator_next("i1");
969
+    sht_iterator_sets("i1", "$ci");
970
+    sht_iterator_end("i1");
971
+...
972
+
973
+4.15.  sht_iterator_seti(iname, ival)
974
+
975
+   Set the value of the current item to the integer in the ival.
976
+
977
+   The parameters can be dynamic strings or integers with variables.
978
+
979
+   This function can be used from ANY_ROUTE.
980
+
981
+   Example 1.34. sht_iterator_seti usage
982
+...
983
+    sht_iterator_start("i1", "h1");
984
+    sht_iterator_next("i1");
985
+    sht_iterator_seti("i1", "20");
986
+    sht_iterator_end("i1");
987
+...
988
+
989
+4.16.  sht_iterator_setex(iname, exval)
990
+
991
+   Set the expire of the current item to the integer in the exval.
992
+
993
+   The parameters can be dynamic strings or integers with variables.
994
+
995
+   This function can be used from ANY_ROUTE.
996
+
997
+   Example 1.35. sht_iterator_setex usage
998
+...
999
+    sht_iterator_start("i1", "h1");
1000
+    sht_iterator_next("i1");
1001
+    sht_iterator_setex("i1", "120");
1002
+    sht_iterator_end("i1");
1003
+...
1004
+
1005
+4.17.  sht_match_name(htable, op, mval)
1006
+
1007
+   Return greater than 0 (true) if the htable has an item that matches the
1008
+   name against the mval parameter.
1009
+
1010
+   The op parameter can be:
1011
+     * eq - match the val parameter as string equal expression.
1012
+     * ne - match the val parameter as string not-equal expression.
1013
+     * re - match the val parameter as regular expression.
1014
+     * sw - match the val parameter as 'starts with' expression.
1015
+
1016
+   All parameters can be static strings or contain variables.
1017
+
1018
+   This function can be used from ANY_ROUTE.
1019
+
1020
+   Example 1.36. sht_match_name usage
1021
+...
1022
+if(sht_match_name("ha", "eq", "alice")) {
1023
+  ...
1024
+}
1025
+...
1026
+
1027
+4.18.  sht_has_name(htable, op, mval)
1028
+
1029
+   Alias for sht_match_name().
1030
+
1031
+4.19.  sht_match_str_value(htable, op, mval)
1032
+
1033
+   Return greater than 0 (true) if the htable has an item that matches the
1034
+   string value against the mval parameter.
1035
+
1036
+   The op parameter can be:
1037
+     * eq - match the val parameter as string equal expression.
1038
+     * ne - match the val parameter as string not-equal expression.
1039
+     * re - match the val parameter as regular expression.
1040
+     * sw - match the val parameter as 'starts with' expression.
1041
+
1042
+   All parameters can be static strings or contain variables.
1043
+
1044
+   This function can be used from ANY_ROUTE.
1045
+
1046
+   Example 1.37. sht_match_name usage
1047
+...
1048
+if(sht_match_str_value("ha", "eq", "alice")) {
1049
+  ...
1050
+}
1051
+...
1052
+
1053
+4.20.  sht_has_str_value(htable, op, mval)
1054
+
1055
+   Alias for sht_match_str_value().
1056
+
1057
+5. Exported pseudo-variables
1058
+
1059
+     * $sht(htable=>key)
1060
+     * $shtex(htable=>key)
1061
+     * $shtcn(htable=>key)
1062
+     * $shtcv(htable=>key)
1063
+     * $shtinc(htable=>key)
1064
+     * $shtitkey(iname)
1065
+     * $shtitval(iname)
1066
+     * $shtrecord(attribute)
1067
+
1068
+   Exported pseudo-variables are documented at
1069
+   https://www.kamailio.org/wiki/.
1070
+
1071
+6. RPC Commands
1072
+
1073
+   6.1. htable.get htable key
1074
+   6.2. htable.delete htable key
1075
+   6.3. htable.sets htable key value
1076
+   6.4. htable.seti htable key value
1077
+   6.5. htable.setex htable key expire
1078
+   6.6. htable.dump htable
1079
+   6.7. htable.reload htable
1080
+   6.8. htable.store htable
1081
+   6.9. htable.flush htable
1082
+   6.10. htable.listTables
1083
+   6.11. htable.stats
1084
+
1085
+6.1.  htable.get htable key
1086
+
1087
+   Lists one value in a hash table
1088
+
1089
+   Name: htable.get
1090
+
1091
+   Parameters:
1092
+     * htable : Name of the hash table to dump
1093
+     * key : Key name of the hash table value to dump
1094
+
1095
+   Example:
1096
+...
1097
+# Dump $sht(students=>alice)
1098
+kamcmd htable.get students alice
1099
+
1100
+# Dump first entry in array key course $sht(students=>course[0])
1101
+kamcmd htable.get students course[0]
1102
+...
1103
+
1104
+6.2.  htable.delete htable key
1105
+
1106
+   Delete one value in a hash table
1107
+
1108
+   Name: htable.delete
1109
+
1110
+   Parameters:
1111
+     * htable : Name of the hash table to delete
1112
+     * key : Key name of the hash table value to delete
1113
+
1114
+   Example:
1115
+...
1116
+# Delete $sht(students=>alice)
1117
+kamcmd htable.delete students alice
1118
+
1119
+# Delete first entry in array key course $sht(students=>course[0])
1120
+kamcmd htable.delete students course[0]
1121
+...
1122
+
1123
+6.3.  htable.sets htable key value
1124
+
1125
+   Set an item in hash table to string value.
1126
+
1127
+   Name: htable.sets
1128
+
1129
+   Parameters:
1130
+     * htable : Name of the hash table
1131
+     * key : Key name in the hash table
1132
+     * Value : String value for the item
1133
+
1134
+   Example:
1135
+...
1136
+# Set $sht(test=>x) as string
1137
+kamcmd htable.sets test x abc
1138
+
1139
+# Set firsti entry in array key x $sht(test=>x[0]) as string
1140
+kamcmd htable.sets test x[0] abc
1141
+...
1142
+
1143
+6.4.  htable.seti htable key value
1144
+
1145
+   Set an item in hash table to integer value.
1146
+
1147
+   Name: htable.seti
1148
+
1149
+   Parameters:
1150
+     * htable : Name of the hash table
1151
+     * key : Key name in the hash table
1152
+     * Value : Integer value for the item
1153
+
1154
+   Example:
1155
+...
1156
+# Set $sht(test=>x) as integer
1157
+kamcmd htable.seti test x 123
1158
+
1159
+# Set first entry in array key x $sht(test=>x[0]) as integer
1160
+kamcmd htable.seti test x[0] 123
1161
+...
1162
+
1163
+6.5.  htable.setex htable key expire
1164
+
1165
+   Set the expire for an item in hash table.
1166
+
1167
+   Name: htable.setex
1168
+
1169
+   Parameters:
1170
+     * htable : name of the hash table
1171
+     * key : key name in the hash table
1172
+     * expire : integer value for the expire (seconds)
1173
+
1174
+   Example:
1175
+...
1176
+# set  expire for $sht(test=>x) to 120 secs
1177
+kamctl rpc htable.seti test x 120
1178
+...
1179
+
1180
+6.6.  htable.dump htable
1181
+
1182
+   Lists all the values in a hash table
1183
+
1184
+   Name: htable.dump
1185
+
1186
+   Parameters:
1187
+     * htable : Name of the hash table to dump
1188
+
1189
+   Example:
1190
+...
1191
+kamcmd htable.dump ipban
1192
+...
1193
+
1194
+6.7.  htable.reload htable
1195
+
1196
+   Reload hash table from database.
1197
+
1198
+   Name: htable.reload
1199
+
1200
+   Parameters:
1201
+     * htable : Name of the hash table to reload
1202
+
1203
+   Example:
1204
+...
1205
+kamcmd htable.reload ipban
1206
+...
1207
+
1208
+6.8.  htable.store htable
1209
+
1210
+   Store hash table to database.
1211
+
1212
+   Name: htable.store
1213
+
1214
+   Parameters:
1215
+     * htable : Name of the hash table to store
1216
+
1217
+   Example:
1218
+...
1219
+kamcmd htable.store ipban
1220
+...
1221
+
1222
+6.9.  htable.flush htable
1223
+
1224
+   Empty the hash table
1225
+
1226
+   Name: htable.flush
1227
+
1228
+   Parameters:
1229
+     * htable : Name of the hash table to flush
1230
+
1231
+   Example:
1232
+...
1233
+kamcmd htable.flush ipban
1234
+...
1235
+
1236
+6.10.  htable.listTables
1237
+
1238
+   Lists all defined tables
1239
+
1240
+   Name: htable.listTables
1241
+
1242
+   Parameters:
1243
+     * None
1244
+
1245
+   Example:
1246
+...
1247
+kamcmd htable.listTables
1248
+...
1249
+
1250
+6.11.  htable.stats
1251
+
1252
+   Get statistics for hash tables - name, number of slots, number of
1253
+   items, max number of items per slot, min number of items per slot.
1254
+
1255
+   Name: htable.stats
1256
+
1257
+   Parameters:
1258
+     * None
1259
+
1260
+   Example:
1261
+...
1262
+kamcmd htable.stats
1263
+...
1264
+
1265
+7. Event routes
1266
+
1267
+   7.1. htable:mod-init
1268
+   7.2. htable:expired:<table>
1269
+
1270
+7.1.  htable:mod-init
1271
+
1272
+   When defined, the module calls event_route[htable:mod-init] after all
1273
+   modules have been initialized. A typical use case is to initialise
1274
+   items in hash tables. The event route is executed only once, after core
1275
+   and module initialization, but before Kamailio forks any child
1276
+   processes.
1277
+
1278
+   Note: do not expect to use functions from all other modules here, even
1279
+   if they are loaded before the htable module, because many of them
1280
+   initialize their runtime structures inside child init callbacks, which
1281
+   are executed after this moment, when forking child processes. For
1282
+   example, sqlops cannot be used, connections to database are initialized
1283
+   in child init. Even more, it is recommended not to use functions from
1284
+   other modules, because it can mess up what they created in mod init
1285
+   callback and expect in child init callback. It should be ok to use
1286
+   functions from htable module or assignment operations.
1287
+...
1288
+event_route[htable:mod-init] {
1289
+    $sht(a=>x) = 1;
1290
+}
1291
+...
1292
+
1293
+7.2.  htable:expired:<table>
1294
+
1295
+   When defined, the module calls event_route[htable:expired:<table>] when
1296
+   an entry in the given table expires. In this event route, the key and
1297
+   value of the expired record are available with the $shtrecord(key) and
1298
+   $shtrecord(value) pseudo-variables.
1299
+...
1300
+
1301
+event_route[htable:expired:mytable] {
1302
+    xlog("mytable record expired $shtrecord(key) => $shtrecord(value)\n");
1303
+}
1304
+...