This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
cookbooks:devel:pseudovariables [2017/03/29 12:46] miconda [$hdr(name) - Headers] |
cookbooks:devel:pseudovariables [2019/11/15 15:21] giavac |
||
---|---|---|---|
Line 1: | Line 1: | ||
{{ : | {{ : | ||
- | ====== Kamailio SIP Server v5.1.x (devel): Pseudo-Variables ====== | + | ====== Kamailio SIP Server v5.4.x (devel): Pseudo-Variables ====== |
===== Introduction ===== | ===== Introduction ===== | ||
Line 20: | Line 20: | ||
* avpops | * avpops | ||
* htable | * htable | ||
+ | * http_async_client | ||
* textops | * textops | ||
* uac | * uac | ||
Line 76: | Line 77: | ||
**$aU** - whole username from Authorization or Proxy-Authorization header | **$aU** - whole username from Authorization or Proxy-Authorization header | ||
- | ==== $Au - Acc username ==== | + | ==== $Au - Acc username |
- | **$Au** - username for accounting purposes. It's a selective pseudo variable (inherited from acc module). It returns auth username ($au) if exists or From username | + | **$Au** - username for accounting purposes. It's a selective pseudo variable (inherited from acc module). It returns |
+ | ==== $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 exists or From user ($fU) otherwise. | ||
==== $branch(name) - Branch attributes ==== | ==== $branch(name) - Branch attributes ==== | ||
Line 170: | Line 173: | ||
**$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. | **$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 ==== | + | ==== $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). | + | **$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 - Contact header ==== | ||
Line 222: | Line 228: | ||
If loose_route() returns TRUE a destination uri is set according to the first Route header. | If loose_route() returns TRUE a destination uri is set according to the first Route header. | ||
- | $du is also set if lookup() function of ' | + | $du is also set if lookup() function of ' |
- | set $du to any SIP URI. | + | 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. | ||
| | ||
| | ||
Line 275: | Line 282: | ||
**$mb** - reference to 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 - Flags ==== | ||
Line 333: | Line 344: | ||
**$pp** - reference to process id (pid) | **$pp** - reference to process id (pid) | ||
- | ==== $pr - Protocol of received message ==== | + | ==== $pr or $proto |
**$pr** or **$proto** - protocol of received message (udp, tcp, tls, sctp, ws, wss) | **$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 - User in P-Preferred-Identity header URI ==== | ||
Line 433: | Line 456: | ||
<fc # | <fc # | ||
+ | ==== $rv - SIP message version ==== | ||
+ | |||
+ | **$rv** - reference to SIP message (reply or request) version | ||
==== $ruid - Record internal Unique ID ==== | ==== $ruid - Record internal Unique ID ==== | ||
Line 440: | Line 466: | ||
**$rz** - returns R-URI scheme, possible values: sip, sips, tel, tels and urn, R-URI scheme parsing error should be reflected by value: none | **$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 - Received IP address ==== | ||
**$Ri** - reference to IP address of the interface where the request has been received | **$Ri** - reference to IP address of the interface where the request has been received | ||
- | |||
==== $Rp - Received port ==== | ==== $Rp - Received port ==== | ||
**$Rp** - reference to the port where the message was received | **$Rp** - reference to the port 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: | ||
==== $sbranch(attr) - Static Branch ==== | ==== $sbranch(attr) - Static Branch ==== | ||
Line 476: | Line 528: | ||
==== $si - Source IP address ==== | ==== $si - Source IP address ==== | ||
- | **$si** - reference to IP source address of the message | + | **$si** - reference to IP source address of the message |
+ | |||
+ | ==== $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 - Source port ==== | ||
Line 502: | Line 561: | ||
==== $sut - Source address as full URI ==== | ==== $sut - Source address as full URI ==== | ||
- | **$su** - returns the representation of source address (ip, port, proto) as full SIP URI. The proto UDP is added also as transport parameter. | + | **$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: | Its value looks like: | ||
Line 567: | Line 626: | ||
**$ua** - reference to user agent header field | **$ua** - reference to user agent header field | ||
+ | |||
+ | ==== $version() - version ==== | ||
+ | |||
+ | **$version(num)** - version as number | ||
+ | |||
+ | **$version(full)** - full version string "name version architecture/ | ||
+ | |||
+ | **$version(hash)** - TBA | ||
===== $env(NAME) - environment variables ===== | ===== $env(NAME) - environment variables ===== | ||
Line 695: | Line 762: | ||
**$(hdr(name)[N])** - represents the body of the N-th header identified by ' | **$(hdr(name)[N])** - represents the body of the N-th header identified by ' | ||
- | If [N] is omitted then the body of the first header is printed. The first header is got when N=0, for the second N=1, a.s.o. In case of a comma-separated multi-body headers, it returns all the bodies, comma-separated. To print the last header of that type, use -1, or other negative values to count from the end. No white spaces are allowed inside the specifier (before }, before or after {, [, ] symbols). When N=' | + | If [N] is omitted then the body of the first header is printed. The body of first header is returned |
+ | |||
+ | If name is *, then any header name is matched, e.g., $hdr(*) is body of first header, $(hdr(*)[-1]) is body of last header. | ||
The module should identify compact header names. It is recommended to use dedicated specifiers for headers (e.g., $ua for user agent header), if they are available -- they are faster. | The module should identify compact header names. It is recommended to use dedicated specifiers for headers (e.g., $ua for user agent header), if they are available -- they are faster. | ||
Line 772: | Line 841: | ||
===== $shv(name) - Shared memory variables ===== | ===== $shv(name) - Shared memory variables ===== | ||
- | **$shv(name)** | + | **$shv(name)** |
Example - shv(name) pseudo-variable usage: | Example - shv(name) pseudo-variable usage: | ||
Line 854: | Line 923: | ||
} | } | ||
</ | </ | ||
- | ===== Send Address | + | ===== Received Data Attributes ===== |
+ | |||
+ | ==== $rcv(key) ==== | ||
+ | |||
+ | Attributes of received data. The variables must be used inside **event_route[core: | ||
+ | |||
+ | The key can be: | ||
+ | |||
+ | * buf - received message | ||
+ | * len - lenght of received message | ||
+ | * srcip - source ip | ||
+ | * rcvip - local ip where it was received | ||
+ | * scrport - source port | ||
+ | * rcvport - local port where it was received | ||
+ | * proto - protocol as int id | ||
+ | * sproto - protocol as string | ||
+ | * af - address family | ||
+ | |||
+ | Example of usage: | ||
+ | |||
+ | <code c> | ||
+ | event_route[core: | ||
+ | xlog(" | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | ===== Send Data Attributes ===== | ||
==== $sndfrom(name) ==== | ==== $sndfrom(name) ==== | ||
Line 873: | Line 968: | ||
* af - address family to be used to send (numeric) | * af - address family to be used to send (numeric) | ||
* port - port of destination address | * port - port of destination address | ||
- | * proto - transport protocol to be used to send (numeric) | + | * proto - transport protocol to be used to send (numeric |
* sproto - transport protocol to be used to send (string) | * sproto - transport protocol to be used to send (string) | ||
* buf - entire send buffer as string | * buf - entire send buffer as string | ||
Line 1250: | Line 1345: | ||
... | ... | ||
</ | </ | ||
+ | |||
+ | ===== http_async_client module Pseudo-Variables ===== | ||
+ | |||
+ | ==== $http_req_id ==== | ||
+ | |||
+ | The $http_req_id read-only variable can be used in REQUEST_ROUTE to retrive the unique identifier for a query after sending it or in the HTTP callback route to retrive the id of the query the reply belongs to. Useful mainly in non-transactional context. | ||
+ | |||
+ | ==== $http_req(key) ==== | ||
+ | |||
+ | The $http_req(key) write-only variable can be used to set custom parameters before sending a HTTP query. | ||
+ | |||
+ | **key** can be one of: | ||
+ | * all: if set to $null, resets all the parameters to their default value (the ones defined in modparam) | ||
+ | * hdr: sets/ | ||
+ | * body: sets/ | ||
+ | * method: sets the HTTP method: either " | ||
+ | * timeout: sets the HTTP timeout. (Note, this timeout should be normally less than tm.fr_timer timeout, because transaction timeout has a higher priority over HTTP timeout) | ||
+ | * tls_client_cert: | ||
+ | * tls_client_key: | ||
+ | * tls_ca_path: | ||
+ | * authmethod: Sets the preferred authentication mode for HTTP/HTTPS requests. The value is a bitmap and multiple methods can be used. Note that in this case, the CURL library will make an extra request to discover server-supported authentication methods. You may want to use a specific value. Valid values are: | ||
+ | * 1 - BASIC authentication | ||
+ | * 2 - HTTP Digest authentication | ||
+ | * 4 - GSS-Negotiate authentication | ||
+ | * 8 - NTLM authentication | ||
+ | * 16 - HTTP Digest with IE flavour. | ||
+ | * (Default value is 3 - BASIC and Digest authentication.) | ||
+ | * username: sets the username to use for authenticated requests | ||
+ | * password: sets the password to use for authenticated requests | ||
+ | * suspend: if set to 0 it doesn' | ||
+ | * tcp_keepalive: | ||
+ | * tcp_ka_idle: | ||
+ | * tcp_ka_interval: | ||
+ | |||
+ | ==== Other read-only variables ==== | ||
+ | |||
+ | The following read-only pseudo variables can only be used in the callback routes executed by http_async_query() | ||
+ | |||
+ | === $http_ok === | ||
+ | 1 if cURL executed the request successfully, | ||
+ | |||
+ | === $http_err === | ||
+ | cURL error string if an error occurred, $null otherwise. | ||
+ | |||
+ | === $http_rs === | ||
+ | HTTP status. | ||
+ | |||
+ | === $http_rr === | ||
+ | HTTP reason phrase. | ||
+ | |||
+ | === $http_hdr(Name) === | ||
+ | Value of the Name header (the $(http_hdr(Name)[N]) syntax can also be used, check the SIP $hdr() PV documentation for details). | ||
+ | |||
+ | === $http_mb and $http_ml === | ||
+ | HTTP response buffer (including headers) and length. | ||
+ | |||
+ | === $http_rb and $http_bs === | ||
+ | HTTP response body and body length, | ||
===== XMLOPS Pseudo-Variables ===== | ===== XMLOPS Pseudo-Variables ===== | ||
Line 1334: | Line 1487: | ||
The **name** can be: | The **name** can be: | ||
- | * id_index - return the internal index of current transaction | + | * id_index - return the internal index of current transaction |
- | * id_label - return the internal label of current transaction | + | * id_label - return the internal label of current transaction |
- | * reply_code - alias to $T_reply_code | + | * id_index_n - return the internal index of current transaction, |
- | * branch_index - alias to $T_branch_idx | + | * id_label_n - return the internal label of current transaction, |
+ | * reply_code - reply code (alias to $T_reply_code) | ||
+ | * reply_reason - reply reason | ||
+ | * reply_last - last received reply code | ||
+ | * branch_index - branch index (alias to $T_branch_idx) | ||
* ruid - return the internal location ruid field for current branch | * ruid - return the internal location ruid field for current branch | ||
* reply_type - 1 if it is a local generated reply, 0 - if no reply for transaction or it is a received reply | * reply_type - 1 if it is a local generated reply, 0 - if no reply for transaction or it is a received reply | ||
Line 1425: | Line 1582: | ||
==== $TV(name) ==== | ==== $TV(name) ==== | ||
- | Seconds and microseconds taken from struct timeval. | + | Seconds and microseconds taken from struct timeval. The time at that moment is represented by **seconds.microseconds**. |
* $TV(s) - seconds (cached at first call per sip message) | * $TV(s) - seconds (cached at first call per sip message) | ||
* $TV(u) - microseconds (cached at first call per sip message) | * $TV(u) - microseconds (cached at first call per sip message) | ||
- | * $TV(sn) - seconds (not cached) | + | * $TV(sn) - seconds (not cached, taken at that moment) |
- | * $TV(un) - microseconds (not cached) | + | * $TV(un) - microseconds (corresponding to the moment $TV(sn) is retrieved) |
- | * $TV(Sn) - string representation seconds.microseconds (not cached) | + | * $TV(Sn) - string representation seconds.microseconds (not cached, taken at that moment) |
===== Next hop address ===== | ===== Next hop address ===== | ||
Line 1445: | Line 1601: | ||
* $nh(P) - transport protocol (upper case p) | * $nh(P) - transport protocol (upper case p) | ||
- | ===== GeoIP module Pseudo-Variables | + | ===== NDB_REDIS Module ===== |
+ | |||
+ | ==== $redis(res=> | ||
+ | |||
+ | Access the attributes of the Redis response. | ||
+ | |||
+ | The key can be: | ||
+ | |||
+ | * type - type of the reply (as in hiredis.h) | ||
+ | * value - the value returned by REDIS server; | ||
+ | * info - in case of error from REDIS, it will contain an info message. | ||
+ | |||
+ | If reply type is an array (as in hiredis.h), there are other keys available: | ||
+ | |||
+ | * size - returns number of elements in the array. | ||
+ | |||
+ | * type[n] - returns the type of the nth element in the array. type - returns array type. | ||
+ | |||
+ | * value[n] - returns value of the nth element. value - returns null for an array. You need to get each element by index. | ||
+ | |||
+ | In case one of the members of the array is also an array (for example calling SMEMBERS in a MULTI/EXEC transaction), | ||
+ | |||
+ | Example: | ||
+ | |||
+ | < | ||
+ | redis_cmd(" | ||
+ | xlog(" | ||
+ | </ | ||
+ | |||
+ | ==== $redisd(key) ==== | ||
+ | |||
+ | Return the corresponding value for various defines from hiredis library. | ||
+ | |||
+ | The key can be: | ||
+ | |||
+ | * rpl_str - return REDIS_REPLY_STRING | ||
+ | * rpl_arr - return REDIS_REPLY_ARRAY | ||
+ | * rpl_int - return REDIS_REPLY_INTEGER | ||
+ | * rpl_nil - return REDIS_REPLY_NIL | ||
+ | * rpl_sts - return REDIS_REPLY_STATUS | ||
+ | * rpl_err - return REDIS_REPLY_ERROR | ||
+ | |||
+ | $redisd(rpl_XYZ) can be compared with $redis(r=> | ||
+ | |||
+ | Example: | ||
+ | |||
+ | < | ||
+ | redis_cmd(" | ||
+ | if ($redis(r=> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | ===== GeoIP Module | ||
==== $gip(pvc=> | ==== $gip(pvc=> | ||
Line 1550: | Line 1758: | ||
==== $tls_peer_subject_unit ==== | ==== $tls_peer_subject_unit ==== | ||
organizationalUnitName in the subject section of the certificate. String type. | organizationalUnitName in the subject section of the certificate. String type. | ||
+ | ==== $tls_peer_subject_uid ==== | ||
+ | UID in the subject section of the certificate. String type. | ||
==== $tls_peer_issuer_unit ==== | ==== $tls_peer_issuer_unit ==== | ||
organizationalUnitName in the issuer section of the certificate. String type. | organizationalUnitName in the issuer section of the certificate. String type. | ||
==== $tls_my_subject_unit ==== | ==== $tls_my_subject_unit ==== | ||
organizationalUnitName in the subject section of the certificate. String type. | organizationalUnitName in the subject section of the certificate. String type. | ||
+ | ==== $tls_my_subject_uid ==== | ||
+ | UID in the subject section of the certificate. String type. | ||
==== $tls_my_issuer_unit ==== | ==== $tls_my_issuer_unit ==== | ||
organizationalUnitName in the issuer section of the certificate. String type. | organizationalUnitName in the issuer section of the certificate. String type. | ||
Line 1812: | Line 2024: | ||
The key can be: | The key can be: | ||
- | * line - return current line in config | + | |
- | * name - return the name of current config file | + | * name - return the name of current config file |
+ | * file - return the name of current config file | ||
+ | * route - return the name of routing block | ||
Example: | Example: | ||
Line 1883: | Line 2097: | ||
</ | </ | ||
- | ===== JSONRPC-S | + | ===== JSONRPCS |
==== $jsonrpl(key) - JSONRPC Reply ==== | ==== $jsonrpl(key) - JSONRPC Reply ==== | ||
Line 1902: | Line 2116: | ||
The key can be: | The key can be: | ||
* uri - subscription URI. Useful in particular for subscriptions within the dialog, when the request URI in SUBSCRIBE is the Contact address from the initial subscription. | * uri - subscription URI. Useful in particular for subscriptions within the dialog, when the request URI in SUBSCRIBE is the Contact address from the initial subscription. | ||
- | ===== $C(xy) - Foreground and background colors ===== | ||
+ | ===== Registrar Module Pseudo-Variables ===== | ||
+ | |||
+ | ==== $ulc(profile=> | ||
+ | |||
+ | Access the attributes of contact addresses stored in ' | ||
+ | |||
+ | It must be used after a call of “reg_fetch_contacts()”. | ||
+ | |||
+ | ===== sipcapture Module Pseudo-Variables ===== | ||
+ | |||
+ | ==== $hep(key) - HEP Packet Attributes ==== | ||
+ | |||
+ | The key refers to HEP packet header values: | ||
+ | |||
+ | * version - HEP version | ||
+ | * src_ip - source IP address | ||
+ | * dst_ip - destination IP address | ||
+ | * 0x000 - HEP attribute 0x000 | ||
+ | * 0x999 - HEP attribute 0x999 | ||
+ | |||
+ | ===== $phn(rid=> | ||
+ | |||
+ | $phn(rid=> | ||
+ | |||
+ | * number - phone number that is matched | ||
+ | * valid - 1 if the matched number has a valid result; 0 otherwise | ||
+ | * normalized - normalized phone number | ||
+ | * cctel - country code for phone number | ||
+ | * ltype - local network type | ||
+ | * ndesc - phone number description | ||
+ | * error - error string if phone number matching fails. | ||
+ | |||
+ | <code c> | ||
+ | if(phonenum_match(" | ||
+ | if($phn(src=> | ||
+ | xlog(" | ||
+ | } else { | ||
+ | xlog(" | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | |||
+ | ===== sdpops module variables ===== | ||
+ | |||
+ | * $sdp(body) - full SDP body (read only) | ||
+ | * $sdp(sess_version) - sess-version -attribute from SDP o= -line. When set to special value -1, current value is incremented. (read + write) | ||
+ | |||
+ | ===== $sruid - Unique ID ===== | ||
+ | |||
+ | * $sruid - return unique ID generated internally Kamailio | ||
+ | |||
+ | ===== $ltt(key) - Local To-Tag ===== | ||
+ | |||
+ | $ltt(key) - return local generated To-tag when Kamailio sends a reply | ||
+ | |||
+ | * $ltt(s) - the to-tag used in stateless replies | ||
+ | * $ltt(t) - the to-tag used in transaction stateful replies (transaction has to be created at that time, eg., by t_newtran() or in a branch/ | ||
+ | * $ltt(x) - $ltt(t) if the transaction was created already, otherwise $ltt(s) | ||
+ | |||
+ | ===== tcpops module variable ===== | ||
+ | |||
+ | $tcp(key) - return TCP connection attributes. | ||
+ | |||
+ | The key can be: | ||
+ | * c_si - connection source ip (useful with HAProxy connections) | ||
+ | * c_sp - connection source port (useful with HAProxy connections) | ||
+ | * conid - connection id | ||
+ | |||
+ | ===== $C(xy) - Foreground and background colors ===== | ||
$C(xy) - reference to an escape sequence. “x” represents the foreground color and “y” represents the background color. | $C(xy) - reference to an escape sequence. “x” represents the foreground color and “y” represents the background color. |