kamailio的伪变量

伪变量

版本: Kamailio SIP 服务器 v6.0.x (稳定版)

简介

伪变量（Pseudo-Variables）是指可在脚本函数中作为参数使用的特殊标记，这些标记在函数执行前会被替换为实际值。伪变量的起始标记为字符 $。若需在字符串中表示 $ 本身，需使用双写形式 $$。

伪变量由多个模块实现，大部分由 pv 模块提供（若无特殊说明，默认由 pv 模块提供）。

伪变量的用途

伪变量可用于以下模块：

accavpopshtablehttp_async_clienttextopsuacxlog

---

伪变量列表（按字母顺序） $$

表示字符 $。

$_s(format)

动态格式化字符串。 示例：

$var(x) = "sip:" + $rU + "@" + $fd; # 等价于： $var(x) = $_s(sip:$rU@$fd); $ai

引用请求头 P-Asserted-Identity 中的 URI（参见 RFC 3325）。

$adu

授权或代理授权头中的 URI，用于 HTTP Digest 响应计算。

$aa

授权或代理授权头中的算法。

$ar

授权或代理授权头中的 realm。

$au

授权或代理授权头中的用户名部分。

$ad

授权或代理授权头中的域名部分。

$aU

授权或代理授权头中的完整用户名。

$Au

计费用户名（来自 acc 模块），格式为 $au@$ar（若存在）或 $fu。

$AU

计费用户名（来自 acc 模块），格式为 $au（若存在）或 $fU。

$branch(name)

分支属性（仅限附加分支，主分支使用 $ru 或 $du）。

uri: 分支 URIdst_uri: 目标 URIpath: 路径向量q: Q 值（整数）send_socket: 发送套接字count: 分支总数flags: 分支标志ruid: 分支的唯一 ID

示例：

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

请求的第一个分支（可读写）。

$bR

请求的所有分支。

$bf

分支标志（十进制，可读写）。

$bF

分支标志（十六进制，可读写）。

$bs

消息体大小。

$ci

Call-Id 头的值。

$cl

Content-Length 头的值。

$cnt(pv)

统计伪变量数量。 示例：

xlog("$$avp(x) 出现次数：$cnt($avp(x))\n"); $conid

TCP 连接 ID（UDP/SCTP 为 $null）。

$cs

CSeq 头的序列号。

$csb

CSeq 头的完整内容。

$ct

Contact 头的值。

$cts

Contact 头是否为 *（1 表示存在值，0 表示 *）。

$ctu

Contact 头的 URI 部分。

$cT

Content-Type 头的值。

$dd

目标 URI 的域名（不含端口）。

$def(name)

返回定义的值。 示例：

#!define ABC xyz xlog("FLT_ACC: $def(ABC)\n"); $defn(name)

返回定义的数值。 示例：

#!define FLT_ACC 1 xlog("FLT_ACC: $defn(FLT_ACC)\n"); $di

Diversion 头的 URI。

$dip

Diversion 头的 privacy 参数。

$dir

Diversion 头的 reason 参数。

$dic

Diversion 头的 counter 参数。

$dp

目标 URI 的端口。

$dP

目标 URI 的传输协议。

$ds

目标集合。

$du

目标 URI（可读写）。 示例：

$du = "sip:kamailio.org;transport=tls"; 转义字符 $Eb: \$En: \n$Er: \r$Et: \t$Es: 空格$Ec: ,$Eq: "$Ek: '$Ei: :$Ej: ;$Ev: ` $fd

From 头的域名（可读写，但实际值不变）。

$fn

From 头的显示名称（可读写，但实际值不变）。

$fs

强制发送套接字（格式 proto:ip:port，可读写）。

$fsn

强制发送套接字名称（可读写）。

$ft

From 头的标签。

$fti

初始请求中的 From 标签（需启用 append_fromtag）。

$fu

From 头的 URI（可读写，但实际值不变）。

$fU

From 头的用户名（可读写，但实际值不变）。

$fUl

From 用户名的长度。

$mb

SIP 消息缓冲区。

$mbu

更新后的 SIP 消息缓冲区。

$mf

消息/事务标志（十进制，可读写）。

$mF

消息/事务标志（十六进制，可读写）。

$mi

SIP 消息 ID。

$ml

SIP 消息长度。

$mt

消息类型（1 为请求，2 为响应）。

$od

原始请求 URI 的域名。

$op

原始请求 URI 的端口。

$oP

原始请求 URI 的传输协议。

$ou

原始请求 URI。

$oU

原始请求 URI 的用户名。

$oUl

原始请求 URI 用户名的长度。

$pd

P-Preferred-Identity 头的域名。

$pn

P-Preferred-Identity 头的显示名称。

$pp

进程 ID。

$pr 或 $proto

接收消息的协议（如 udp, tcp）。

$prid

协议 ID（如 UDP=1, TCP=2）。

$pU

P-Preferred-Identity 头的用户名。

$pu

P-Preferred-Identity 头的 URI。

$rb

消息体内容。

$rc

上一个函数的返回码。

$rd

请求 URI 的域名（可读写）。

$rdir(key)

请求方向（downstream 或 upstream）。

$re

Remote-Party-ID 头的 URI。

$rm

请求方法（如 INVITE）。

$rmid

请求方法的内部 ID。

$route_uri

第一个 Route 头的 URI。

$rp

请求 URI 的端口（可读写）。

$rP

请求 URI 的传输协议。

$rr

响应的原因短语。

$rs

响应的状态码。

$rt

Refer-To 头的 URI。

$ru

请求 URI（可读写）。

$rU

请求 URI 的用户名（可读写）。

$rUl

请求 URI 用户名的长度。

$rv

SIP 消息版本（如 SIP/2.0）。

$ruid

位置记录的内部唯一 ID。

$rz

请求 URI 的协议方案（如 sip, tel）。

$RAi

接收接口的广告 IP。

$RAp

接收接口的广告端口。

$Ri

接收消息的源 IP。

$Rp

接收消息的源端口。

$Rn

接收套接字名称。

$RAu

广告套接字 URI（无传输参数）。

$RAut

广告套接字 URI（带传输参数）。

$Ru

接收套接字 URI（无传输参数）。

$Rut

接收套接字 URI（带传输参数）。

$sas

源地址（格式 proto:ip:port）。

$sbranch(attr)

静态分支属性（同 $branch）。

$sf

脚本标志（十进制）。

$sF

脚本标志（十六进制）。

$si

源 IP 地址。

$sid

服务器 ID。

$siz

源 IP（IPv6 带方括号）。

$sp

源端口。

$stat(name)

统计项的值。

$su

源地址的 SIP URI（无传输参数）。

$sut

源地址的完整 SIP URI。

$td

To 头的域名（可读写，但实际值不变）。

$tn

To 头的显示名称（可读写，但实际值不变）。

$tt

To 头的标签。

$tti

初始响应中的 To 标签（需启用 append_fromtag）。

$tu

To 头的 URI（可读写，但实际值不变）。

$tU

To 头的用户名（可读写，但实际值不变）。

$tUl

To 用户名的长度。

$Tb

Kamailio 启动时间戳。

$Tf

格式化时间（缓存）。

$TF

格式化时间（实时）。

$Ts

Unix 时间戳（缓存）。

$TS

Unix 时间戳（实时）。

$ua

User-Agent 头的值。

$version()

版本信息：

$version(num): 数字版本$version(full): 完整版本字符串$version(hash): 哈希值 $env(NAME)

环境变量的值。

$avp(id)

AVP 值（可读写）。 示例：

$avp(x) = 1; $avp(y) = "abc"; $expires(key)

Expires 头的最小/最大值。

min: 最小值max: 最大值 $xavp(id)

扩展 AVP（支持嵌套结构）。 示例：

$xavp(person=>lastname) = "Smith"; $hdr(name)

头域值（只读）。 示例：

if($hdr(From) =~ "kamailio\.org") { ... } $hfl(name)

多值头域的单个值（如 Contact, Via）。

$hdrc(name)

头域数量。

$hflc(name)

头域值的数量。

$var(name)

私有内存变量（可读写）。 示例：

$var(a) = 1; $vz(name)

同 $var(name)。

$vn(name)

支持 $null 的私有变量。

$shv(name)

共享内存变量（可读写）。

$dsv(key)

分发器变量（如 code, reason）。

$dsg(key)

分发器组属性（如 count, active）。

$time(name)

本地时间的分解属性（如 sec, min）。

$utime(name)

UTC 时间的分解属性。

$timef(format)

格式化本地时间。

$utimef(format)

格式化 UTC 时间。

$ccp(key)

全局配置参数。

$sel(name)

选择器（如 via[1].host）。

$rcv(key)

接收数据的属性（如 buf, srcip）。

$rpl(key)

响应属性（如 duri, dhost）。

$msgbuf(index)

消息缓冲区的字符（可读写）。

$hfitname(iname)

头域迭代器的名称。

$hfitbody(iname)

头域迭代器的内容。

$blitval(iname)

消息体行的值。

$sndfrom(name)

发送地址的本地套接字属性。

$sndto(name)

发送地址的远程套接字属性。

$sipdump(name)

SIPDUMP 模块的消息属性。

$siptrace(name)

SIPTRACE 模块的消息属性。

$BM_time_diff

基准测试时间差。

$dlg(attr)

对话属性（如 h_id, state）。

$dlg_ctx(attr)

对话上下文属性（如 flags, timeout）。

$dlg_var(key)

对话自定义变量。

$erl_atom(name)

Erlang 原子类型。

$erl_list(name)

Erlang 列表类型。

$erl_tuple(name)

Erlang 元组类型。

$evapi(key)

EVAPI 模块的事件属性。

$sht(htable=>key)

哈希表条目（可读写）。

$shtex(htable=>key)

哈希表条目的过期时间。

$shtcn(htable=>exp)

匹配正则的哈希表条目数。

$shtcv(htable=>exp)

匹配值的哈希表条目数。

$shtinc(htable=>key)

原子递增哈希表值。

$shtdec(htable=>key)

原子递减哈希表值。

$shtitkey(iname)

哈希表迭代器的键。

$shtitval(iname)

哈希表迭代器的值。

$shtrecord(id)

过期哈希表记录的键或值。

$mct(key)

Memcached 条目（可读写）。

$mcinc(key)

原子递增 Memcached 值。

$mcdec(key)

原子递减 Memcached 值。

$http_req_id

HTTP 请求的唯一 ID。

$http_req(key)

HTTP 请求参数（如 method, body）。

$http_ok

HTTP 请求是否成功。

$http_err

HTTP 错误信息。

$http_rs

HTTP 状态码。

$http_rr

HTTP 原因短语。

$http_hdr(Name)

HTTP 头域值。

$xml(name=>spec)

XML 文档操作。

$T_branch_idx

当前分支的索引。

$T_reply_code

响应的状态码。

$T_req(pv)

事务请求的属性。

$T_rpl(pv)

事务响应的属性。

$T_inv(pv)

INVITE 请求的属性。

$T(name)

事务属性（如 id_index, reply_code）。

$uac_req(key)

UAC 请求参数（如 method, ruri）。

$rr_count

Record-Route 头的数量。

$rr_top_count

顶部 Record-Route 的数量。

$mqk(q)

队列的键。

$mqv(q)

队列的值。

$TV(name)

时间戳（秒和微秒）。

$nh(key)

下一跳地址属性（如 u, d）。

$gip(pvc=>key)

GeoIP 属性（如 cc, tz）。

$tls(key)

TLS 属性（如 m_issuer_line, p_subject_line）。

$msrp(key)

MSRP 帧属性（如 body, method）。

$sipt(key)

SIP-T 属性（如 calling_party_number）。

$dns(pvid=>key)

DNS 查询结果（如 count, addr）。

$HN(key)

本地主机名属性（如 n, f）。

$RANDOM

随机数（0 到 2^31-1）。

$jsonrpl(key)

JSONRPC 响应属性（如 code, body）。

$cfg(key)

配置文件属性（如 line, name）。

$lsock(expr)

监听套接字属性（如 name, listen）。

$atkv(name)

异步事件属性（如 type, key）。

$evr(key)

执行事件属性（如 data, srcip）。

$ulc(profile=>attr)

注册联系人的属性。

$hep(key)

HEP 数据包属性（如 version, src_ip）。

$phn(rid=>key)

电话号码匹配结果（如 number, valid）。

$secsipid(key)

安全 SIP 身份属性（如 val, ret）。

$sdp(key)

SDP 属性（如 body, c:ip）。

$sruid

唯一 ID。

$ltt(key)

本地生成的 To 标签。

$via0(attr)

第一个 Via 头的属性（如 host, port）。

$via1(attr)

第二个 Via 头的属性。

$viaZ(attr)

最后一个 Via 头的属性。

$tcp(key)

TCP 连接属性（如 c_si, conid）。

$C(xy)

终端颜色代码（如 $C(bg) 表示背景色）。

$K(key)

Kamailio 常量（如 IPv4, UDP）。

---

示例 示例 1：伪变量基本用法 avp_aliases="uuid=I:50" route { $avp(uuid) = "caller_id"; $avp(i:20) = $avp(uuid) + ": " + $fu; xdbg("$(C(bg))avp(i:20)$(C(xx)) [$avp(i:20)] $(C(br))cseq$(C(xx))=[$hdr(cseq)]\n"); } 示例 2：请求 URI 解析 # 请求 URI 包含 SIP URI $ru = "sip:example "; $rz = "sip"; $rU = "<null>"; $rd = "example "; $rp = "5060"; 以下是关于请求URI（Request-URI）和目的URI（Destination-URI）解析的示例说明，涵盖SIP-URI、tel-URI和服务型URN的解析规则： --- ### **请求URI包含SIP URI** ```plaintext $ru = "sip:example " $rz = "sip" // 协议方案 $rU = "<null>" // 用户名为空 $rd = "example " // 域名 $rp = "5060" // 默认端口 $rP = "UDP" // 默认传输协议 $ru = "sips:john.q.public:hispw@example :6061 transport=tls;foo=bar" $rz = "sips" // 协议方案（加密SIP） $rU = "john.q.public" // 用户名 $rd = "example " // 域名 $rp = "6061" // 显式指定端口 $rP = "tls" // 显式指定传输协议

---

请求URI包含服务型URN $ru = "urn:service:sos.fire" $rz = "urn" // 协议方案（统一资源名） $rU = "service" // URN命名空间标识 $rd = "sos.fire" // URN具体内容 $rp = "5060" // 默认端口 $rP = "UDP" // 默认传输协议

---

请求URI包含tel: URI $ru = "tel:+1-201-555-0123" $rz = "tel" // 协议方案（电话URI） $rU = "+1-201-555-0123" // 电话号码 $rd = "<null>" // 无域名 $rp = "5060" // 默认端口 $rP = "UDP" // 默认传输协议 $ru = "tel:7042;phone-context=example " $rz = "tel" // 协议方案 $rU = "7042" // 本地号码 $rd = "<null>" // 无域名（phone-context定义上下文） $rp = "5060" // 默认端口 $rP = "UDP" // 默认传输协议

---

目的URI（必须是SIP(S) URI） $du = "sip:example :6061;transport=tls;foo=bar" $dd = "example " // 目标域名 $dp = "6061" // 显式指定端口 $dP = "tls" // 显式指定传输协议

---

关键字段说明 $rz：URI的协议方案（如sip、sips、tel、urn）。$rU：用户信息部分（如用户名、电话号码或URN命名空间）。$rd/$dd：域名或URN内容。$rp/$dp：端口号（未显式指定时使用默认值5060）。$rP/$dP：传输协议（未显式指定时使用默认值UDP）。