diff --git a/src/modules/keepalive/doc/keepalive.xml b/src/modules/keepalive/doc/keepalive.xml
index d7c4cffa24d..ae4d93c0427 100644
--- a/src/modules/keepalive/doc/keepalive.xml
+++ b/src/modules/keepalive/doc/keepalive.xml
@@ -33,6 +33,7 @@
+
diff --git a/src/modules/keepalive/doc/keepalive_admin.xml b/src/modules/keepalive/doc/keepalive_admin.xml
index d65d4f6c123..a3694451782 100644
--- a/src/modules/keepalive/doc/keepalive_admin.xml
+++ b/src/modules/keepalive/doc/keepalive_admin.xml
@@ -24,7 +24,7 @@
As an example of usage by other modules, see
drouting, which was
- enahnced to use this module to monitor its gateways.
+ enhanced to use this module to monitor its gateways.
@@ -62,7 +62,7 @@
<varname>ping_interval</varname> (integer)
- Interval requests are sent to destinations (in seconds)
+ Define the interval (in seconds) ping requests are sent to destinations
@@ -81,7 +81,7 @@ modparam("keepalive", "ping_interval", 10)
<varname>destination</varname> (string)
- Allows to specify statically destinations you want to monitor
+ Allows to statically define destinations you want to monitor
Set <varname>destination</varname> parameter
@@ -102,13 +102,18 @@ modparam("keepalive", "destination", "sip.provider.com")
is_alive(destination)
- Get destination status
+ Get destination status.
- Parameter destination
is destination you want to check status
+ The Parameter destination is destination you want to check status
- Return value: 1 if destination is up, 2 if destination is down, -1 on error.
+ Returned value:
+
+ 1 if destination is up
+ 2 if destination is down
+ -1 on error
+
This function can be used from ANY_ROUTE.
@@ -117,7 +122,9 @@ modparam("keepalive", "destination", "sip.provider.com")
<function>is_alive()</function> usage
...
-is_alive("192.168.10.20");
+if(is_alive("192.168.10.20") == 1) {
+ // do stuff
+};
...
diff --git a/src/modules/keepalive/doc/keepalive_devel.xml b/src/modules/keepalive/doc/keepalive_devel.xml
new file mode 100644
index 00000000000..ff042bbe541
--- /dev/null
+++ b/src/modules/keepalive/doc/keepalive_devel.xml
@@ -0,0 +1,146 @@
+
+
+
+%docentities;
+
+]>
+
+
+
+
+ &develguide;
+
+
+ The KeepAlive module provides an internal API to be used by
+ other &kamailio; modules. This API offers support for destinations
+ monitoring.
+
+
+ For internal (non-script) usage, the KeepAlive module offers to other module the
+ possibility to register callback functions to be executed for each destination's
+ status change.
+
+
+
+
+ Available Functions
+
+
+
+ <function moreinfo="none">add_destination(uri, owner, flags, [callback, [user_attr]])</function>
+
+
+ This function registers a new destination to monitor.
+ Monitoring of the destination starts as soon as it returns with success (0 value).
+
+ Meaning of the parameters is as follows:
+
+
+
+ uri (string) - address of destination to monitor. Valid format is [proto:]ip[:port], with:
+
+
+
+ proto being one of sip or sips (SIP over TLS).
+ If omitted, sip is used by default
+
+
+ port being optional (using default standard port, 5060 for sip and 5061 for sips)
+
+
+
+
+
+ owner (string) - module name owning
the destination
+ (for information purpose)
+
+
+
+
+ flags (integer) - destination flags (unused for now, use 0 value)
+
+
+
+
+ callback (ka_statechanged_f, optional) - callback function, executed on destination's state change.
+
+
+ The callback function is of type void (*ka_statechanged_f)(str *uri, int state, void *user_attr);. Use NULL to set no callback.
+
+
+ destination's state value is one of:
+
+
+
+ 0 - unknown state (this is the destination state at first, waiting first ping replies or timeout)
+
+
+ 1 - destination is UP
+
+
+ 2 - destination is DOWN
+
+
+
+
+
+ user_attr (void * pointer, optional) - If callback function is setup, this parameter will be forwarded to it, as last parameter. Use NULL to set no user_attr parameter.
+
+
+
+
+
+ Returned values:
+
+
+ 0 if ok
+
+ -1 if an error occured
+
+
+
+
+
+
+
+ Examples
+
+ Loading KeepAlive module's API from another module, adding a destination to monitor & registering a callback
+
+...
+#include "../keepalive/api.h"
+...
+keepalive_api_t ka_api;
+...
+...
+/* loading keepalive API */
+if (bind_keepalive( &ka_api ) != 0) {
+ LM_ERR("can't load KeepAlive API\n");
+ goto error;
+}
+...
+...
+/* callback function */
+void my_callback(str uri, int state, void *user_attr) {
+
+ printf("%.*s new state is: %d\n", uri.len, uri.str, state)
+}
+
+/* register a new destination */
+str dest = str_init("sip:192.168.10.21:5060");
+str owner = str_init("mymodule");
+
+if (ka_api.add_destination(dest, owner, 0, my_callback, NULL) != 0) {
+ LM_ERR("can't add destination\n");
+ goto error;
+}
+...
+
+
+
+
+
+