# &develguide;

The RR module provides an internal API to be used by other &kamailio; modules. The API offers support for SIP dialog based functionalities - for more about the dialog support offered by RR module, see .

For internal(non-script) usage, the RR module offers to other module the possibility to register callback functions to be executed each time a local Route header is processed. The callback function will receive as parameter the register parameter and the Route header parameter string.

## Available Functions

### `record_route(string)`

The function adds a new Record-Route header field. The header field will be inserted in the message before any other Record-Route header fields.

If any string is passed as parameter, it will be appended as URI parameter to the Record-Route header. The string must follow the ;name=value scheme and it may contain pseudo-variables.

This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and FAILURE_ROUTE.

#### `record_route` usage

    ...
    record_route();
    ...

### `record_route_advertised_address(string)`

This function will add the string into a new Record-Route header field. Don't use unless you know what you are doing. The header field will be inserted in the message before any other Record-Route header fields.

Meaning of the parameters is as follows:

- string - String to be inserted into the header field.

Calls to add_rr_param() will add parameters to the Record-Route header. Note: A second Record-Route will be inserted if the transport used on the inbound and outbound interfaces changes.

#### `record_route_advertised_address` usage

    ...
    record_route_advertised_address("1.2.3.4:5090");
    ...

### `add_rr_param(msg, param)`

Adds a parameter to the requests' Record-Route URI (param must be in ;name=value format).

The function returns 0 on success. Otherwise, -1 is returned.

Meaning of the parameters is as follows:

- struct sip_msg* msg - request that will has the parameter param added to its Record-Route header.

- str* param - parameter to be added to the Record-Route header - it must be in ;name=value format.

### `check_route_param(msg, re)`

The function checks for the request msg if the URI parameters of the local Route header (corresponding to the local server) matches the given regular expression re. It must be called after the loose_route was done.

The function returns 0 on success. Otherwise, -1 is returned.

Meaning of the parameters is as follows:

- struct sip_msg* msg - request that will has the Route header parameters checked.

- regex_t* param - compiled regular expression to be checked against the Route header parameters.

### `is_direction(msg, dir)`

The function checks the flow direction of the request msg. As for checking it's used the ftag Route header parameter, the append_fromtag (see module parameter must be enables. Also this must be called only after the loose_route is done.

The function returns 0 if the dir is the same with the request's flow direction. Otherwise, -1 is returned.

Meaning of the parameters is as follows:

- struct sip_msg* msg - request that will have the direction checked.

- int dir - direction to be checked against. It may be RR_FLOW_UPSTREAM or RR_FLOW_DOWNSTREAM.

### `get_route_param(msg, name, val)`

The function searches in the msg's Route header parameters the parameter called name and returns its value into val. It must be called only after the loose_route is done.

The function returns 0 if parameter was found (even if it has no value). Otherwise, -1 is returned.

Meaning of the parameters is as follows:

- struct sip_msg* msg - request that will have the Route header parameter searched.

- str *name - contains the Route header parameter to be searched.

- str *val - returns the value of the searched Route header parameter if found. It might be empty string if the parameter had no value.

### `register_rrcb(callback, param)`

The function registers a new callback (along with its parameter). The callback will be called when a loose route will be performed for the local address.

The function returns 0 on success. Otherwise, -1 is returned.

Meaning of the parameters is as follows:

- rr_cb_t callback - callback function to be registered.

- void *param - parameter to be passed to the callback function.

## Examples

### Loading RR module's API from another module

    ...
    #include "../rr/api.h"
    ...
    struct rr_binds my_rrb;
    ...
    ...
    /* load the RR API */
    if (load_rr_api( &my_rrb )!=0) {
        LM_ERR("can't load RR API\n");
        goto error;
    }
    ...
    ...
    /* register a RR callback */
    if (my_rrb.register_rrcb(my_callback,0))!=0) {
        LM_ERR("can't register RR callback\n");
        goto error;
    }
    ...