You are here: start » ref_manual » selects

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision 		Previous revision
Next revision Both sides next revision
ref_manual:selects [2009/05/05 00:24]
janakj created 		ref_manual:selects [2012/03/15 09:03]
109.230.216.225 FQMiCeqSQnI
Line 1: Line 1:
-====== The Select Framework ====== +Hmm it seems like your site ate my first comment (it was super long) so I guess I'll just sum it up what I wrote and say, I'm rohthugoly enjoying your blog. I as well am an aspiring blog blogger but I'm still new to everything. Do you have any points for rookie blog writers? I'd definitely appreciate it.         
-//(written by Michal Matyska)// +
- +
-You might ask, why the select framework was introduced at all? The main reason +
-was that everytime you wanted to check any part (header, etc.) of the +
-incomming message you had to write new module/new function which did that. +
-Moreover this function (due to historic limitations) might get at most two +
-parameters. If you need more you have to use workaround and set attributes +
-which are then checked from this function. So to make the route script more +
-readable and understandable a new element has started to be supported - the +
-select framework. +
- +
-In the script the select is identified by it's unique name. The intention is +
-to make the identifier as much understandable as possible, so e.g. if you see +
-''@to.uri.user'' it is quite obvious, that you'd get the username from the uri +
-present in the "To" header. Wherever you see the select identifier in the +
-script, it is actually its value, which is then used during the route script +
-process. +
- +
-To make the select framework speed efficient, the identifier of the select is +
-parsed and fixed on the SER startup. If it is not valid select identifier, +
-error message is dumped and SER does not start at all.  But then, during the +
-request route script execution, there is just single function call invocation, +
-which gets the parsed select identifier as parameter if it needs it for any +
-purpose. From the performance point of view there is almost no difference +
-between calling specialized function from any module and calling function +
-which represents the select identifier. +
- +
-===== Overview of Operation ===== +
-What we call select is basically unified notation for calling function which +
-is defined as select function either in SER's core or from any module. The +
-identifier starts with at sign and consists of few text elements denoted by +
-dot optionally adding single integer or string parameter enclosed in square +
-brackets. +
- +
-You can use selects in the routing script in the expression evaluation, as +
-right side of attribute assignment and as parameters in some function calls. +
-(This is limited to functions which support this and the parameter is actually +
-text with the select identifier, so it must be enclosed in double quotes.) +
-Xlog formatting also support selects as a element while composing the final +
-value - the formatting element is ''%@select.identtifier.as.usual''. +
- +
-Return value of the select is text string, but be aware, it might be also +
-string with 0 length (empty string) if such value is allowed (e.g.  some uri +
-parameter value) or when select function signalizes that expected value was +
-not found in the header or message parsing encountered syntax error. This kind +
-of error has influence on the conditional expression - if there is problem +
-with the select evaluation, the result is false regardless it matches the +
-empty string. +
- +
-===== Select Identifiers ===== +
-Select identifier starts with at sign (@) followed by at least one (at most +
-30) text elements each separated by dot (.) from the previous one.  The +
-identifier elements are case insensitive, so you can e.g. use letter case to +
-emphasize some of them, but lower case is preferred. Some of the select +
-functions accept parameters (like index of the repetead headers, or the header +
-name or authorization realm) - this parameter is expressed in the identifier +
-by enclosing it with square brackets. The index starts counting from 1 +
-(programmers be aware), because it is more natural and you can also express +
-that you want count the headers in the opposite direction and get the last +
-header (using -1 as the index). +
- +
-Examples of identifiers (syntactically valid): +
-  * ''@the.simplest'' +
-  * ''@another.with!["parameter"]'' +
-  * ''@yet.another![1].parameter![2]'' +
-  * ''@you.can.also.mix.string!["like-this"].and.integer![1].parameters'' +
- +
-===== Nested Selects ===== +
-You might find some repeating patterns in the SIP requests, like that there is +
-URI element present in quite a lot of SIP headers. The select framework has +
-possibility to ease the developers' life reusing the URI parser and select +
-function already included in the core (or parser of parameter values (either +
-header or URI), or any other if you are able to think it off) and apply it on +
-intermediate select result.  This so called nested select (see developers' doc +
-if you are interested) divides the select call to two (or more) separate +
-function calls, where the first one returns the URI text as temporary result, +
-which is then passed to the built-in URI select machinery as the value which +
-should be used for the final result.  E.g. +
-''@hf_value!["X-any-header"].nameaddr.uri.user'' gets the value of X-any-header +
-header, assuming it is conforming to the name-addr RFC specification and +
-passes the header value to the name-addr select-parser, which separates the +
-username from the URI and returns that as the final value of the select. +
- +
-So every of these URIs (select's results) can be passed to URI specialized +
-select, which makes individual URI parts accessible. +
- +
-  @request_uri, @dst_uri, @next_hop, @from.uri, @to.uri, @refer_to.uri, +
-  @rpid.uri, @contact.uri, @record_route.uri or +
-  @hf_value!["any-header"].nameaddr.uri - all these return appropriate URI. +
- +
-Now if you want just the username, append .user to the select identifier and +
-you get the username. The .user identifier part is everytime same regardless +
-which URI was selected in the first step. +
- +
-Here is the list of all URI's nested select identifiers: +
-   * ''type'': returns the URI type in normalized (lowercase) text sip, sips, tel, tels +
-   * ''user'' +
-   * ''pwd'' +
-   * ''host'' +
-   * ''port'': all above is selfexplaining +
- +
-   * ''transport'': returns the transport parameter value if present, otherwise the default transport used based on the URI type. +
-   * ''hostport'': returns the host:port value from the URI. If the port is not present, the default value based on the URI type is used. +
-   * ''params'': the whole parameters part of URI like user=phone;phone-context=+1234 +
-   * ''params!["parameter-name"]'': just the value of the specified parameter +
- +
-===== Selects in Expressions ===== +
-You can use the select in the conditional expressions like these: +
- +
-  * ''if (@select.value) {...}'' +
- +
-the test is true, when the select returns NON-EMPTY string. +
- +
-  * ''if (@select.value=="string") {...}'' +
-  * ''if ("string"==@select.value) {...}'' +
- +
-the result is true, when the select is error-free and its return value. +
-Instead of constant value, you can also use values from $attribute or +
-@yet.another.select +
- +
-  * ''if (@select.value!="string") {...}'' +
-  * ''if ("string"!=@select.value) {...}'' +
- +
-in this case the test checks whether the two strings are different. If +
-there is error during the select evaluation, the result is also false. +
- +
- * ''if (@select.value=~"reg.*expr.?") {...}'' +
- +
-true, when the string returned by select function matches the regular +
-expression. In this case swapping of the left and right values matter, so +
- +
- * ''if ("string"=~@select.value) {...}'' +
- +
-is true when the "string" matches the regular expression, which is +
-obtained as select's return value. This is what you usually don't want. +
- +
-You can also use the select as the right hand value of the attribute +
-assignment. A new string-type attribute is created and the result value of +
-the select function call is assigned to this attribute. +
- +
-  * ''$attribute=@the.select.you.want'' +
- +
-===== Selects in Parameters ===== +
-Some functions allow to pass the select's return value as parameter. The +
-function must support that, so it is not possible for every function. The +
-parameter holds the select identifier and the function is responsible to +
-resolve and fixup the indetifier at SER startup and then call the select +
-function to obtain the return value. +
- +
-If the select's evaluation has stopped with error, then the return value of +
-the function is false and the rest of the function's code is typically skipped +
-over. +
- +
-===== System Selects ===== +
-As the select framework has begun to show its strength, new ideas whatever +
-else could be accessible using select call has emerged. The example of that +
-are system selects which's identifiers begin with @sys like: +
- +
- * ''@sys.pid'' +
-   returns string representation of current process # +
- * ''@sys.now'' +
-   unix timestamp or +
- * ''@sys.utc'' +
-   UTC timestamp if you use different time zones +
- * ''@sys.unique'' +
-   generates and returns random UUID (type 2) +
- +
-===== Selects in Modules ===== +
-As you can see, the select framework is very powerfull tool, which can be +
-easily extended using the SER's modules concept. E.g. the TLS module, there is +
-lot of TLS information you can get/check in the script, but only when the TLS +
-module is used. So all the TLS related selects are part of the TLS module... +
-if you use the module, then they are available, if you don't use the module, +
-they are not and SER will complain about the wrong select identifier and +
-decline to start. +
- +
-On the other hand, there is no difference between the module's selects and +
-core's selects, so you don't really need to care where is the source of the +
-select, just make sure you have loaded all neccessary modules. +

Trace:

Navigation

Wiki

Other

QR Code
QR Code ref_manual:selects (generated for current page)