核心内容摘要
糖心logo官方网站：开启品牌设计的“甜蜜革命”，打造触动人心的视觉新阵地
选择框架作者米哈尔·马蒂斯卡你可能会问选择框架究竟为何会被引入最主要的原因是以往每当你需要检查入站消息的任意部分如消息头时都必须编写新的模块或新的函数来实现该功能。
此外受历史局限性的影响这类函数最多只能接收两个参数。
若需要传入更多参数就必须采用变通方案先设置好相关属性再由该函数对属性进行校验。
因此为了让路由脚本更具可读性和易懂性一种全新的功能组件——选择框架应运而生并得到了支持。
在脚本中每个选择项都通过其唯一名称来标识。
设计这种标识符的初衷是让它的含义尽可能直观易懂。
例如当你看到to.uri.user时就能立刻明白它的作用是从To消息头所包含的URI中提取用户名。
在脚本里无论你在何处看到选择项标识符它所代表的实际上都是对应的值这个值会在路由脚本的执行过程中被调用。
为了保证选择框架的执行效率选择项标识符会在SER启动阶段完成解析和固化。
如果标识符无效系统会输出错误信息且SER将无法启动。
而在请求路由脚本的执行阶段仅需发起一次函数调用——如果该调用需要用到选择项标识符就会将解析后的标识符作为参数传入。
从性能角度来看调用某个模块中的专用函数与调用代表选择项标识符的函数二者几乎没有差异。
工作原理概述我们所说的选择项本质上是一种标准化调用方式用于调用那些在SER内核或各类模块中被定义为“选择函数”的方法。
选择项标识符以符号开头由若干文本元素组成元素之间用英文句点.分隔部分场景下还可以在方括号[]内添加单个整数或字符串作为参数。
选择项可在路由脚本的以下场景中使用表达式求值过程中作为属性赋值操作的右值作为部分函数的调用参数此用法仅适用于支持该特性的函数且参数必须是包含选择项标识符的文本因此需要用双引号括起来。
此外在Xlog日志格式化功能中选择项也可作为组成最终日志内容的元素其格式为%select.identifier.as.usual。
选择函数的返回值为文本字符串但需要注意的是在以下两种情况下返回值也可能是长度为0的空字符串一是该空值本身是合法的例如某些URI参数允许为空二是选择函数在消息头中未找到目标值或在解析消息时遇到语法错误。
这类异常情况会对条件表达式产生影响——只要选择项的求值过程出现错误无论其结果是否为空字符串条件表达式的最终判断结果都会为false。
选择项标识符规则选择项标识符以符号开头后接至少1个、最多30个文本元素元素之间用英文句点.分隔。
标识符的元素大小写不敏感你可以通过大小写区分来突出某些元素但建议优先使用小写形式。
部分选择函数支持传入参数例如重复消息头的索引、消息头名称或鉴权域这类参数需要放在方括号[]内嵌入到标识符中。
参数索引从1开始计数程序员需特别注意这一点这种设计更符合直观认知同时你也可以使用负数索引表示反向计数例如用-1表示获取最后一个消息头。
合法的标识符示例the.simplest another.with![parameter] yet.another![1].parameter![2] you.can.also.mix.string![like-this].and.integer![1].parameters嵌套选择项你可能会发现SIP请求中存在一些重复的模式例如许多SIP消息头中都包含URI元素。
选择框架支持复用内核中已有的URI解析器和选择函数也可以是参数值解析器包括消息头参数或URI参数解析器或是其他你能想到的解析器并将其作用于选择项的中间结果以此简化开发流程。
这种用法被称为嵌套选择项如果感兴趣可参考开发者文档它会将一次选择项调用拆分为两次或多次独立的函数调用第一次调用会返回URI文本作为临时结果随后该临时结果会被传入内置的URI选择处理机制最终生成目标结果。
例如hf_value![X-any-header].nameaddr.uri.user的执行逻辑为提取X-any-header消息头的值假设该值符合RFC规范中对name-addr格式的定义将其传入name-addr选择解析器解析器从URI中提取用户名并将其作为该选择项的最终返回值。
所有返回URI的选择项结果都可以传入专门的URI选择函数从而访问URI的各个组成部分。
以下选择项均可返回对应的URIrequest_uri、dst_uri、next_hop、from.uri、to.uri、refer_to.uri、rpid.uri、contact.uri、record_route.uri以及hf_value![any-header].nameaddr.uri。
若只需获取用户名只需在选择项标识符后追加.user即可。
无论第一步获取的是哪一个URI.user这个标识符后缀的含义和用法都是完全相同的。
URI嵌套选择项标识符列表标识符功能说明type返回标准化小写的URI类型例如sip、sips、tel、telsuser返回URI中的用户名pwd返回URI中的密码host返回URI中的主机地址port返回URI中的端口号以上标识符的功能均通俗易懂transport返回URI中transport参数的值若该参数不存在则返回基于URI类型的默认传输协议hostport返回URI中的主机:端口组合值若端口未指定则使用基于URI类型的默认端口params返回URI中的完整参数部分例如userphone;phone-context1234params![parameter-name]返回URI中指定参数的值选择项在表达式中的应用选择项可用于条件表达式常见用法如下非空判断if (select.value) {...}当选择项返回非空字符串时条件判断结果为true。
注意这种用法已被废弃SER启动时会输出警告信息。
在Sip-router中该写法的逻辑变为仅当返回值为非空且非零的数字字符串如123时条件才为true。
推荐使用标准写法if (select.value!)或if (!strempty(select.value))等值判断if (select.valuestring) {...} if (stringselect.value) {...}当选择项求值过程无错误且返回值与string完全相等时条件为true。
表达式右侧可以是任意值包括AVP变量、PV变量或其他选择项而非仅限于常量。
不等值判断if (select.value!string) {...} if (string!select.value) {...}用于判断两个字符串是否不相等。
若选择项求值过程出错条件判断结果也会为false。
正则匹配if (select.value~reg.*expr.?) {...}当选择函数返回的字符串匹配指定正则表达式时条件为true。
注意该运算符的左右操作数顺序不可随意调换例如if (string~select.value) {...}其逻辑是判断固定字符串string是否匹配选择项返回值作为正则表达式的规则这通常不符合实际需求。
选择项可用于任意类型的表达式中包括赋值操作的右值、if条件判断、while循环条件或switch分支判断等。
示例$attributethe.select.you.want选择项在函数参数中的应用部分函数支持将选择项的返回值作为调用参数但该特性仅适用于明确支持此功能的函数。
这类函数的参数会存储选择项标识符函数会在SER启动阶段负责解析并固化该标识符在运行阶段调用对应的选择函数以获取参数值。
若选择项求值过程出错函数会返回false且函数后续的执行逻辑通常会被跳过。
系统选择项随着选择框架的优势逐渐显现开发者开始探索更多可通过选择项访问的功能系统选择项便是其中之一。
这类选择项的标识符均以sys开头例如sys.pid返回当前进程ID的字符串形式sys.now返回Unix时间戳sys.utc返回UTC时间戳适用于多时区场景sys.unique生成并返回一个随机的UUID版本2模块中的选择项选择框架是一种功能强大的工具且可通过SER的模块机制轻松扩展。
以TLS模块为例脚本中需要获取或校验的大量TLS相关信息都需要依赖TLS模块才能实现。
因此所有与TLS相关的选择项都隶属于TLS模块——当你加载该模块后这些选择项即可使用若未加载模块SER会因检测到无效的选择项标识符而拒绝启动。
从使用角度来看模块提供的选择项与内核原生的选择项并无差异你无需关心选择项的具体来源只需确保已加载所有必需的模块即可。
选择项完整列表关于Sip-router开发版本主分支中已定义的所有选择项可参考官方文档http://sip-router.org/docbook/sip-router/branch/master/select_list/select_list.html。
追踪• 选择项