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

src/modules/dlgs/README

@@ -26,26 +26,44 @@ Daniel-Constantin Mierla
         3. Parameters
 
               3.1. active_lifetime (int)
-              3.2. timer_interval (int)
+              3.2. init_lifetime (int)
+              3.3. finish_lifetime (int)
+              3.4. timer_interval (int)
 
         4. Functions
 
               4.1. dlgs_init(src, dst, data)
-              4.2. dlgs_update(src)
+              4.2. dlgs_update()
+              4.3. dlgs_count(field, op, data)
+              4.4. dlgs_tags_add(vtag)
+              4.5. dlgs_tags_rm(vtag)
+              4.6. dlgs_tags_count(vtag)
 
         5. RPC Commands
 
-              5.1. rpc.list
-              5.2. rpc.stats
+              5.1. dlgs.list
+              5.2. dlgs.briefing
+              5.3. dlgs.get
+              5.4. dlgs.getall
+              5.5. dlgs.stats
 
    List of Examples
 
    1.1. Set active_lifetime parameter
-   1.2. Set timer_interval parameter
-   1.3. dlgs_init usage
-   1.4. dlgs_update usage
-   1.5. dlgs.list usage
-   1.6. dlgs.stats usage
+   1.2. Set init_lifetime parameter
+   1.3. Set finish_lifetime parameter
+   1.4. Set timer_interval parameter
+   1.5. dlgs_init usage
+   1.6. dlgs_update usage
+   1.7. dlgs_count usage
+   1.8. dlgs_tags_add usage
+   1.9. dlgs_tags_rm usage
+   1.10. dlgs_tags_count usage
+   1.11. dlgs.list usage
+   1.12. dlgs.briefing usage
+   1.13. dlgs.get usage
+   1.14. dlgs.get usage
+   1.15. dlgs.stats usage
 
 Chapter 1. Admin Guide
 
@@ -60,17 +78,26 @@ Chapter 1. Admin Guide
    3. Parameters
 
         3.1. active_lifetime (int)
-        3.2. timer_interval (int)
+        3.2. init_lifetime (int)
+        3.3. finish_lifetime (int)
+        3.4. timer_interval (int)
 
    4. Functions
 
         4.1. dlgs_init(src, dst, data)
-        4.2. dlgs_update(src)
+        4.2. dlgs_update()
+        4.3. dlgs_count(field, op, data)
+        4.4. dlgs_tags_add(vtag)
+        4.5. dlgs_tags_rm(vtag)
+        4.6. dlgs_tags_count(vtag)
 
    5. RPC Commands
 
-        5.1. rpc.list
-        5.2. rpc.stats
+        5.1. dlgs.list
+        5.2. dlgs.briefing
+        5.3. dlgs.get
+        5.4. dlgs.getall
+        5.5. dlgs.stats
 
 1. Overview
 
@@ -106,11 +133,14 @@ Chapter 1. Admin Guide
 3. Parameters
 
    3.1. active_lifetime (int)
-   3.2. timer_interval (int)
+   3.2. init_lifetime (int)
+   3.3. finish_lifetime (int)
+   3.4. timer_interval (int)
 
 3.1. active_lifetime (int)
 
-   The lifetime in seconds of a dialog in memory.
+   The lifetime in seconds of an active dialog in memory. A dialog is
+   considered active after the ACK of 200OK for INVITE.
 
    Default value is 10800 (3 hours).
 
@@ -119,14 +149,42 @@ Chapter 1. Admin Guide
 modparam("dlgs", "active_lifetime", 3600)
 ...
 
-3.2. timer_interval (int)
+3.2. init_lifetime (int)
+
+   The lifetime in seconds of an initial dialog in memory. A dialog is in
+   initial state from the moment of creation until it gets to active
+   state. If the dialog stays longer in the initial state, then it is
+   destroyed by the next timer cleanup.
+
+   Default value is 180 (3 minutes).
+
+   Example 1.2. Set init_lifetime parameter
+...
+modparam("dlgs", "init_lifetime", 240)
+...
+
+3.3. finish_lifetime (int)
+
+   The lifetime in seconds of a finished dialog in memory. A dialog is
+   finished if the initial INVITE was not answered or the BYE was
+   received. Once this lifetime passes, the dialog record is removed from
+   memory by the next timer cleanup.
+
+   Default value is 10 (seconds).
+
+   Example 1.3. Set finish_lifetime parameter
+...
+modparam("dlgs", "finish_lifetime", 20)
+...
+
+3.4. timer_interval (int)
 
    The value in secods to run the timer callback function for cleaning up
    dialogs past the lifetime limit.
 
    Default value is 30.
 
-   Example 1.2. Set timer_interval parameter
+   Example 1.4. Set timer_interval parameter
 ...
 modparam("dlgs", "timer_interval", 60)
 ...
@@ -134,18 +192,23 @@ modparam("dlgs", "timer_interval", 60)
 4. Functions
 
    4.1. dlgs_init(src, dst, data)
-   4.2. dlgs_update(src)
+   4.2. dlgs_update()
+   4.3. dlgs_count(field, op, data)
+   4.4. dlgs_tags_add(vtag)
+   4.5. dlgs_tags_rm(vtag)
+   4.6. dlgs_tags_count(vtag)
 
 4.1.  dlgs_init(src, dst, data)
 
    Start track the dialog corresponding to the current SIP message. It has
    to be used for INVITE messages.
 
-   This function can be used from ANY_ROUTE.
+   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
+   ONREPLY_ROUTE, ONSEND_ROUTE.
 
-   Example 1.3. dlgs_init usage
+   Example 1.5. dlgs_init usage
 ...
-request_route {
+onsend_route {
     ...
     if(is_method("INVITE")) {
         dlgs_init("$fu", "$tu", "my data");
@@ -154,42 +217,163 @@ request_route {
 }
 ...
 
-4.2.  dlgs_update(src)
+4.2.  dlgs_update()
 
-   Update dialog state.
+   Update dialog state. It has to be used for SIP requests only, the SIP
+   responses are handled automatically.
 
-   This function can be used from ONSEND_ROUTE.
+   This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
+   ONSEND_ROUTE.
 
-   Example 1.4. dlgs_update usage
+   Example 1.6. dlgs_update usage
 ...
-onsend_route {
+request_route {
     ...
-    if(is_method("INVITE|ACK|BYE")) {
-        dlgs_init("$fu", "$tu", "my data");
+    if(is_method("ACK|BYE|CANCEL")) {
+        dlgs_update();
     }
     ...
 }
 ...
 
+4.3.  dlgs_count(field, op, data)
+
+   Return the number of dialogs matching the filter specified by the
+   parameters. It does not count the dialogs that are finished (not
+   answered or terminated with BYE).
+
+   The field parameter can be: 'src', 'dst', 'data' to specify what dialog
+   attribute has to be used for matching. It can be also 'any' to get the
+   count of all ongoing dialogs.
+
+   The op parameter can be: 'eq' - equal; 'ne' - not equal; 're' - regex;
+   'sw' - start with; 'fm' - fnmatch.
+
+   In case of error or no dialog matched, it returns -1 or other negative
+   (false) value.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.7. dlgs_count usage
+...
+request_route {
+    ...
+    $var(count) = dlgs_count("src", "eq", "$fu");
+    if($var(count) > 0) {
+        # caller has ongoing dialogs
+    }
+    ...
+    $var(allcalls) = dlgs_count("any", "eq", "*");
+    if($var(allcalls) > 0) {
+        # there are ongoing dialogs
+    }
+    ...
+}
+...
+
+4.4.  dlgs_tags_add(vtag)
+
+   Add a tag to current dialog.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.8. dlgs_tags_add usage
+...
+request_route {
+    ...
+    dlgs_tags_add("$si");
+    ...
+}
+...
+
+4.5.  dlgs_tags_rm(vtag)
+
+   Remove a tag from current dialog.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.9. dlgs_tags_rm usage
+...
+request_route {
+    ...
+    dlgs_tags_rm("$si");
+    ...
+}
+...
+
+4.6.  dlgs_tags_count(vtag)
+
+   Count all tags for ongoing dialogs matching the parameter.
+
+   It returns -1 if no tag for ongoing dialogs is matched or there was an
+   error.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.10. dlgs_tags_count usage
+...
+request_route {
+    ...
+    $var(tcount) = dlgs_tags_count("$si");
+    ...
+}
+...
+
 5. RPC Commands
 
-   5.1. rpc.list
-   5.2. rpc.stats
+   5.1. dlgs.list
+   5.2. dlgs.briefing
+   5.3. dlgs.get
+   5.4. dlgs.getall
+   5.5. dlgs.stats
 
-5.1.  rpc.list
+5.1.  dlgs.list
 
    List dialog records.
 
-   Example 1.5. dlgs.list usage
+   Example 1.11. dlgs.list usage
 ...
 kamctl rpc dlgs.list
 ...
 
-5.2.  rpc.stats
+5.2.  dlgs.briefing
+
+   List dialog records with fewer attributes per record.
+
+   Example 1.12. dlgs.briefing usage
+...
+kamctl rpc dlgs.briefing
+...
+
+5.3.  dlgs.get
+
+   Prototype: dlgs.get field op data
+
+   List first dialog record matching the filter. The parameters have the
+   same meaning like those for dlgs_count(...).
+
+   Example 1.13. dlgs.get usage
+...
+kamctl rpc dlgs.get src eq sip:[email protected]
+...
+
+5.4.  dlgs.getall
+
+   Prototype: dlgs.getall field op data
+
+   List all dialog records matching the filter. The parameters have the
+   same meaning like those for dlgs_count(...).
+
+   Example 1.14. dlgs.get usage
+...
+kamctl rpc dlgs.get src eq sip:[email protected]
+...
+
+5.5.  dlgs.stats
 
    Return dialog statistics.
 
-   Example 1.6. dlgs.stats usage
+   Example 1.15. dlgs.stats usage
 ...
 kamctl rpc dlgs.stats
 ...