# &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

### `add_destination(uri, owner, flags, ping_interval, [statechanged_clb, response_clb, [user_attr]])`

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)

- ping_interval (integer) - Pinging interval in seconds for this destination

- statechanged_clb (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

- response_clb (ka_response_f, optional) - callback function, executed on destination's response provided.

  The callback function is of type `void (*ka_response_f)(str *uri, struct tmcb_params *ps, void *user_attr);`. Use NULL to set no callback.

  ps is a pack structure with all params passed to callback function. Defined in t_hooks.h

- user_attr (void * pointer, optional) - If any callback function is set up, this parameter will be forwarded to it (or both callbacks in both are defined), as last parameter. Use NULL to set no user_attr parameter.

Returned values:

- 0 if ok
- -1 if an error occurred

### 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 (on state changed) */
    void my_state_changed_clb(str uri, int state, void *user_attr) {
    	printf("%.*s new state is: %d\n", uri.len, uri.str, state)
    }

    /* callback function (on each response received) */
    void my_response_clb(str *uri, struct tmcb_params *ps, void *user_attr) {
    	printf("response [%d] from %.*s\n", ps->code, uri.len, uri.str)
    }

    if (ka_api.add_destination(dest, owner, 0, 60, my_state_changed_clb,
    				my_response_clb, NULL) != 0) {
        LM_ERR("can't add destination\n");
        goto error;
    }
    ...