opensips Core Variables
原文
Prev
Opensips提供多种类型的变量，用于路由脚本。变量类型之间的差异来自1）变量的可访问性（何处可访问）2）变量隶属于哪里（变量所在的位置）3）变量的读写状态（有些变量仅可读）4）多个值（for the same variable handled）
opensips变量可以在脚本中轻松识别，因为他们的所有名称均以’$'符号开头。
语法：
伪变量的完整语法是：
$(<context>name(subname)[index]{transformation})
name之外的部分是可选的，字段含义如下：
- name（必选）- 伪变量名(类型)
例如 pvar,avp,ru,DLG_status等等 - subname - 给定类型的某个pv的标识符
例如 hdr(From), avp(name)。 - index - 一个pv可用存储多个值-可以一个值列表。如果指定index可以获取到List中的特定值。你也可以指定负数，-1标识最后一个插入的，-2标识标识倒数第二个插入的。
- transformation - 可以作用于伪变量的一系列操作。你可以在Script-Tran发现所有可用的transformations.transformation可以级联，使用一个transformation的输出作为另一个transformation的输入。
- context - the context in which the pseudo0variable will be evaluated. Now there are 2 pv contexts: reply and request. The reply context can be used in the failure route to request for the pseudo-variable to be evaluated in the context of the reply message. The request context can be used if in a reply route is desired for the pv to be evaluated in the context of the corresponding request.
用法示例： - Only name: $ru
- Name and 'subname: $hdr(Contact)
- Name and index: $(ct[0])
- Name, subname and index: $(avp(i:10)[2])
- Context - ：
$(<request>ru) from a reply route will get the Request-URI from the request
$(<reply>hdr(Contact)) context can be used from failure route to access information from the reply
变量类型： - script variables - 顾名思义，这些变量严格的绑定到脚本语言。变量尽在路由块中可见-他们不与消息和事务相关，但是他们和进程相关（脚本变量将由同一opensips进程执行的脚本继承）。
- AVP- Attribute Value Pair - AVPs是可以创建的动态变量-avps和单个消息或者事务（如果使用有状态代理）相关联。最初（当接收或者创建）消息或者事务具有附加的AVPs的空白列表。在路由脚本中,脚本或者从脚本调用的函数可以创建新的AVPS：和事件或者事务关联。AVPS对于事务处理的所有消息(回复或者请求)都是可访问的- branche_route, failure_route,noreply_route（对于noreplay_route,需要开启TM参数noreply_vap_mode）。AVPs是可读写的并且现有的AVP可以删除（移除）。一个AVP可以包含多个值-新的赋值（或写操作）将向AVP添加新值；这个值保存在’最后添加最先使用’序列中。
- paeudo variables - 伪变量(或者PV)提供已处理的SIP消息的信息（headers,RURI,transprot level info,a.s.o）或者opensips内部（time values, process PID,return code of a function）。根据他们提供的消息，PVs即可以绑定到消息，也可以绑定到任何内容（全局）。大部分PVs是只读的并且仅仅少数允许写操作。一个PV可以返回几个值或仅返回一个值，具体取决于所引用的信息（可以有多个值）。标准PV是只读的并且仅仅返回一个值(如果没有另外说明).
- escape sequences - escape sequences可以用于格式化字符串；他们实际上不是变量，而是格式化程序。
Script variables
Naming: $var(name)
Hints:
- 如果你想在一个路由中初始化一个脚本变量，最好使用相同的值初始化它(或重置它)，否则你可能从同一进程执行的先前路由继承数据。
- 脚本变量比AVP更快，因为他们直接引用内存位置。
- 脚本变量的值在opensips进程中持续存在。
- 脚本变量只能有一个值。
使用用例
$var(a) = 2; # sets the value of variable 'a' to integer '2'
$var(a) = "2"; # sets the value of variable 'a' to string '2'
$var(a) = 3 + (7&(~2)); # arithmetic and bitwise operation
$var(a) = "sip:" + $au + "@" + $fd; # compose a value from authentication username and From URI domain
# using a script variable for tests
if( [ $var(a) & 4 ] ) {
xlog("var a has third bit set\n");
}
设置变量为NULL实际上是初始化为整数’0’。脚本变量没有NULL值。
AVP variables
Naming: $avp(name) or $(avp(name)[N])
使用索引"N"时，可以强制AVP返回某个值（第N个值）。如果没有指定index,则返回第一个值。
Hints:
- 要在onreply_route中使用AVPs,需要使用"modparam(“tm”, “onreply_avp_mode”, 1)"
- 如果一个VAPs有多个值，值的顺序与添加的顺序相反。
- AVPs是事务context的一部分，因此他们在当前事务的任何地方都是可访问的。
- AVP的值可以删除。
使用用例
事务持久性示例
# enable avps in onreply route
modparam("tm", "onreply_avp_mode", 1)
...
route{
...
$avp(tmp) = $Ts ; # store the current time (at request processing)
...
t_onreply("1");
t_relay();
...
}
onreply_route[1] {
if (t_check_status("200")) {
# calculate the setup time
$var(setup_time) = $Ts - $avp(tmp);
}
}
多个值示例
$avp(17) = "one";
# we have a single value
$avp(17) = "two";
# we have two values ("two","one")
$avp(17) = "three";
# we have three values ("three","two","one")
xlog("accessing values with no index: $avp(17)\n");
# this will print the first value, which is the last added value -> "three"
xlog("accessing values with no index: $(avp(17)[2])\n");
# this will print the index 2 value (third one), -> "one"
# remove the last value of the avp; if there is only one value, the AVP itself will be destroyed
$avp(17) = NULL;
# delete all values and destroy the AVP
avp_delete("$avp(17)/g");
# delete the value located at a certain index
$(avp(17)[1]) = NULL;
#overwrite the value at a certain index
$(avp(17)[0]) = "zero";
AVPOPS模块提供了大量有效的方法操作AVPS（如检查值，将值推送到不同的其他位置，删除AVPs等等）
Pseudo Variables
Naming: $name
Hints:
- PV tokens可以作为不通脚本方法的参数给出，并且在函数执行前会赋值覆盖。
- 大多数PVs对于opensips core提供，但是也有模块导出PV（以便为特定模块提供可用信息）-检查modules文档。预定义的PVs（由core提供）按照字母顺序罗列。
URI in SIP Request’s P-Asserted-Identity header
$ai - 请求的P-Asserted-Identity header的URI引用（RFC3325）。
Authentication Digest URI
$adu - Authorization或者Proxy-Authorization header的URI。用于计算http Digest响应。
Authentication realm
$ar - Authorization或者Proxy-Authorization header中 realm。
Authentication user
$au - Authorization或者Proxy-Authorization header中username的user部分。
Auth username domain
$ad - Authorization或者Proxy-Authorization header中username的domain部分。
Auth nonce
$an - Authorization或者Proxy-Authorication header的nonce。
Auth response
$auth.resp - Authorization或者Proxy-Authorization header的认证返回。
Auth nonce
$auth.nonce - Authorization或者Proxy-Authorization header的nonce 字符串。
Auth opaque
$auth.opaque - Authorization或者Proxy-Authorization header的opaque字符串。
Auth algorithm
$auth.alg - Authorization或者Proxy-Authorization header的algorithm字符串。
Auth QOP
$auth.qop - Authorization或者Proxy-Authorization header的qop参数的值。
Auth nonce count(nc)
$auth.nc - Authorization或者Proxy-Authorization header的nonce count参数的值。
Auth whole username
$aU - Authorization或者Proxy-Authorization header的整个username。
Acc username
$aU - 用于计费的username。这是一个selective pseudo variable（继承自acc模块）。如果存在返回$au，否则返回From username。
Argument options
$argv - 提供对使用’-o’选项指定的命令行参数的访问。例子：
# for option '-o foo=0'
xlog("foo is $argv(foo) \n");
Branch flags
$bf - 展示当前SIP请求的branch flags的列表。
Branch
$branch - 该变量用于创建一个新的branches：写入SIP URI的值。示例：
# creates a new branch
$branch = "sip:new@doamin.org";
# print its URI
xlog("last added branch has URI $(branch(uri)[-1]) \n");
Branch fields
$branch() - 该变量提供对现有branch的所有fields/attributes的读写权限（先前使用append_branch()创建）。branch的域如下：
- uri - the RURI of the branch (string value)
- duri - destination URI of the branch (outbound proxy of the branch) (string value)
- q - q value of the branch (int value)
- path - the PATH string for this branch (string value)
- flags - the branch flags of this branch (int value)
- socket - the local socket to be used for relaying this branch (string value)
该变量接收index$(branch(uri)[1])以访问特定的branch(可以同时定义多个branch)。index从0开始（第一个branch）。如果index是负数，则指倒数第n个（-1表示最后一个branch）。
如果想要得到所有的branch,使用 * index- $(branch(uri)[*])。
示例：
# creates the first branch
append_branch();
# creates the second branch
force_send_socket(udp:192.268.1.12:5060);
$du = "sip:192.268.2.20";
append_branch("sip:foo@bar.com","0.5");
# display branches
xlog("----- branch 0: $(branch(uri)[0]) , $(branch(q)[0]), $(branch(duri)[0]), $(branch(path)[0]), $(branch(flags)[0]), $(branch(socket)[0]) \n");
xlog("----- branch 1: $(branch(uri)[1]) , $(branch(q)[1]), $(branch(duri)[1]), $(branch(path)[1]), $(branch(flags)[1]), $(branch(socket)[1]) \n");
# do some changes over the branches
$branch(uri) = "sip:user@domain.ro"; # set URI for the first branch
$(branch(q)[0]) = 1000; # set to 1.00 for the first branch
$(branch(socket)[1]) = NULL; # reset the socket of the second branch
$branch(duri) = NULL; # reset the destination URI or the first branch
该变量是R/W变量（可以从路由逻辑中为期赋值）。
Call-Id
$ci - call-id header内容的引用
Content-Length
$cl - content-length header内容的引用
CSeq number
$cs - cseq header的cseq number的引用。
Contact instance
$ct - contact header的contact instance/body的引用。一个contact instance的样式：display_name + URI + contact_params。由于一个contact header可能包含多个contact instance并且一个消息可能包含多个contact,因此在$ct变量中添加索引index。
- name - display name
- uri - contact uri
- q - q params(value only)
- expires - expires param(value only)
- methods - methods param(value only)
- received - received param(value only)
- params - all params (include names)
示例
$ct.fields(uri) - the URI of the first contact instance
$(ct.fields(name)[1]) - the display name of the second contact instance
contact-Type
$cT - Content-Type header的内容引用。并且Content-type headers在多个body中。
- $cT - 消息的主要Content-Type;headers中的一个。
- $(cT[n]) - 消息多个信息中的第n个Content-Type，索引以0开始。
- $(cT[-n]) - 消息多个信息中的倒数第n个Content-Type，索引以-1开始。
- $(cT[*]) - 所有的Content-Type header包含主要的以及其他的。
Domain of destination URI
$dd - destination uri的domain引用
该变量是R/W（可以在路由逻辑中赋值）。
Diversion header URI
$di - Diversion header URI的引用。
Diversion “privacy” parameter
$dip - Diversion header "privacy"参数值的引用。
Diversion “reason” parameter
$dir - Diversion header "reason"参数值的引用。
Port of destination URI
$dp - destination uri的port引用。
该变量可R/W（可以在路由逻辑中修改）。
Transport protocol of destination URI
$dp - destination uri的传输协议。
Destination set
$ds - destination set的引用。
Destination URI
$du - destination uri的引用(用于发送请求的outbound proxy)。如果loose_route()返回TRUE，依据第一个Route header为destination uri赋值。
该变量可R/W（可以在路由逻辑中赋值）。
Error class
$err.class - error对应的类名。（解析erros对应index ‘1’）。
Error level
$err.level - error的严重级别。
Error info
$err.info - error的文本描述。
Error reply code
$err.rcode - recommended reply code
Error reply reason
$err.rreason - recommended reply reason phrase
From URI domain
$fd - ‘From’ header URI的domain。
From display domain
$fn - ‘From’ header 的display name
Forced socket
$fs - 以 proto:ip:port格式用于消息发送的强制socket。
该变量是可R/W的（可以在路由脚本修改）。
From tag
$ft - ‘From’ header的tag参数引用。
From URI
$fu - ‘From’ header的URI引用。
From URI username
$fU ‘From’ header中URI的username引用。
OpenSIPS Log Level
$log_level - 修改当前进程的日志级别；日志级别可以设置为一个新的值（请参阅可用的值或者可以将其重置为全局日志等级。如果进跟踪和调试特定代码，此功能非常有效）。
使用用例
log_level= -1 # errors only
.....
{
......
$log_level = 4; # set the debug level of the current process to DBG
uac_replace_from(....);
$log_level = NULL; # reset the log level of the current process to its default level
.......
}
SIP message buffer
$mb - reference to SIP message buffer
Message Flags
$mf - 展示当前SIP请求的message/trnasaction flags set 的列表。
SIP message ID
$mi - SIP message id的引用。
SIP message length
$ml - SIP message length的引用。
Domain in SIP Request’s original URI
$od - 请求的原始R-URL的domain引用。
Port of SIP request’s original URI
$op - 原始R-URI的端口引用
Transport protocol of SIP request original URI
$oP - 原始R-URI的传输协议。
SIP Request’s original URI
$ou - 请求原始URI引用。
Username in SIP Request’s original URI
$oU - 请求原始URI的username。
Route parameter
$param(idx) - 检索路由的参数。索引index可以是整数也可以是pseudo-variable(index从1开始)。
示例
route {
...
$var(debug) = "DBUG:"
route(PRINT_VAR, $var(debug), "param value");
...
}
route[PRINT_VAR] {
$var(index) = 2;
xlog("$param(1): The parameter value is <$param($var(index))>\n");
}
Domain in SIP Request’s P-Preferred-Identity header URI
$pd - 请求的P-Preferred-Identity header URI 的domain引用（参考RFC3325）。
Display Name in SIP Request’s P-Preferred-Identity header
$pn - 请求的P-Preferred-Identity header URI 的Display Name引用（参考RFC3325）。
Process id
$pp - process id的引用(pid)
Protocol of received message
$pr or $proto - 接收的消息的协议(UDP,TCP,TLS,SCTP,WS)。
User in SIP Request’s P-Preferred-Identity header URI
$pU - 请求的P-Preferred-Identity header URI 的user引用（参考RFC3325）。
URI in SIP Request’s P-Preferred-Identity header
$pu - 请求的P-Preferred-Identity header的URI引用。
Domain in SIP Request’s URI
$rd - 请求URI的domain引用。
Body of request/reply
$rb - 消息体的引用。
- $rb - 消息体
- $(rb[*]) - 类似于$rb
- $(rb[n]) - 消息体多个body中的第n个body。计数从0开始。
- $(rb[-n]) - 消息体多个 body中的倒数第n个body，计数从-1开始（对应最后一个）
Returned code
$rc - 上次调用的function返回的code
$retcode - 和$rc类似。
Remote-Party-ID header URI
$re - Remote-Party-ID header URI的引用。
SIP request’s method
$rm - 请求method的引用
SIP request’s port
$rp - R-URI的端口
该变量是R/W的（可以在路由脚本赋值）。
Transport protocol of SIP request URI
$rP - R-URI的传输协议。
SIP reply’s reason
$rr - reference to reply’s reason
SIP reply’s status
$rs - reference to reply’s status
Refer-to URI
$rt - refer-to header的引用。
SIP Request’s URI
$ru - 请求URI的引用
该变量是R/W变量（可以在路由脚本赋值）。
Username in SIP Request’s URI
$rU - 请求URI的username引用。
该变量是R/W变量（可以在路由脚本赋值）。
Q value of the SIP Request’s URI
$ru_q - R-URI中q的值。
Received IP address
$Ri - 收到请求的接口IP地址。
Received port
$Rp - 接收消息对应的端口。
Script flags（Removed in OpenSIPS 2.2）
$sf - 展示当前sip请求的script flags set的列表。
IP source address
$si - 消息的ip源地址。
Source port
$sp - 消息的源端口。
To URI Domain
$td - ‘To’ header URI的domain。
To display name
$tn - ‘To’ header的diaplay name。
To tag
$tt - ‘To’ header的tag参数。
To URI
$tu - ‘To’ header的URI
To URI Username
$tU - ‘To’ header的URI的username
Formatted date and time
$time(format) - 依据unix时间返回格式化的字符串。
Branch index
$T_branch_idx - 执行branch_route[]的branch的index（索引从1开始）。如果在branch_route[] 代码块外使用，值为0。由TM模块提供。
String formatted time
$Tf - 字符串格式化时间。
Current unix time stamp in seconds
$Ts - 当前的unix时间戳(秒)。
Startup unix time stamp
$TS - 启动unix时间戳
User agent header
$ua - user agent header 字段
SIP Headers
$(hdr(name)[N]) - 表示由’name’标识的第N个header的正文。如果省略[N]，打印第一个header对应的正文。N=0时获取第一个header，N=1时获取第二个header。 打印最后一个header，使用-1。现在还不支持其他负数。不允许存在空格(before }, before or after {, [, ] symbols)。当N=’*'时，打印指定类型的所有headers。
该模块需要识别大多数 compact header 名字（所有opensips识别的名字）。如果不能，必须明确指定的compact form。建议使用headers的专用说明符（比如%ua 对应user agent header），如果可用，则更快。
$(hdrcnt(name)) - 返回由’name’标识的headers的数目。使用和上面$(hdr(name))相同规则的headers name。很多headers（如 Via, Path, Record-Route）可能出现很多次。该变量返回执行类型headers的数目。
请注意，一些headers可能用逗号连接在一起并显示未单个header line。该变量返回header lines的数目，而不是header的值。
对于下面的消息碎片，$(hdrcn(Path))值为2，并且$(hdr(Path)[0])返回 <a.com>：
Path: <a.com>
Path: <b.com>
对于下面的消息碎片，$(hdrcn(Path))值为1，并且$(hdr(Path)[0])返回 <a.com>,<b.com>：
Path: <a.com>,<b.com>
注意上面两个例子语音上都是等效的，但是变量对应不同的值。
Route Type
$rT - 将当前路由类型保存为字符串。用于在另一个路由脚本中，确定原始路由类型，例如从onreplay_route调用的route。允许更加重用可重用的routes如日志route：在日志信息中包含route type。
Current script line and file
$cfg_line - 保存正在执行的路由脚本的当前行，有益于记录日志
$cfg_file - 保存正在执行的cfg文件名，在通过include包含多个脚本时非常有效。
$shv(name)
存储在共享内存的pseudo-variables。所有opensips进程都可以看到$shv(name)的值。每个"shv"都有单个值并且初始化为整数0。可以使用"shvset"参数初始化共享变量。该模块提供了一组MI函数去获取/设置共享变量的值。
参考 cfgutils
使用示例
...
modparam("cfgutils", "shvset", "debug=i:1")
...
if ($shv(debug) == 1) {
xlog("request: $rm from $fu to $ru\n");
}
...
Escape Sequences（转移序列）
这些序列主要由xlog模块提供并使用，使用转义序列用不通的颜色打印消息(前景和背景)。
Foreground and background colors
$C(xy) - 转义序列，¿x¿ represents the foreground color and ¿y¿ represents the background color.
支持的颜色如下：
- x : default color of the terminal
- s : Black
- r : Red
- g : Green
- y : Yellow
- b : Blue
- p : Purple
- c : Cyan
- w : White
示例
使用示例
...
route {
...
$avp(uuid)="caller_id";
$avp(tmp)= $avp(uuid) + ": " + $fu;
xlog("$C(bg)$avp(tmp)$C(xx) [$avp(tmp)] $C(br)$cs$C(xx)=[$hdr(cseq)]\n");
...
}
...
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
