Chapter 2. Developer Guide
The RR module provides an internal API to be used by other OpenSIPS modules. The API offers support for SIP dialog based functionalities - for more about the dialog support offered by RR module, see Section 1.2, “Dialog support”.
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. 2.1. Available Functions
2.1.1. 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.
2.1.2. 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. 2.1.3. 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 Section 1.4.2, “append_fromtag (integer)” 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”. 2.1.4. 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. 2.1.5. register_rrcb( callback, param)
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. 2.2. Examples
Example 2.1. Loading RR module's API from another module
...
#include \...
struct rr_binds my_rrb; ... ...
/* load the RR API */
if (load_rr_api( &my_rrb )!=0) { LM_ERR(\ goto error; } ... ...
/* register a RR callback */
if (my_rrb.register_rrcb(my_callback,0))!=0) { LM_ERR(\ goto error; } ...