kamailio 虚变量

伪变量是以$开头的一些变量，这些变量可以作为参数提供给不同的脚本函数，并且在执行函数之前，它们将被替换为一个值.

伪变量的开头用字符$标记。如果你想让字符$加倍$$。

有一组预定义的伪变量，其名称由一个或多个字符组成，以及作为动态字段（AVP和Headers）引用的特殊伪变量。

伪变量是由各种模块实现的，其中大多数是由pv提供的（如果没有对某个模块的特殊引用，则期望伪变量由pv模块提供）。

伪变量用法

伪变量可以与许多模块一起使用，其中包括：

• acc
• avpops
• htable
• http_async_client
• textops
• uac
• xlog

伪变量列表

预定义的伪变量按字母顺序列出。

$$-伪变量标记
$$-表示字符$

$_s（format）-评估动态格式
$_s（format）-以格式计算所有伪变量后返回字符串

    $var(x) = "sip:" + $rU + "@" + $fd;

    # is equivalent of:

    $var(x) = $_s(sip:$rU@$fd);

$ai - P-Asserted-Identity标头中的URI

$ai - 对请求的P-Asserted-Identity报头中URI的引用（参见RFC 3325）

$adu - Auth Digest URI

$adu - URI from Authorization or Proxy-Authorization header. This URI is used when calculating the HTTP Digest Response.

$aa - Auth algorithm

$aa - algorithm from Authorization or Proxy-Authorization header.

$ar - Auth realm

$ar - realm from Authorization or Proxy-Authorization header

$au - Auth username user

$au - user part of username from Authorization or Proxy-Authorization header

$ad - Auth username domain

$ad - domain part of username from Authorization or Proxy-Authorization header

$aU - Auth whole username

$aU - whole username from Authorization or Proxy-Authorization header

$Au - Acc username and realm/domain

$Au - username for accounting purposes. It's a selective pseudo variable (inherited from acc module). It returns the auth username and realm ($au@$ar) if it exists or From URI ($fu) otherwise.

$AU - Acc username

$AU - username for accounting purposes. It's a selective pseudo variable (inherited from acc module). It returns the auth username ($au) if it exists or From user ($fU) otherwise.

$branch(name) - Branch attributes

$branch(name) - reference to attribute 'name' of a branch

This pseudo variable gives you access to the "additional branches" only, not to the "main branch". E.g. if there are 3 clients registered for the same AoR, after lookup() you will have one contact in the "main branch" and two "additional branches". Using $branch() you can access the additional branches, the main branch can be accessed using $ru and $du. (Note: In branch_routes there is no distinction between the main and the additional branches - the branch_route will be called once for each one of them.)

The 'name' can be:

• uri - return uri of the branch
• dst_uri - return destination uri (next hop address)
• path - return the path vector for the branch
• q - return the q value of the branch as integer 0..100 (representing q * 100)
• send_socket - return the socket to be used to send the branch
• count - return the number of the branches
• flags - return the branch flags value
• ruid - return the ruid of the branch (Record internal Unique ID from usrloc)

The PV can take an index to access a specific branch: $(branch(name)[index])

Example:

$var(i)=0;
while($var(i)<$branch(count))
{
   xlog("$(branch(uri)[$var(i)])\n");
   $var(i) = $var(i) + 1;
}

Starting with 3.1.0, you can assign value per attribute. Index can be used to update a specific branch:

$(branch(attr)[index]) = value;

If index is missing, first branch is used. If index is -1 the last branch is used.

Assigning $null to uri attribute will drop the branch, for the rest of attributes will just set the value to null.

$(branch(uri)[2]) = "sip:test@kamailio.org;transport=sctp";

$br - Request's first branch

$br - reference to request's first branch

🔥IMPORTANT: It is R/W variable, you can assign values to it directly in configuration file (will add a new branch).

$bR - Request's all branches

$bR - reference to request's all branches

$bf - Branch flags

$bf - reference to branch flags of branch 0 (RURI) - decimal output

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file)

$bF - Branch flags

$bF - reference to branch flags of branch 0 (RURI) - hexa output

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file)

$bs - Body size

$bs - body size

$ci - Call-Id

$ci - reference to the value of call-id header

$cl - Content-Length

$cl - reference to the value of content-length header

$cnt(pv) - Count number of pvs

$cnt(avp) - return the number of avps

xlog("$$avp(x) found $cnt($avp(x)) times\n");

$cnt(xavp) - return the number of xavps

 * $cnt($xavp(key[*])) : number of XAVPs "key".
 * $cnt($xavp(key[n]=>sub[*])) : number of children "sub" in XAVP "key[n]".
 * $cnt($xavp(key[*]=>sub[*])) : total number of children "sub" in all XAVPs "key".

 * $cnt($xavp(key[n])) : 1 or 0 (if this index exists or not).
 * $cnt($xavp(key[-n])) : same but with reverse indexing (-1 is the last index).

 * $cnt($xavp(key[*]=>sub[n])) : number of children "sub[n]" that exist in all XAPVs "key".

 * $cnt($xavp(key)) is the same as $cnt($xavp(key[*])).
 * $cnt($xavp(key=>sub)) is the same as $cnt($xavp(key[*]=>sub[*]))

$conid - TCP Connection ID

$conid - The TCP connection ID of the connection the current message arrived on for TCP, TLS, WS, and WSS. Set to $null for SCTP and UDP.

$cs - CSeq Number

$cs - reference to the sequence number in the CSeq header. The method in the CSeq header is identical to the request method, thus use $rm to get the method (works also for responses).

$csb - CSeq Header Body

$csb - reference to the CSeq header body (number method).

$ct - Contact header

$ct - reference to the value of contact header

$cT - Content-Type

$cT - reference to the value of content-type header

$dd - Domain of destination URI

$dd - reference to domain of destination uri (without port)

$def(name) - Defined Value

$def(name) - return a defined value.

Example:

#!define ABC xyz

xlog("FLT_ACC: $def(ABC)\n");

$defn(name) - Defined Value As Number

$defn(name) - return a defined value as a signed integer.

Example:

#!define FLT_ACC 1

xlog("FLT_ACC: $defn(FLT_ACC)\n");

$di - Diversion header URI

$di - reference to Diversion header URI

$dip - Diversion "privacy" parameter

$dip - reference to Diversion header "privacy" parameter value

$dir - Diversion "reason" parameter

$dir - reference to Diversion header "reason" parameter value

$dic - Diversion "counter" parameter

$dic - reference to Diversion header "counter" parameter value

$dp - Port of destination URI

$dp - reference to port of destination uri

$dP - Transport protocol of destination URI

$dP - reference to transport protocol of destination uri

$ds - Destination set

$ds - reference to destination set

$du - Destination URI

$du - reference to destination uri

If loose_route() returns TRUE a destination uri is set according to the first Route header. $du is also set if lookup() function of 'registrar' module finds contact(s) behind NAT or if you use the path functionality. The function handle_ruri_alias() from the nathelper module will also set it. You can set $du to any SIP URI.

 sip:kamailio.org
 sip:pbx123.kamailio.org;transport=udp
 sip:[2001:DB8::33:2]:5980;transport=tls

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file)

To reset $du:

$du = $null;

$fd - From URI domain

$fd - reference to domain in URI of 'From' header

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file, but its value does not change)

$fn - From display name

$fn - reference to display name of 'From' header

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file, but its value does not change)

$fs - Forced Send Socket

$fs - reference to the forced send socket for the SIP message (if any) in the form "proto:ip:port". It is the socket from where Kamailio is going to send out the message.

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file). Transport proto can be omitted when assigning value, in which case it is taken from destination URI of the message.

Example:

listen=udp:1.2.3.4:5060
...
$fs = "udp:1.2.3.4:5060";

$fsn - Forced Send Socket Name

$fsn - reference to the name of the forced send socket for the SIP message. The name can be assigned to this variable to select a send socket via its name.

listen=udp:1.2.3.4:5060 name "s1"
...
$fsn = "s1";
...
$fs = "udp:1.2.3.4:5060";
xdbg("name for forced send socket: $fsn\n");

$ft - From tag

$ft - reference to tag parameter of 'From' header

$fti - Initial From tag

$fti - reference to tag parameter of 'From' header as it was in the initial request (e.g., initial INVITE).

The value From tag in the initial request can be in the To tag, if the request within the dialog is sent by the callee. This variable detects who sent the request within the dialog and returns the proper value that was in the From tag of the request initiating the dialog.

It is exported by rr module and has to be used after loose_route(). The append_fromtag parameter is required to be set to 1 in order to have this variable returning the right value.

$fu - From URI

$fu - reference to URI of 'From' header

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file, but its value does not change)

Note that changing the From: header may break backwards compatibility with SIP 1.0 devices.

$fU - From URI username

$fU - reference to username in URI of 'From' header

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file, but its value does not change)

Note that changing the From: header may break backwards compatibility with SIP 1.0 devices.

$fUl - From URI Username Length

$fUl - length of the username in the From URI

$mb - SIP message buffer

$mb - reference to SIP message buffer

$mbu - updated SIP message buffer

$mbu - reference to updated SIP message buffer, after applying changes

$mf - Flags

$mf - reference to message/transaction flags set for current SIP request

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file)

$mF - Flags in hexadecimal

$mF -reference to message/transaction flags set for current SIP request in hexa-decimal

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file)

$mi - SIP message id

$mi - reference to SIP message id

$ml - SIP message length

$ml - reference to SIP message length

$mt - SIP Message Type

$mt - returns 1 if the sip message is a request, returns 2 if the sip message is a reply

$od - Domain original R-URI

$od - reference to domain in request's original R-URI

$op - Port in original R-URI

$op - reference to port of original R-URI

$oP - Protocol of original R-URI

$oP - reference to transport protocol of original R-URI

$ou - Original R-URI

$ou - reference to request's original URI

$oU - Username in original R-URI

$oU - reference to username in request's original URI

$oUl - Original R-URI Username Length

$oUl - the length of the username in the original R-URI

$pd - Domain in P-Preferred-Identity header URI

$pd - reference to domain in request's P-Preferred-Identity header URI (see RFC 3325)

$pn - Display Name in P-Preferred-Identity header

$pn - reference to Display Name in request's P-Preferred-Identity header (see RFC 3325)

$pp - Process id

$pp - reference to process id (pid)

$pr or $proto - Protocol of received message

$pr or $proto - protocol of received message (udp, tcp, tls, sctp, ws, wss)

$prid - protocol id

$prid - internal protocol id

• 0 - NONE
• 1 - UDP
• 2 - TCP
• 3 - TLS
• 4 - SCTP
• 5 - WS
• 6 - WSS
• 7 - OTHER

$pU - User in P-Preferred-Identity header URI

$pU - reference to user in request's P-Preferred-Identity header URI (see RFC 3325)

$pu - URI in P-Preferred-Identity header

$pu - reference to URI in request's P-Preferred-Identity header (see RFC 3325)

$rb - Body of request/reply

$rb - reference to message body

$rc - Returned code

$rc - reference to returned code by last invoked function

$retcode - same as $rc

Note that the value of $rc is overwritten by each new function call.

Example of use:

    lookup("location");
    $var(rc) = $rc;
    if ($var(rc) < 0) {
        t_newtran();
        switch ($var(rc)) {
            case -1:
            case -3:
                send_reply("404", "Not Found");
                exit;
            case -2:
                send_reply("405", "Method Not Allowed");
                exit;
        }
    }

$rd - Domain in R-URI

$rd - reference to domain in request's URI (without port) or to the Namespace Specific String of a URN (see RFC 2141)

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file)

$rdir(key) - Request Direction

$rdir(key) - get the direction of the request within dialog.

The direction is 'downstream' if sent by the caller and 'upstream' if sent by callee.

The key can be:

• id - the returned value is an integer: 1 - for direction downstream, 2 - for direction upstream
• name - the returned value is a string: 'downstream' or 'upstream'

Example:

if($rdir(name)=="upstream") {
  xlog("request was sent by callee\n");
}

The variable is exported by rr module and append_fromtag parameter must be enabled. The variable has to be used after loose_route() function.

$re - Remote-Party-ID header URI

$re - reference to Remote-Party-ID header URI

$rm - SIP method

$rm - reference to request's method. Works also for replies (by using the CSeq header)

$rmid - SIP Method ID

$rmid - returns internal integer representation of SIP method type

$route_uri - URI in first Route header

$route_uri - returns the string with URI field in the first Route header

$rp - Port in R-URI

$rp - reference to port of R-URI

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file)

$rP - Protocol of R-URI

$rP - reference to transport protocol of R-URI

$rr - SIP reply reason phrase

$rr - reference to reply's reason phrase (the text after reply code)

$rs - SIP reply code

$rs - reference to reply's status (status-code, response-code, reply-code)

$rt - Refer-to URI

$rt - reference to URI of refer-to header

$ru - Request URI

$ru - reference to request's URI (address in the first line of a SIP request)

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file)

$rU - Username in R-URI

$rU - reference to username in request's URI or to the Namespace Identifier of a URN (see RFC 2141)

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file)

$rUl - R-URI Username Length

$rUl - the length of the username in R-URI

$rv - SIP message version

$rv - reference to SIP message (reply or request) version

$ruid - Record internal Unique ID

$ruid - the Record internal Unique ID for the location record selected by calling registrar:lookup()

$rz - URI Scheme of R-URI

$rz - returns R-URI scheme, possible values: sip, sips, tel, tels and urn, R-URI scheme parsing error should be reflected by value: none

$RAi - Received advertised IP address

$RAi - reference to advertised IP address of the interface where the request has been received, or $Ri if no advertised address.

$RAp - Received advertised port

$RAp - reference to advertised port where the request has been received, or $Rp if no advertised port.

$Ri - Received IP address

$Ri - reference to IP address of the interface where the request has been received

$Rp - Received port

$Rp - reference to the port where the message was received

$Rn - Received socket name

$Rn - reference to the name of the socket where the message was received

$RAu - Advertised socket URI

$RAu - local socket where the SIP messages was received in URI format, without transport parameter for UDP, using advertised address when available.

$RAut - Advertised socket URI

$RAut - local socket where the SIP messages was received in URI format, always with transport parameter, using advertised address when available.

$Ru - Received socket URI

$Ru - local socket where the SIP messages was received in URI format, without transport parameter for UDP.

$Rut - Received socket URI

$Rut - local socket where the SIP messages was received in URI format, always with transport parameter.

$sas - Source address in socket format

$sas - get source address in socket format (proto:address:port).

$sbranch(attr) - Static Branch

$sbranch(attr) - class of variables allowing to manage the values of attributes for static branch. The static branch is internal structure that is used by the functions sbranch_push_ruri() and sbranch_append() from pv module, enabling more flexibility in updating the R-URI (first) branch attributes as well as extra branches (e.g., for parallel forking).

The attr can be any of the supported values for $branch(attr) class of variables -- see above for proper details.

Example of usage:

sbranch_reset();
$sbranch(uri) = "sip:127.0.0.1:5080";
$sbranch(dst_uri) =  "sip:127.0.0.1:5090";
$sbranch(path) =  "sip:127.0.0.1:5090, sip:127.0.0.1:5094";
$sbranch(send_socket) =  "udp:127.0.0.1:5060";
sbranch_set_ruri();

$sf - Script flags

$sf - reference to script flags - decimal output

$sF - Script flags

$sF - reference to script flags - hexa output

$si - Source IP address

$si - reference to IP source address of the message - see also $siz

$sid - Server ID

$sid - the value for server id (server_id parameter)

$siz - Source IP address

$siz - reference to IP source address of the message, with enclosing square brackets for IPv6

$sp - Source port

$sp - reference to the source port of the message

$stat(name) - Statistics

$stat(name) - return the value of statistic item specified by 'name'

$su - Source address as URI

$su - returns the representation of source address (ip, port, proto) as SIP URI. If the proto is UDP, then it is not added (being the default transport protocol).

Its value looks like:

"sip:ip:port" -- if proto is UDP
"sip:ip:port;transport=proto"  -- if proto is not UDP

Note that WS and WSS are both represented by transport=ws, conforming with the IETF RFC for SIP over WebSocket.

$sut - Source address as full URI

$sut - returns the representation of source address (ip, port, proto) as full SIP URI. The proto UDP is added also as transport parameter.

Its value looks like:

"sip:ip:port;transport=proto"

$td - To URI Domain

$td - reference to domain in URI of 'To' header

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file, but its value does not change)

$tn - To display name

$tn - reference to display name of 'To' header

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file, but its value does not change)

$tt - To tag

$tt - reference to tag parameter of 'To' header

$tti - Initial To tag

$tti - reference to tag parameter of 'To' header as it was in the SIP response to the initial request (e.g., 200ok to the initial INVITE).

The value To tag in the initial transaction can be in the From tag, if the request within the dialog is sent by the callee. This variable detects who sent the request within the dialog and returns the proper value that was in the To tag of the transaction initiating the dialog.

It is exported by rr module and has to be used after loose_route(). The append_fromtag parameter is required to be set to 1 in order to have this variable returning the right value.

$tu - To URI

$tu - reference to URI of 'To' header

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file, but its value does not change)

$tU - To URI Username

$tU - reference to username in URI of 'To' header

🔥IMPORTANT: It is R/W variable (you can assign values to it directly in configuration file, but its value does not change)

$tUl - To URI Username Length

$tUl - the length of the username in To URI

$Tb - Startup timestamp

$Tb - reference to unix timestamp of the time at which kamailio was started (boot time)

$Tf - String formatted time - cached

$Tf - reference string formatted time

Note: the system time is retrieved only once for each processed SIP message. Subsequent calls of $Tf for same SIP message will return same value.

$TF - String formatted time - current

$TF - reference string formatted time

Note: the system time is computed for each call of $TF. Subsequent calls of $TF for same SIP message may return different values.

$Ts - Unix time stamp - cached

$Ts - reference to unix time stamp

Note: the system time is retrieved only once for each processed SIP message. Subsequent calls of $Ts for same SIP message will return same value.

$TS - Unix time stamp - current

$TS - reference to unix time stamp

Note: the system time is computed for each call of $TS. Subsequent calls of $TS for same SIP message may return different values.

$ua - User agent header

$ua - reference to user agent header field