Login | Register

Documentation

Documentation -> Development Manual 3.1 -> RR Module API

This page has been visited 888 times.


Pages for other versions: devel 3.3 3.2 3.1 Older versions:


RR Module API

The RR ( Record Route ) module API is exported by the modules/rr/api.h file.
From a general functionality point of view, the RR module is the one responsible for controlling the Record-Route part for requests, and then routing the sequential requests based on the Route headers. The RR module is the simplest module that provides very simple dialog-aware functionality, by allowing the storage of information ( parameters ) in the Record-Route headers, which can be later retrieved from the Route headers.
First, you will have to bind to the RR module's API and get the structure which you will further use. The binding function is :

/*
Parameters : rrb is the API output to be further used

Returns : 0 in case of success and -1 in case of failure
*/

inline static int load_rr_api( struct rr_binds *rrb );

The rr_binds structure is exemplified below :

struct rr_binds {
        add_rr_param_t      add_rr_param;
        check_route_param_t check_route_param;
        is_direction_t      is_direction;
        get_route_param_t   get_route_param;
        register_rrcb_t     register_rrcb;
        get_remote_target_t get_remote_target;
        get_route_set_t     get_route_set;
        /* whether or not the append_fromtag parameter is enabled in the RR module */
        int                 append_fromtag;
        /* the number of routes removed within the loose routing process */
        int*                removed_routes;
        /* the type of routing done, when comparing the previous and the next hop
        Both can be either strict or loose routers, thus here we have 4 different options :
        ROUTING_LL - loose to loose routing
        ROUTING_SL - strict to loose routing
        ROUTING_SS - strict to strict routing
        ROUTING_LS - loose to strict routing
        */

        int*                routing_type;

        loose_route_t       loose_route;
        record_route_t      record_route;
};


Find below the API function signatures along with their usage :

/* Adds a parameter to the requests's Record-Route URI. The API supports the use case
   where the Record-Routed header will be further added.
   The function is to be used for marking certain dialogs that can
   be identified from the sequential requests - since the Route
   headers in the sequential requests will also contain our added
   params, which we'll be able to fetch with get_route_param ( see below )

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

   Parameters :
     * 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.
*/

typedef  int (*add_rr_param_t)(struct sip_msg* msg, str* param);


/*    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.

   * struct sip_msg* msg - request that will has the Route
       header parameters checked.
   * regex_t* re - compiled regular expression to be checked
       against the Route header parameters.
*/

int (*check_route_param_t)(struct sip_msg* msg, regex_t* rem);


/*    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.1, “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 direction - direction to be checked against. It may be
       RR_FLOW_UPSTREAM ( from callee to caller ) or
       RR_FLOW_DOWNSTREAM ( from caller to callee ).
*/

typedef  int (*is_direction_t)(struct sip_msg* msg, int direction);


/*
   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.
*/

typedef  int (*get_route_param_t)(struct sip_msg*, str*, str*);


/*
   The function register a new callback (along with its
   parameter). The callback will be called when a loose route will
   succesfully 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 func - callback function to be registered.
     * void *param - parameter to be passed to the callback
       function.
     * short prior - parameter to set the priority. The callbacks
        will be executed in order from small to big priority - thus
        to be used for ordering callbacks that depend on each other.

*/

typedef int (*register_rrcb_t)( rr_cb_t func, void *param, short prior);


/* Function to be registered as callback within the RR API :
     * struct sip_msg* req - request that is currently being processed
     * str *rr_param - the parameters in our server's Route header
     * str *param - the custom parameter provided at the callback registration
*/

typedef void (rr_cb_t) (struct sip_msg* req, str *rr_param, void *param);


/*
   Function used to fetch the far-end remote target for the current message.
   Depending on the type routing done ( see the '''routing_type''' API member )
   the remote target can be either in the initial Request URI, in the current
   Request-URI or in the last route header. The API function take care to
   correctly identify which scenario is correct.
   The API function MUST be called after loose_route() was called.

   The function returns the str pointer with the remote target, or NULL in case of error.

   Meaning of the parameters is as follows:
        -* struct sip_msg* msg - request that the remote target will be extracted from
*/

typedef  str* (*get_remote_target_t)(struct sip_msg* msg);


/*
    Function used to fetch the route set from the current SIP message.
    The function takes into account the actual loose_route() done, and properly discards
    the proxy's own Route headers from the SIP message. Thus, the function must be called
    after loose_route() was done.

    The function will return an array of str structures, or NULL in case of error. The
    nr_routes parameter will indicate the size of the returned array

    Meaning of the parameters is as follows:
        -* struct sip_msg* msg - request that the remote target will be extracted from
        -* int* nr_routes - the size of the returned array
*/

typedef  str* (*get_route_set_t)(struct sip_msg*,int *nr_routes);


/*
    Function to be used when for routing a request according to the Route headers present
    in it and to the type of Routing ( loose vs strict ) that needs to be used.

    The function will return 0 in case of success ( request is succesfully routed ). Otherwise,
    -1 is returned.

   Meaning of the parameters is as follows:
        -* struct sip_msg* msg - request to be routed

*/

typedef  int (*loose_route_t)(struct sip_msg* msg);


/*
    Function to be used when record-routing an initial request. The function will add
    one or two Record-Route headers , depending if there are any interface changes and
    if r2 is enabled. Also, if any parameters are provided, they will be added to all the
    Record-Route headers that the function internally adds.

    Returns 0 in case of success. Otherwise, -1 will be returned.

    Meaning of the parameters is as follows:
        -* struct sip_msg* msg - request to be record routed
        -* str* params - parameters to be added to the Record-Route headers
*/

typedef  int (*record_route_t)(struct sip_msg* msg, str* params);
 


See below an example of binding to the RR API from another module, registering a callback and then checking the direction of the sequential request and also checking for the existence of a certain parameter.

...
#include "../rr/api.h"
...
struct rr_binds my_rrb;
...
...
int mod_init(void) {
        ...
        ...
        /* load the RR API */
        if (load_rr_api( &my_rrb )!=0) {
            LM_ERR("can't load RR API\n");
            goto error;
        }

        if (!my_rrb.append_fromtag) {
            LM_ERR("The append_fromtag parameter is not set, but we need it for detecting the direction of requests \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;
        }
        ...
        ...
}

void my_callback(struct sip_msg* msg,str* rr_param,void *param)
{
        str name = str_init("ftag");
        str val;

        LM_INFO("Received a new sequential request from %s\n",
        my_rrb.is_direction( msg, RR_FLOW_UPSTREAM)?"callee":"caller");

        if (my_rrb.get_route_param(msg,&name,&val) == 0) {
                LM_INFO("We have the ftag parameter with value [%.*s]\n",val.len,val.s);
        }
}

Page last modified on December 11, 2019, at 07:21 PM