rtpengine Add result code for rtpengine_offer (et al) to README and regenerate README
authorOlle E. Johansson <oej@edvina.net>
Mon, 4 Apr 2016 10:49:56 +0000 (12:49 +0200)
committerOlle E. Johansson <oej@edvina.net>
Mon, 4 Apr 2016 10:50:49 +0000 (12:50 +0200)
modules/rtpengine/README
modules/rtpengine/doc/rtpengine_admin.xml

index 00b26f2..d03d9bf 100644 (file)
@@ -63,13 +63,24 @@ Richard Fuchs
               4.1. rtpengine_sock (string)
               4.2. rtpengine_disable_tout (integer)
               4.3. rtpengine_tout_ms (integer)
               4.1. rtpengine_sock (string)
               4.2. rtpengine_disable_tout (integer)
               4.3. rtpengine_tout_ms (integer)
-              4.4. queried_nodes_limit (integer)
-              4.5. rtpengine_retr (integer)
-              4.6. extra_id_pv (string)
-              4.7. setid_avp (string)
-              4.8. force_send_interface (string)
-              4.9. write_sdp_pv (string)
-              4.10. rtp_inst_pvar (string)
+              4.4. rtpengine_allow_op (integer)
+              4.5. queried_nodes_limit (integer)
+              4.6. rtpengine_retr (integer)
+              4.7. extra_id_pv (string)
+              4.8. setid_avp (string)
+              4.9. force_send_interface (string)
+              4.10. read_sdp_pv (string)
+              4.11. write_sdp_pv (string)
+              4.12. rtp_inst_pvar (string)
+              4.13. hash_table_size (integer)
+              4.14. hash_table_tout (integer)
+              4.15. db_url (string)
+              4.16. table_name (string)
+              4.17. setid_col (string)
+              4.18. url_col (string)
+              4.19. weight_col (string)
+              4.20. disabled_col (string)
+              4.21. setid_default (string)
 
         5. Functions
 
 
         5. Functions
 
@@ -89,6 +100,8 @@ Richard Fuchs
               7.1. nh_enable_rtpp proxy_url/all 0/1
               7.2. nh_show_rtpp proxy_url/all
               7.3. nh_ping_rtpp proxy_url/all
               7.1. nh_enable_rtpp proxy_url/all 0/1
               7.2. nh_show_rtpp proxy_url/all
               7.3. nh_ping_rtpp proxy_url/all
+              7.4. nh_reload_rtpp
+              7.5. nh_show_hash_total
 
    2. Frequently Asked Questions
 
 
    2. Frequently Asked Questions
 
@@ -97,23 +110,37 @@ Richard Fuchs
    1.1. Set rtpengine_sock parameter
    1.2. Set rtpengine_disable_tout parameter
    1.3. Set rtpengine_tout_ms parameter
    1.1. Set rtpengine_sock parameter
    1.2. Set rtpengine_disable_tout parameter
    1.3. Set rtpengine_tout_ms parameter
-   1.4. Set queried_nodes_limit parameter
-   1.5. Set rtpengine_retr parameter
-   1.6. Set extra_id_pv parameter
-   1.7. Set setid_avp parameter
-   1.8. Set force_send_interface parameter
-   1.9. Set write_sdp_pv parameter
-   1.10. Set rtp_inst_pvar parameter
-   1.11. set_rtpengine_set usage
-   1.12. rtpengine_offer usage
-   1.13. rtpengine_answer usage
-   1.14. rtpengine_delete usage
-   1.15. rtpengine_manage usage
-   1.16. start_recording usage
-   1.17. $rtpstat Usage
-   1.18. nh_enable_rtpp usage
-   1.19. nh_show_rtpp usage
-   1.20. nh_ping_rtpp usage
+   1.4. Set rtpengine_allow_op parameter
+   1.5. Set queried_nodes_limit parameter
+   1.6. Set rtpengine_retr parameter
+   1.7. Set extra_id_pv parameter
+   1.8. Set setid_avp parameter
+   1.9. Set force_send_interface parameter
+   1.10. Set read_sdp_pv parameter
+   1.11. Set write_sdp_pv parameter
+   1.12. Set rtp_inst_pvar parameter
+   1.13. Set hash_table_size parameter
+   1.14. Set hash_table_tout parameter
+   1.15. Set db_url parameter
+   1.16. Set table_name parameter
+   1.17. Setup rtpengine table
+   1.18. Set setid_col parameter
+   1.19. Set url_col parameter
+   1.20. Set weight_col parameter
+   1.21. Set disabled_col parameter
+   1.22. Set setid_default parameter
+   1.23. set_rtpengine_set usage
+   1.24. rtpengine_offer usage
+   1.25. rtpengine_answer usage
+   1.26. rtpengine_delete usage
+   1.27. rtpengine_manage usage
+   1.28. start_recording usage
+   1.29. $rtpstat Usage
+   1.30. nh_enable_rtpp usage
+   1.31. nh_show_rtpp usage
+   1.32. nh_ping_rtpp usage
+   1.33. nh_reload_rtpp usage
+   1.34. nh_show_hash_total usage
 
 Chapter 1. Admin Guide
 
 
 Chapter 1. Admin Guide
 
@@ -131,13 +158,24 @@ Chapter 1. Admin Guide
         4.1. rtpengine_sock (string)
         4.2. rtpengine_disable_tout (integer)
         4.3. rtpengine_tout_ms (integer)
         4.1. rtpengine_sock (string)
         4.2. rtpengine_disable_tout (integer)
         4.3. rtpengine_tout_ms (integer)
-        4.4. queried_nodes_limit (integer)
-        4.5. rtpengine_retr (integer)
-        4.6. extra_id_pv (string)
-        4.7. setid_avp (string)
-        4.8. force_send_interface (string)
-        4.9. write_sdp_pv (string)
-        4.10. rtp_inst_pvar (string)
+        4.4. rtpengine_allow_op (integer)
+        4.5. queried_nodes_limit (integer)
+        4.6. rtpengine_retr (integer)
+        4.7. extra_id_pv (string)
+        4.8. setid_avp (string)
+        4.9. force_send_interface (string)
+        4.10. read_sdp_pv (string)
+        4.11. write_sdp_pv (string)
+        4.12. rtp_inst_pvar (string)
+        4.13. hash_table_size (integer)
+        4.14. hash_table_tout (integer)
+        4.15. db_url (string)
+        4.16. table_name (string)
+        4.17. setid_col (string)
+        4.18. url_col (string)
+        4.19. weight_col (string)
+        4.20. disabled_col (string)
+        4.21. setid_default (string)
 
    5. Functions
 
 
    5. Functions
 
@@ -157,6 +195,8 @@ Chapter 1. Admin Guide
         7.1. nh_enable_rtpp proxy_url/all 0/1
         7.2. nh_show_rtpp proxy_url/all
         7.3. nh_ping_rtpp proxy_url/all
         7.1. nh_enable_rtpp proxy_url/all 0/1
         7.2. nh_show_rtpp proxy_url/all
         7.3. nh_ping_rtpp proxy_url/all
+        7.4. nh_reload_rtpp
+        7.5. nh_show_hash_total
 
 1. Overview
 
 
 1. Overview
 
@@ -202,6 +242,31 @@ Chapter 1. Admin Guide
    the set was selected using setid_avp, the avp needs to be set only once
    before rtpengine_offer() or rtpengine_manage() call.
 
    the set was selected using setid_avp, the avp needs to be set only once
    before rtpengine_offer() or rtpengine_manage() call.
 
+   From the current implementation point of view, the sets of rtpproxy
+   nodes are shared memory(shm), so all processes can see a common list of
+   nodes. There is no locking when setting the nodes enabled/disabled (to
+   keep the memory access as fast as possible). Thus, problems related to
+   node state might appear for concurent processes that might set the
+   nodes enabled/disabled(e.g. by fifo command). This robustness problems
+   are overcomed as follows.
+
+   If the current process sees the selected node as disabled, the node is
+   force tested before the current process actually takes the disabled
+   decision. If the test succeeds, the process will set the node as
+   enabled (but other concurrent process might still see it as disabled).
+   .
+
+   If the current process sees the selected node as enabled, it does no
+   additional checks and sends the command which will fail in case the
+   machine is actually broken. The process will set the node as disabled
+   (but other concurrent process might still see it as enabled).
+
+   The 'kamctl fifo' commands (including rtpengin ones) are executed by an
+   exclusive process which operate on the same shared memory node list.
+
+   All the nodes are pinged in the beginning by all the processes, even if
+   the node list is shared memory.
+
 3. Dependencies
 
    3.1. Kamailio Modules
 3. Dependencies
 
    3.1. Kamailio Modules
@@ -224,13 +289,24 @@ Chapter 1. Admin Guide
    4.1. rtpengine_sock (string)
    4.2. rtpengine_disable_tout (integer)
    4.3. rtpengine_tout_ms (integer)
    4.1. rtpengine_sock (string)
    4.2. rtpengine_disable_tout (integer)
    4.3. rtpengine_tout_ms (integer)
-   4.4. queried_nodes_limit (integer)
-   4.5. rtpengine_retr (integer)
-   4.6. extra_id_pv (string)
-   4.7. setid_avp (string)
-   4.8. force_send_interface (string)
-   4.9. write_sdp_pv (string)
-   4.10. rtp_inst_pvar (string)
+   4.4. rtpengine_allow_op (integer)
+   4.5. queried_nodes_limit (integer)
+   4.6. rtpengine_retr (integer)
+   4.7. extra_id_pv (string)
+   4.8. setid_avp (string)
+   4.9. force_send_interface (string)
+   4.10. read_sdp_pv (string)
+   4.11. write_sdp_pv (string)
+   4.12. rtp_inst_pvar (string)
+   4.13. hash_table_size (integer)
+   4.14. hash_table_tout (integer)
+   4.15. db_url (string)
+   4.16. table_name (string)
+   4.17. setid_col (string)
+   4.18. url_col (string)
+   4.19. weight_col (string)
+   4.20. disabled_col (string)
+   4.21. setid_default (string)
 
 4.1. rtpengine_sock (string)
 
 
 4.1. rtpengine_sock (string)
 
@@ -278,7 +354,30 @@ modparam("rtpengine", "rtpengine_disable_tout", 20)
 modparam("rtpengine", "rtpengine_tout_ms", 2000)
 ...
 
 modparam("rtpengine", "rtpengine_tout_ms", 2000)
 ...
 
-4.4. queried_nodes_limit (integer)
+4.4. rtpengine_allow_op (integer)
+
+   Enable this to allow finishing the current sessions while denying new
+   sessions for the manually deactivated nodes via kamctl command i.e.
+   "disabled(permanent)" nodes. Probably the manually deactivated machine
+   is still running(did not crash).
+
+   This is useful when deactivating a node for maintanance and reject new
+   sessions but allow current ones to finish.
+
+   The behaviour is the same for a rtpengine deleted table node. When the
+   node is deleted from the table and the table reloaded (see
+   nh_reload_rtpp) the node actually is disabled(permanent) and hidden for
+   display. Next time the same node will be added in the table, and the
+   content reloaded, it will be updated and re-displayed.
+
+   Default value is "0" to keep the current behaviour.
+
+   Example 1.4. Set rtpengine_allow_op parameter
+...
+modparam("rtpengine", "rtpengine_allow_op", 1)
+...
+
+4.5. queried_nodes_limit (integer)
 
    The total number of nodes inside a set (sets are configurable via
    rtpengine_sock function) to be queried before giving up establishing a
 
    The total number of nodes inside a set (sets are configurable via
    rtpengine_sock function) to be queried before giving up establishing a
@@ -288,24 +387,24 @@ modparam("rtpengine", "rtpengine_tout_ms", 2000)
    By default all nodes in a set are tried before giving up communicating
    with the rtpengines.
 
    By default all nodes in a set are tried before giving up communicating
    with the rtpengines.
 
-   Example 1.4. Set queried_nodes_limit parameter
+   Example 1.5. Set queried_nodes_limit parameter
 ...
 modparam("rtpengine", "queried_nodes_limit", 5)
 ...
 
 ...
 modparam("rtpengine", "queried_nodes_limit", 5)
 ...
 
-4.5. rtpengine_retr (integer)
+4.6. rtpengine_retr (integer)
 
    How many times the module should retry to send and receive after
    timeout was generated.
 
    Default value is "5".
 
 
    How many times the module should retry to send and receive after
    timeout was generated.
 
    Default value is "5".
 
-   Example 1.5. Set rtpengine_retr parameter
+   Example 1.6. Set rtpengine_retr parameter
 ...
 modparam("rtpengine", "rtpengine_retr", 2)
 ...
 
 ...
 modparam("rtpengine", "rtpengine_retr", 2)
 ...
 
-4.6. extra_id_pv (string)
+4.7. extra_id_pv (string)
 
    The parameter sets the PV defination to use when the "b" parameter is
    used on rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
 
    The parameter sets the PV defination to use when the "b" parameter is
    used on rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
@@ -313,12 +412,12 @@ modparam("rtpengine", "rtpengine_retr", 2)
 
    Default is empty, the "b" parameter may not be used then.
 
 
    Default is empty, the "b" parameter may not be used then.
 
-   Example 1.6. Set extra_id_pv parameter
+   Example 1.7. Set extra_id_pv parameter
 ...
 modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
 ...
 
 ...
 modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
 ...
 
-4.7. setid_avp (string)
+4.8. setid_avp (string)
 
    The parameter defines an AVP that, if set, determines which RTP proxy
    set rtpengine_offer(), rtpengine_answer(), rtpengine_delete(), and
 
    The parameter defines an AVP that, if set, determines which RTP proxy
    set rtpengine_offer(), rtpengine_answer(), rtpengine_delete(), and
@@ -326,12 +425,12 @@ modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
 
    There is no default value.
 
 
    There is no default value.
 
-   Example 1.7. Set setid_avp parameter
+   Example 1.8. Set setid_avp parameter
 ...
 modparam("rtpengine", "setid_avp", "$avp(setid)")
 ...
 
 ...
 modparam("rtpengine", "setid_avp", "$avp(setid)")
 ...
 
-4.8. force_send_interface (string)
+4.9. force_send_interface (string)
 
    Forces all control messages between the SIP proxy and the RTP proxy to
    be sent from the specified local interface. Both IPv4 and IPv6
 
    Forces all control messages between the SIP proxy and the RTP proxy to
    be sent from the specified local interface. Both IPv4 and IPv6
@@ -345,14 +444,32 @@ modparam("rtpengine", "setid_avp", "$avp(setid)")
 
    There is no default value.
 
 
    There is no default value.
 
-   Example 1.8. Set force_send_interface parameter
+   Example 1.9. Set force_send_interface parameter
 ...
 modparam("rtpengine", "force_send_interface", "10.3.7.123")
 modparam("rtpengine", "force_send_interface", "2001:8d8:1ff:10c0:9a90:96ff:fea8:
 fd99")
 ...
 
 ...
 modparam("rtpengine", "force_send_interface", "10.3.7.123")
 modparam("rtpengine", "force_send_interface", "2001:8d8:1ff:10c0:9a90:96ff:fea8:
 fd99")
 ...
 
-4.9. write_sdp_pv (string)
+4.10. read_sdp_pv (string)
+
+   If this parameter is set to a valid AVP or script var specifier,
+   rtpengine will take the input SDP from this pv instead of the message
+   body.
+
+   There is no default value.
+
+   Example 1.10. Set read_sdp_pv parameter
+...
+modparam("rtpengine", "read_sdp_pv", "$var(sdp)")
+...
+route {
+        ...
+        $var(sdp) = $rb + "a=foo:bar\r\n";
+        rtpengine_manage();
+}
+
+4.11. write_sdp_pv (string)
 
    If this parameter is set to a valid AVP or script var specifier, the
    SDP returned by rtpengine in the offer/answer operations is returned in
 
    If this parameter is set to a valid AVP or script var specifier, the
    SDP returned by rtpengine in the offer/answer operations is returned in
@@ -360,14 +477,17 @@ fd99")
 
    There is no default value.
 
 
    There is no default value.
 
-   Example 1.9. Set write_sdp_pv parameter
+   Example 1.11. Set write_sdp_pv parameter
 ...
 modparam("rtpengine", "write_sdp_pv", "$avp(sdp)")
 ...
 modparam("rtpengine", "write_sdp_pv", "$avp(sdp)")
-  ...  or
-modparam("rtpengine", "write_sdp_pv", "$pv(sdp)")
 ...
 ...
+route {
+        ...
+        rtpengine_manage();
+        set_body("$avp(sdp)a=baz123\r\n", "application/sdp");
+}
 
 
-4.10. rtp_inst_pvar (string)
+4.12. rtp_inst_pvar (string)
 
    A pseudo variable to store the chosen RTP Engine IP address. If this
    parameter is set, the IP address and port of the instance chosen will
 
    A pseudo variable to store the chosen RTP Engine IP address. If this
    parameter is set, the IP address and port of the instance chosen will
@@ -375,9 +495,165 @@ modparam("rtpengine", "write_sdp_pv", "$pv(sdp)")
 
    By default, this parameter is not set.
 
 
    By default, this parameter is not set.
 
-   Example 1.10. Set rtp_inst_pvar parameter
+   Example 1.12. Set rtp_inst_pvar parameter
+...
+modparam("rtpengine", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
+...
+
+4.13. hash_table_size (integer)
+
+   Size of the hash table. Default value is 256.
+
+   NOTE: If configured size is less than 1, the size will be defaulted to
+   1.
+
+   Example 1.13. Set hash_table_size parameter
 ...
 ...
-modparam("rtpproxy", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
+modparam("rtpengine", "hash_table_size", "123")
+...
+
+4.14. hash_table_tout (integer)
+
+   Number of seconds after an rtpengine hash table entry is marked for
+   deletion. By default, this parameter is set to 3600 (seconds).
+
+   To maintain information about a selected rtp machine node, for a given
+   call, entries are added in a hashtable of (callid, node) pairs. When
+   command comes, lookup callid. If found, return chosen node. If not
+   found, choose a new node, insert it in the hastable and return the
+   chosen node.
+
+   NOTE: In the current implementation, the actual deletion happens on the
+   fly, while insert/remove/lookup the hastable, only for the entries in
+   the insert/remove/lookup path.
+
+   NOTE: When configuring this parameter, one should consider maximum call
+   time VS share memory for unfinished calls.
+
+   Example 1.14. Set hash_table_tout parameter
+...
+modparam("rtpengine", "hash_table_tout", "300")
+...
+
+4.15. db_url (string)
+
+   The rtpengine datablase url. If present and valid, it activates
+   database mode. Node information is read from database, not from config.
+
+   By default, the datablase url is NULL (not set).
+
+   Example 1.15. Set db_url parameter
+...
+modparam("rtpengine", "db_url", "mysql://pass@localhost/db")
+...
+
+4.16. table_name (string)
+
+   The rtpengine table name. If database mode is activated (i.e. valid
+   db_url), set the name of rtpengine table, on startup.
+
+   By default, the rtpengine table name is "rtpengine".
+
+   NOTE: One needs to add the version of the rtpengine table in the
+   version table. The current version is version 1.
+
+   Example 1.16. Set table_name parameter
+...
+modparam("rtpengine", "table_name", "rtpengine_table_name")
+...
+
+   Example 1.17. Setup rtpengine table
+mysql> describe rtpengine;
++----------+------------------+------+-----+---------------------+-------+
+| Field    | Type             | Null | Key | Default             | Extra |
++----------+------------------+------+-----+---------------------+-------+
+| setid    | int(10) unsigned | NO   | PRI | 0                   |       |
+| url      | varchar(64)      | NO   | PRI | NULL                |       |
+| weight   | int(10) unsigned | NO   |     | 1                   |       |
+| disabled | int(1)           | NO   |     | 0                   |       |
+| stamp    | datetime         | NO   |     | 1900-01-01 00:00:01 |       |
++----------+------------------+------+-----+---------------------+-------+
+
+mysql> select * from rtpengine;
++-------+---------------------------+--------+----------+---------------------+
+| setid | url                       | weight | disabled | stamp               |
++-------+---------------------------+--------+----------+---------------------+
+|     0 | udp:rtpproxy1.domain:8800 |      1 |        0 | 2016-03-10 10:30:54 |
+|     0 | udp:rtpproxy2.domain:8800 |      1 |        1 | 2016-03-10 10:30:54 |
++-------+---------------------------+--------+----------+---------------------+
+
+mysql> select * from version;
++---------------------------+---------------+
+| table_name                | table_version |
++---------------------------+---------------+
+| rtpengine                 |             1 |
++---------------------------+---------------+
+
+4.17. setid_col (string)
+
+   Column name in the rtpengine table. If database mode is activated (i.e.
+   valid db_url), set the setid of rtp nodes according to this column, on
+   startup. The MySQL value for this column should be INT UNSIGNED.
+
+   By default, the column name is "setid".
+
+   Example 1.18. Set setid_col parameter
+...
+modparam("rtpengine", "setid_col", "setid_column_name")
+...
+
+4.18. url_col (string)
+
+   Column name in the rtpengine table. If database mode is activated (i.e.
+   valid db_url), set the url of rtp nodes according to this column, on
+   startup. The MySQL value for this column should be VARCHAR.
+
+   By default, the column name is "url".
+
+   Example 1.19. Set url_col parameter
+...
+modparam("rtpengine", "url_col", "url_column_name")
+...
+
+4.19. weight_col (string)
+
+   Column name in the rtpengine table. If database mode is activated (i.e.
+   valid db_url), set the weight of rtp nodes according to this column, on
+   startup. The column value has priority over the URL weight. The MySQL
+   value for this column should be INT UNSIGNED.
+
+   By default, the column name is "weight".
+
+   Example 1.20. Set weight_col parameter
+...
+modparam("rtpengine", "weight_col", "weight_column_name")
+...
+
+4.20. disabled_col (string)
+
+   Column name in the rtpengine table. If database mode is activated (i.e.
+   valid db_url), set the state of rtp nodes according to this column, on
+   startup. The MySQL value for this column should be INT.
+
+   By default, the column name is "disabled".
+
+   Example 1.21. Set disabled_col parameter
+...
+modparam("rtpengine", "disabled_col", "disabled_column_name")
+...
+
+4.21. setid_default (string)
+
+   The default set of nodes to be used.
+
+   By default, the setid is 0.
+
+   NOTE that if setid_avp is configured, this value will be ignored and
+   the active set will be chosen according to the setid_avp.
+
+   Example 1.22. Set setid_default parameter
+...
+modparam("rtpengine", "setid_default", 11)
 ...
 
 5. Functions
 ...
 
 5. Functions
@@ -411,7 +687,7 @@ modparam("rtpproxy", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    BRANCH_ROUTE.
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    BRANCH_ROUTE.
 
-   Example 1.11. set_rtpengine_set usage
+   Example 1.23. set_rtpengine_set usage
 ...
 set_rtpengine_set("2");
 rtpengine_offer();
 ...
 set_rtpengine_set("2");
 rtpengine_offer();
@@ -423,6 +699,10 @@ rtpengine_offer();
    To be invoked on INVITE for the cases the SDP bodies are in INVITE and
    200 OK and on 200 OK when SDP bodies are in 200 OK and ACK.
 
    To be invoked on INVITE for the cases the SDP bodies are in INVITE and
    200 OK and on 200 OK when SDP bodies are in 200 OK and ACK.
 
+   The function will return true on success and false (-1) on various
+   failures, like using rtp_engine_offer() on a SIP MESSAGE request or
+   communication with rtpengine fails.
+
    Meaning of the parameters is as follows:
      * flags - flags to turn on some features.
        The "flags" string is a list of space-separated items. Each item is
    Meaning of the parameters is as follows:
      * flags - flags to turn on some features.
        The "flags" string is a list of space-separated items. Each item is
@@ -612,7 +892,7 @@ rtpengine_offer();
 
    This function can be used from ANY_ROUTE.
 
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.12. rtpengine_offer usage
+   Example 1.24. rtpengine_offer usage
 route {
 ...
     if (is_method("INVITE")) {
 route {
 ...
     if (is_method("INVITE")) {
@@ -656,7 +936,7 @@ onreply_route[2]
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
-   Example 1.13. rtpengine_answer usage
+   Example 1.25. rtpengine_answer usage
 
    See rtpengine_offer() function example above for example.
 
 
    See rtpengine_offer() function example above for example.
 
@@ -669,7 +949,7 @@ onreply_route[2]
 
    This function can be used from ANY_ROUTE.
 
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.14. rtpengine_delete usage
+   Example 1.26. rtpengine_delete usage
 ...
 rtpengine_delete();
 ...
 ...
 rtpengine_delete();
 ...
@@ -699,7 +979,7 @@ rtpengine_delete();
 
    This function can be used from ANY_ROUTE.
 
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.15. rtpengine_manage usage
+   Example 1.27. rtpengine_manage usage
 ...
 rtpengine_manage();
 ...
 ...
 rtpengine_manage();
 ...
@@ -712,7 +992,7 @@ rtpengine_manage();
 
    This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
 
 
    This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
 
-   Example 1.16. start_recording usage
+   Example 1.28. start_recording usage
 ...
 start_recording();
 ...
 ...
 start_recording();
 ...
@@ -728,7 +1008,7 @@ start_recording();
    packet counters. The statistics must be retrieved before the session is
    deleted (before rtpengine_delete()).
 
    packet counters. The statistics must be retrieved before the session is
    deleted (before rtpengine_delete()).
 
-   Example 1.17. $rtpstat Usage
+   Example 1.29. $rtpstat Usage
 ...
     append_hf("X-RTP-Statistics: $rtpstat\r\n");
 ...
 ...
     append_hf("X-RTP-Statistics: $rtpstat\r\n");
 ...
@@ -738,6 +1018,8 @@ start_recording();
    7.1. nh_enable_rtpp proxy_url/all 0/1
    7.2. nh_show_rtpp proxy_url/all
    7.3. nh_ping_rtpp proxy_url/all
    7.1. nh_enable_rtpp proxy_url/all 0/1
    7.2. nh_show_rtpp proxy_url/all
    7.3. nh_ping_rtpp proxy_url/all
+   7.4. nh_reload_rtpp
+   7.5. nh_show_hash_total
 
 7.1. nh_enable_rtpp proxy_url/all 0/1
 
 
 7.1. nh_enable_rtpp proxy_url/all 0/1
 
@@ -765,7 +1047,7 @@ start_recording();
    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
    escape the :: from the IPv6 address. See the example below.
 
    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
    escape the :: from the IPv6 address. See the example below.
 
-   Example 1.18. nh_enable_rtpp usage
+   Example 1.30. nh_enable_rtpp usage
 ...
 $ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0
 $ kamctl fifo nh_enable_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999 1
 ...
 $ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0
 $ kamctl fifo nh_enable_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999 1
@@ -788,7 +1070,7 @@ $ kamctl fifo nh_enable_rtpp all 1
    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
    escape the :: from the IPv6 address. See the example below.
 
    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
    escape the :: from the IPv6 address. See the example below.
 
-   Example 1.19. nh_show_rtpp usage
+   Example 1.31. nh_show_rtpp usage
 ...
 $ kamctl fifo nh_show_rtpp udp:192.168.2.133:8081
 $ kamctl fifo nh_show_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
 ...
 $ kamctl fifo nh_show_rtpp udp:192.168.2.133:8081
 $ kamctl fifo nh_show_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
@@ -808,13 +1090,38 @@ $ kamctl fifo nh_show_rtpp all
    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
    escape the :: from the IPv6 address. See the example below.
 
    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
    escape the :: from the IPv6 address. See the example below.
 
-   Example 1.20. nh_ping_rtpp usage
+   Example 1.32. nh_ping_rtpp usage
 ...
 $ kamctl fifo nh_ping_rtpp udp:192.168.2.133:8081
 $ kamctl fifo nh_ping_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
 $ kamctl fifo nh_ping_rtpp all
 ...
 
 ...
 $ kamctl fifo nh_ping_rtpp udp:192.168.2.133:8081
 $ kamctl fifo nh_ping_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
 $ kamctl fifo nh_ping_rtpp all
 ...
 
+7.4. nh_reload_rtpp
+
+   Reloads the database node table content if configured. Returns specific
+   message related to success, failure and no db_url configured.
+
+   NOTE: The current behaviour updates the nodes state or creates new ones
+   or hides old ones, based on the database content. If allow_op modparam
+   is enabled, the sessions are still allowed to finish for the hidden old
+   nodes.
+
+   Example 1.33. nh_reload_rtpp usage
+...
+$ kamctl fifo nh_reload_rtpp
+...
+
+7.5. nh_show_hash_total
+
+   Print the total number of hash entries in the hash table at a given
+   moment.
+
+   Example 1.34. nh_show_hash_total usage
+...
+$ kamctl fifo nh_show_hash_total
+...
+
 Chapter 2. Frequently Asked Questions
 
    2.1. How do I migrate from "rtpproxy" or "rtpproxy-ng" to "rtpengine"?
 Chapter 2. Frequently Asked Questions
 
    2.1. How do I migrate from "rtpproxy" or "rtpproxy-ng" to "rtpengine"?
index 6e334cd..9f6e8c8 100644 (file)
@@ -702,6 +702,11 @@ rtpengine_offer();
                on INVITE for the cases the &sdp; bodies are in INVITE and 200 OK and on 200 OK
                when &sdp; bodies are in 200 OK and ACK.
                 </para>
                on INVITE for the cases the &sdp; bodies are in INVITE and 200 OK and on 200 OK
                when &sdp; bodies are in 200 OK and ACK.
                 </para>
+                <para>
+               The function will return true on success and false (-1) on various failures,
+               like using rtp_engine_offer() on a SIP MESSAGE request or communication with
+               rtpengine fails.
+                </para>
                <para>Meaning of the parameters is as follows:</para>
                <itemizedlist>
                <listitem>
                <para>Meaning of the parameters is as follows:</para>
                <itemizedlist>
                <listitem>