Browse code

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

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