Call Control Module

The following modules must be loaded before this module:

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

Boolean flag that specifies if callcontrol should be disabled. This is useful when you want to use the same OpenSIPS configuration in two different context, one using callcontrol, the other not. In the case callcontrol is disabled, calls to the call_control() function will return a code indicating that there is no limit associated with the call, allowing the use of the same configuration without changes.

Default value is “0”.

...
modparam("call_control", "disable", 1)
...
        

It is the path to the filesystem socket where the callcontrol application listens for commands from the module.

Default value is “/run/callcontrol/socket”.

...
modparam("call_control", "socket_name", "/run/callcontrol/socket")
...
        

How much time (in milliseconds) to wait for an answer from the callcontrol application.

Default value is “500” (ms).

...
modparam("call_control", "socket_timeout", 500)
...
        

Specification of the AVP which holds the IP address from where the SIP signaling originated. If this AVP is set it will be used to get the signaling IP address, else the source IP address from where the SIP message was received will be used. This AVP is meant to be used in cases where there are more than one proxy in the call setup path and the proxy that actually starts callcontrol doesn't receive the SIP messages directly from the UA and it cannot determine the NAT IP address from where the signaling originated. In such a case attaching a SIP header at the first proxy and then copying that header's value into the signaling_ip_avp on the proxy that starts callcontrol will allow it to get the correct NAT IP address from where the SIP signaling originated.

This is used by the rating engine which finds the rates to apply to a call based on caller's SIP URI, caller's SIP domain or caller's IP address (whichever yields a rate first, in this order).

Default value is “$avp(cc_signaling_ip)”.

...
modparam("call_control", "signaling_ip_avp", "$avp(cc_signaling_ip)")
...
        

Specification of the AVP which holds an optional application defined canonical request URI. When this is set, it will be used as the destination when computing the call price, otherwise the request URI will be used. This is useful when the username of the ruri needs to have a different, canonical form in the rating engine computation than it has in the ruri.

Default value is “$avp(cc_can_uri)”.

...
modparam("call_control", "canonical_uri_avp", "$avp(cc_can_uri)")
...
        

Specification of the AVP which holds an optional application defined diverter SIP URI. When this is set, it will be used by the rating engine as the billing party when finding the rates to apply to a given call, otherwise, the caller's URI taken from the From field will be used. When set, this AVP should contain a value in the form “user@domain” (no sip: prefix should be used).

This is useful when a destination diverts a call, thus becoming the new caller. In this case the billing party is the diverter and this AVP should be set to it, to allow the rating engine to pick the right rates for the call. For example, if A calls B and B diverts all its calls unconditionally to C, then the diverter AVP should the set to B's URI, because B is the billing party in the call not A after the call was diverted.

Default value is “$avp(diverter)”.

...
modparam("call_control", "diverter_avp", "$avp(diverter)")

route {
  ...
  # alice@example.com is paying for this call
  $avp(diverter) = "alice@example.com";
  ...
}
...
        

The flag that is used to specify whether the account making the call is prepaid or postpaid. Setting this to a non-null value will determine the module to pass the flag's value to the external application. This will allow the external application to compare OpenSIPS's and the rating engine's views on whether the account calling is prepaid or not and take appropriate action if they conflict. The flag should be set from the OpenSIPS configuration for a prepaid account and reset for a postpaid one.

Default value is NULL (undefined).

...
modparam("call_control", "prepaid_account_flag", "PP_ACC_FLAG")
...
        

Specification of the AVP which holds an optional application defined call limit. When this is set, it will be passed to the CallControl application and if the limit is reached the call_control function will return an error code of -4.

Default value is “$avp(cc_call_limit)”.

...
modparam("call_control", "call_limit_avp", "$avp(cc_call_limit)")
...
        

Specification of the AVP which holds an optional application defined token. This token will be used to check if two calls with the same CallID actually refer to the same call. If call_control() is called multiple times for the same call (thus same CallID) the token needs to be the same or call_control will return -3 error, indicating that the CallID is duplicated.

Default value is “$avp(cc_call_token)”.

...
modparam("call_control", "call_token_avp", "$avp(cc_call_token)")
...
$avp(cc_call_token) := $RANDOM;
...
        

This parameter is used to describe custom call control initialize messages. It represents a list of key value pairs and has the following format:

The left-hand side of the assignment can be any string.

The right-hand side of the assignment must be a script pseudo variable or a script AVP. For more information about them see CookBooks - Scripting Variables.

If the parameter is not set, the default initialize message is sent.

Default value is “NULL”.

	
...
modparam("call_control", "init", "call-id=$ci to=$tu from=$fu 
			authruri=$du another_field = $avp(10)")
...
        

This parameter is used to describe custom call control start messages. It represents a list of key value pairs and has the following format:

The left-hand side of the assignment can be any string.

The right-hand side of the assignment must be a script pseudo variable or a script AVP. For more information about them see CookBooks - Scripting Variables.

If the parameter is not set, the default start message is sent.

Default value is “NULL”.

	
...
modparam("call_control", "start", "call-id=$ci to=$tu from=$fu 
			authruri=$du another_field = $avp(10)")
...
        

This parameter is used to describe custom call control stop messages. It represents a list of key value pairs and has the following format:

The left-hand side of the assignment can be any string.

The right-hand side of the assignment must be a script pseudo variable or a script AVP. For more information about them see CookBooks - Scripting Variables.

If the parameter is not set, the default stop message is sent.

Default value is “NULL”.

	
...
modparam("call_control", "stop", "call-id=$ci to=$tu from=$fu 
			authruri=$du another_field = $avp(10)")
...
        

Trigger the use of callcontrol for the dialog started by the INVITE for which this function is called (the function should only be called for the first INVITE of a call). Further in-dialog requests will be processed automatically using internal bindings into the dialog state machine, allowing callcontrol to update its internal state as the dialog progresses, without any other intervention from the script.

This function should be called right before the message is sent out using t_relay(), when all the request uri modifications are over and a final destination has been determined.

This function has the following return codes:

This function can be used from REQUEST_ROUTE.

...
if ($avp(805) != NULL) {
    # the diverter AVP is set, use it as billing party
    $avp(billing_party_domain) = $(avp(805){uri.domain});
} else {
    $avp(billing_party_domain) = $fd;
}

if (is_method("INVITE") && !has_totag() &&
    is_domain_local($avp(billing_party_domain))) {
    call_control();
    switch ($retcode) {
    case 2:
        # Call with no limit
    case 1:
        # Call has limit and is under callcontrol management
        break;
    case -1:
        # Not enough credit (prepaid call)
        sl_send_reply(402, "Not enough credit");
        exit;
        break;
    case -2:
        # Locked by another call in progress (prepaid call)
        sl_send_reply(403, "Call locked by another call in progress");
        exit;
        break;
    case -3:
        # Duplicated callid
        sl_send_reply(400, "Duplicated callid");
        exit;
        break;
    case -4:
        # Call limit reached
        sl_send_reply(503, "Too many concurrent calls");
        exit;
        break;
    default:
        # Internal error (message parsing, communication, ...)
        if (PREPAID_ACCOUNT) {
            xlog("Call control: internal server error\n");
            sl_send_reply(500, "Internal server error");
            exit;
        } else {
            xlog("L_WARN", "Cannot set time limit for postpaid call\n");
        }
    }
}
t_relay();
...