Differences

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

--- cookbooks:devel:pseudovariables [2017/02/27 18:13]
coudot $env() class
+++ cookbooks:devel:pseudovariables [2019/11/29 01:22] (current)
jih
@@ Line 1: / Line 1: @@
 {{ :cookbooks:devel:pseudovariables.png?200|}}
-====== Kamailio SIP Server v5.1.x (devel): Pseudo-Variables ======
+====== Kamailio SIP Server v5.4.x (devel): Pseudo-Variables ======
 ===== Introduction =====
@@ Line 20: / Line 20: @@
   * avpops
   * htable
+  * http_async_client
   * textops
   * uac
@@ Line 76: / Line 77: @@
 **$aU** - whole username from Authorization or Proxy-Authorization header
-==== $Au - Acc username ====
+==== $Au - Acc username and realm/domain ====
-**$Au** - username for accounting purposes. It's a selective pseudo variable (inherited from acc module). It returns $au if exits or From username otherwise.
+**$Au** - username for accounting purposes. It's a selective pseudo variable (inherited from acc module). It returns the auth username and realm ($au@$ar) if exists or From URI ($fu) otherwise.
+==== $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 ====
@@ 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.
-==== $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 ====
@@ Line 222: / Line 228: @@
 If loose_route() returns TRUE a destination uri is set according to the first Route header.
-$du is also set if lookup() function of 'registrar' module finds contact(s) behind NAT. You can
+$du is also set if lookup() function of 'registrar' module finds contact(s) behind NAT or
-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.
    sip:kamailio.org
    sip:pbx123.kamailio.org;transport=udp
@@ Line 275: / Line 282: @@
 **$mb** - reference to SIP message buffer
+==== $mbu - updated SIP message buffer ====
+**$mbu** - reference to updated SIP message buffer, after applying changes
 ==== $mf - Flags ====
@@ Line 333: / Line 344: @@
 **$pp** - reference to process id (pid)
-==== $pr - Protocol of received message ====
+==== $pr or $proto - Protocol of received message ====
 **$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 ====
@@ Line 433: / Line 456: @@
 <fc #0000ff>It is R/W variable (you can assign values to it directly in configuration file)</fc>
+==== $rv - SIP message version ====
+**$rv** - reference to SIP message (reply or request) version
 ==== $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
+==== $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** - reference to IP address of the interface where the request has been received
 ==== $Rp - Received port ====
 **$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:address:port).
 ==== $sbranch(attr) - Static Branch ====
@@ Line 476: / Line 528: @@
 ==== $si - Source IP address ====
-**$si** - reference to IP source address of the message
+**$si** - reference to IP source address of the message - see also $siz
+==== $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 ====
@@ Line 502: / Line 561: @@
 ==== $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:
@@ Line 567: / Line 626: @@
 **$ua** - reference to user agent header field
+==== $version() - version ====
+**$version(num)** - version as number
+**$version(full)** - full version string "name version architecture/platform"
+**$version(hash)** - TBA
 ===== $env(NAME) - environment variables =====
@@ Line 695: / Line 762: @@
 **$(hdr(name)[N])** - represents the body of the N-th header identified by 'name'.
-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='*', all headers of that type are printed.
+If [N] is omitted then the body of the first header is printed. The body of first header is returned 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='*', all headers of that type are printed.
+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.
@@ Line 708: / Line 777: @@
 <fc #0000ff>It is read-only variable. You can remove or add headers using functions from textops module.</fc>
+===== $hdrc(name) - Number of Headers =====
+**$hdrc(name)** - get the number of headers with the respective name
+Example of usage:
+<code c>
+if($hdrc(Via) == 2) {
+...
+}
+</code>
 ===== $var(name) - Private memory variables (zero) =====
@@ Line 760: / Line 841: @@
 ===== $shv(name) - Shared memory variables =====
-**$shv(name)**  - it is a class of pseudo-variables stored in shared memory. The value of $shv(name) is visible across all Kamailio processes. Each “shv” has single value and it is initialised to integer 0. You can use “shvset” parameter of **pv module** to initialize the shared variable. The module exports a set of MI functions to get/set the value of shared variables.
+**$shv(name)**  - it is a class of pseudo-variables stored in shared memory. The value of $shv(name) is visible across all Kamailio processes. Each “shv” has single value and it is initialised to integer 0. You can use “shvset” parameter of **pv module** to initialize the shared variable. The module exports a set of RPC functions to get/set the value of shared variables.
 Example - shv(name) pseudo-variable usage:
@@ Line 776: / Line 857: @@
 <fc #0000ff>It is R/W variable (you can assign values to it directly in configuration file)</fc>
+===== $dsv(key) - Dispatcher variables =====
+Return attributes related to dispatcher module.
+The key can be:
+  * code - the SIP response code that caused the execution of event_route 'dispatcher:dst-up' or 'dispatcher:dst-down', if available
+  * reason - the SIP response reason that caused the execution of event_route 'dispatcher:dst-up' or 'dispatcher:dst-down', if available
+  * flags - flags set internally when executing event_route 'dispatcher:dst-up' or 'dispatcher:dst-down'
 ===== $time(name) - Broken-down time =====
@@ Line 842: / Line 932: @@
 }
 </code>
-===== Send Address Attributes =====
+===== Received Data Attributes =====
+==== $rcv(key) ====
+Attributes of received data. The variables must be used inside **event_route[core:msg-received]** routing block.
+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:msg-received] {
+  xlog("rcv on $rcv(af)/$rcv(proto): ($rcv(len)) [$rcv(buf)] from [$rcv(srcip):$rcv(srcport)] to [$rcv(rcvip):$rcv(rcvport)]\n");
+}
+</code>
+===== Send Data Attributes =====
 ==== $sndfrom(name) ====
@@ Line 861: / Line 977: @@
   * af - address family to be used to send (numeric)
   * port - port of destination address
-  * proto - transport protocol to be used to send (numeric)
+  * proto - transport protocol to be used to send (numeric - UDP=1, TCP=2, TLS=3, SCTP=4, WS=5, WSS=6)
   * sproto - transport protocol to be used to send (string)
   * buf - entire send buffer as string
@@ Line 1015: / Line 1131: @@
 Access hash table entries.
-<fc #0000ff>It is R/W variable, you can assign values to it directly in configuration file.  Hash table entry can be deleted by assigning value $null to it.</fc>
+<fc #0000ff>It is R/W variable, you can assign values to it directly in configuration file.  Hash table entry can be deleted by assigning value $null to it.  Value of a non-existing hash table entry is $null.</fc>
 The “htname” must be a hash table name defined via “htable” parameter.
@@ Line 1238: / Line 1354: @@
 ...
 </code>
+===== 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/modifies/removes a HTTP header. N.B.: setting this variable multiple times will add several headers to the query.
+  * body: sets/modifies/removes the request body
+  * method: sets the HTTP method: either "GET", "POST", "PUT" or "DELETE" (these are the supported methods). (Note: if the method is not set, curl will use GET, or POST if a body is specified)
+  * 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: sets the client certificate to use
+  * tls_client_key: sets the client certificate key to use
+  * tls_ca_path: sets the CA certificate path to use
+  * 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't suspend the current transaction before performing the query
+  * tcp_keepalive: enable TCP keepalive
+  * tcp_ka_idle: set TCP keepalive idle time wait
+  * tcp_ka_interval: set TCP keepalive 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 ===
+if cURL executed the request successfully, 0 otherwise (check $http_err for details).
+=== $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 =====
@@ Line 1322: / Line 1496: @@
 The **name** can be:
-  * id_index - return the internal index of current transaction
+  * id_index - return the internal index of current transaction or $null if not transaction is found
-  * id_label - return the internal label of current transaction
+  * id_label - return the internal label of current transaction or $null if not transaction is found
-  * reply_code - alias to $T_reply_code
+  * id_index_n - return the internal index of current transaction, if no transaction exists yet, create it
-  * branch_index - alias to $T_branch_idx
+  * id_label_n - return the internal label of current transaction, if no transaction exists yet, create it
+  * 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
   * reply_type - 1 if it is a local generated reply, 0 - if no reply for transaction or it is a received reply
@@ Line 1413: / Line 1591: @@
 ==== $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(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 =====
@@ Line 1433: / Line 1610: @@
   * $nh(P) - transport protocol (upper case p)
-===== GeoIP module Pseudo-Variables =====
+===== NDB_REDIS Module =====
+==== $redis(res=>key) ====
+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), the members of the array can be accessed by adding any of the above keys, after a value[n] key. The first value[n] references the element in the first array, while the next key references an element of the referenced array.
+Example:
+<code>
+redis_cmd("srvN", "GET foo", "r");
+xlog("===== result type: $redis(r=>type) * value: $redis(r=>value)\n");
+</code>
+==== $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=>type).
+Example:
+<code>
+redis_cmd("srvN", "GET foo", "r");
+if ($redis(r=>type) == $redisd(rpl_int)) {
+}
+</code>
+===== GeoIP Module =====
 ==== $gip(pvc=>key) ====
@@ Line 1538: / Line 1767: @@
 ==== $tls_peer_subject_unit ====
 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 ====
 organizationalUnitName in the issuer section of the certificate. String type.
 ==== $tls_my_subject_unit ====
 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 ====
 organizationalUnitName in the issuer section of the certificate. String type.
@@ Line 1800: / Line 2033: @@
 The key can be:
- * line - return current line in config
+  * line - return the 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:
@@ Line 1871: / Line 2106: @@
 </code>
-===== JSONRPC-S Variables =====
+===== JSONRPCS Variables =====
 ==== $jsonrpl(key) - JSONRPC Reply ====
@@ Line 1890: / Line 2125: @@
 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.
-===== $C(xy) - Foreground and background colors =====
+===== Registrar Module Pseudo-Variables =====
+==== $ulc(profile=>attr) - Registered Contact Attributes ====
+Access the attributes of contact addresses stored in 'profile'.
+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=>key) - Phonenum Variables =====
+$phn(rid=>key) - rid is an identifier for this query result; it is designated by the second parameter of phonenum_match(). The key can be one of the following:
+  * 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("1-484-555-8888", "src")) {
+    if($phn(src=>valid)==1) {
+        xlog("number normalized to: $phn(src=>normalized)\n");
+    } else {
+        xlog("number normalization error: $phn(src=>error)\n");
+    }
+}
+</code>
+===== 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/failure route, otherwise it returns $null)
+  * $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.

Kamailio SIP Server Wiki

User Tools

Site Tools

Differences

Page Tools