# &develguide;

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

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

### `add_rr_param( msg, param)`

Adds a parameter to the requests's 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 call 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 append-fromtag-id module parameter must be enables. Also this must be call 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 search in to the msg's Route header parameters the parameter called name and returns its value into val. It must be call 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 serached.

- 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, prior)`

The function register 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.

- short prior - parameter to set the priority. If the callback depends on another module, this parameter should be greater than that module's priority. Otherwise, it should be 0.

## 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))!=0) {
        LM_ERR("can't register RR callback\n");
        goto error;
    }
    ...