Variáveis Core

O OpenSIPS prove varios tipos de variaveis para serem usados no script de roteamento, as diferenças entre os tipos de variaveis são:

• 1. A visibilidade da variavel
• 2. Onde a variavel é relacionada (onde a mesma reside)
• 3. Status read-write da variavel ( algumas variaveis são apenas de leitura)
• 4. Como multiplos valores (da mesma variavel) são manipulados.

As variáveis do OpenSIPS podem facilmente ser identificadas no script apartir de seus nomes (ou nota'ões) iniciando com o simbolo $

Sintaxe:

A sintaxe completa de uma pseudo-variavel é:

$(<context>name(subname)[index]{transformation})

Os campos context, subname, index e transformation são opcionais

Os campos significam:

• name - o nome(tipo) da pseudo variavel.

Ex: pvar, avp, ru, DLG_status etc...

• subname - o identificador de um certo tipo de variável.

Ex: hdr(From), avp(nome)

• index - uma pv pode armazenar mais de um valor, isso pode ser referenciado a uma lista de valores, você pode acessar um certo valor de uma lista se você especificar o index, você também pode especificar indexe's negativos , -1 significa o ultimo inserido e -2 significa o valor anterior ao ultimo (penultimo).

• transformation - uma série de processos que podem ser aplicados em pseudo-variaveis, você pode encontrar a lista completa em Transformações , as transformações podem ser cascateadas usango a saída de uma tranformação como entrada de outra.

• context - o contexto onde a pseudo-variavel será verificada, atualmente existem dois contextos, reply e request, o contexto de reply pode ser usado na rota de falha para verificar o valor da pseudovariavel neste contexto , o contexto de request (requisição) pode ser usado quando em um contexto de reply é desejado a verificação do valor no contexto correspondente ao request.

Exemplo de uso:

• Apenas name: $ru
• Name e subname: $hdr(Contact)
• Name e index: $(ct[0])
• Name, subname e index: $(avp(i:10)[2])
• Context
  • $(<request>ru) de uma rota reply irá receber a Request-URI da requisição
  • $(<reply>hdr(contact)) , contexto pode ser utilizado em uma rota de falha para acessar as informações do reply.

Tipos de variáveis

script variables

• Como o nome diz, estas variáveis são estritamente utilizadas em rotas de script, estas variáveis são visiveis apenas nos blocos de roteamento, não existem mensagem ou transações relacionas, mas são processos relacionados (variaveis de script são dependentes de rotas executadas pelo mesmo processo do OpenSIPS).

Variáveis de scripts são de leitura e escrita e podem ter valores inteiros ou strings, uma variável de script pode ter apenas um valor, uma nova atribuição (ou escrita) irá sobrescrever os valores existentes.

AVP - Atribute Value Pair

• As avp's são variaveis dinamicas que podem ser criadas, as avp's são linkadas para uma mensagem singular ou uma transação ( se processamento stateful está em uso), uma mensagem ou transação irá inicialmente (quando recebida ou criada) ter uma lista vazia de avp's atreladas, durante o processo de roteamento o script diretamente ou via função poderá criar novos AVP's que automaticamente serão atrelados a mensagem/transação, as avp's serão visiveis em todas as rotas onde qualquer mensagem (reply ou request) da transação seja processada, branch_route, filure_route, onreply_route ( para onreply_route voce deve ter ativado o parametro onreply_avp_mode).

AVP's são variáveis de leitura e escrita e uma AVP existente pode ser deletada (removida), uma AVP pode conter multiplos valores, uma nova atribuição (operação de escrita) irá adicionar o novo valor para a AVP, os valores são mantidos no formado ultimo adicionado é o primeiro a ser utilizado .

pseudo variables

• pseudo-variáveis (ou PV's) provem acesso a informação das mensagens SIP processadas (cabeçalhos, RURI, informações de trnasporte, etc..) ou de informações do OpenSIPS (valores de timers, números de processo (PID), códigos de retorno de função).

Dependendo da informação provida a PV fica presa (relacionada) a um amensagem ou a nada (global), a maior parte das PV's são apenas de leitura, apenas algumas suportam operações de escrita, uma PV pode retornar varios ou apenas um valor dependendo da informação referenciadas (se pode ter valores multiplos ou nao)

PV padrões são apenas de leitura e retornam apenas um valor (se não foi documentado de forma diferente)

escape sequences

• Sequencias de escape são utilizadas para formatar strings, estas não são variaveis mas podem ser formatadas.

Definições

Script Variables

Nominação: **$var(name)**

Dicas:

• Se você quer utilizar uma variavel em uma rota é melhor inicializar ou restar a mesma), de outra forma você poderá ter problemas com valores de rotas anteriores que forão executadas por um mesmo processo.
• Variáveis de script são mais rápidas que AVP's sendo processadas diretamente no endereço de memória.
• O valor de uma variável de script persiste para o processo do OpenSIPS
• Um variável pode ter apenas um valor

1. a script value can have only one value.

Exemplos de uso

$var(a) = 2;  # sets the value of variable 'a' to integer '2'
$var(a) = "2";  # sets the value of variable 'a' to string '2'
$var(a) = 3 + (7&(~2)); # arithmetic and bitwise operation
$var(a) = "sip:" + $au + "@" + $fd; # compose a value from authentication username and From URI domain

# using a script variable for tests
if( [ $var(a) & 4 ] ) {
  xlog("var a has third bit set\n");
}

Definir uma variável para NULL corresponde a iniciar a a mesma com valor '0', variáveis de script não possuem valor NULL.

AVP variables

Nominação: **$avp(name)** ou **$(avp(name)[N])**

Quando utilizado o index 'N' você pode forçar a AVP para retornar um certo valor (valor na posição N), se nenhum index é informado o primeiro valor será o retornado.

Dicas:

• Para ativar AVP's em onreply_route utilize modparam("tm", "onreply_avp_mode", 1)
• Se multiplos valores forem utilizados em uma mesma AVP os valores são indexados em ordem reversa (primeiro inserido é o ultimo da lista)
• AVP's são parte do contexto de transação, desta forma estarão visiveis em todo local que a transação esteja presente.
• O valor de uma AVP pode ser deletado

Exemplo de uso:

Exemplo persistente a transação:

# enable avps in onreply route
modparam("tm", "onreply_avp_mode", 1)
...
route{
...
$avp(tmp) = $Ts ; # store the current time (at request processing)
...
t_onreply("1");
t_relay();
...
}

onreply_route[1] {
	if (t_check_status("200")) {
		# calculate the setup time
		$var(setup_time) = $Ts - $avp(tmp);
	}
}

Exemplo com multiplos valores

$avp(17) = "one";
# we have a single value
$avp(17) = "two";
# we have two values ("two","one")
$avp(17) = "three";
# we have three values ("three","two","one")

xlog("accessing values with no index: $avp(17)\n");
# this will print the first value, which is the last added value -> "three"

xlog("accessing values with no index: $(avp(17)[2])\n");
# this will print the index 2 value (third one), -> "one"

# remove the last value of the avp; if there is only one value, the AVP itself will be destroyed
$avp(17) = NULL;

# delete all values and destroy the AVP
avp_delete("$avp(17)/g");

# delete the value located at a certain index 
$(avp(17)[1]) = NULL;

#overwrite the value at a certain index
$(avp(17)[0]) = "zero";

O módulo AVPOPS prove uma série de funções para operar as AVP's (como checagem de valores, extração em diferentes locais, deleção etc..)

Pseudo Variables

Nominação: $name

Dicas:

• as PV podem ser utilizadas como parametros para diferentes funções e serão substituidas com o valor antes da execução da função
• A maior part edas PV's são disponibilizadas pelo core do OpenSIPS porém existem vários módulos que exportas PV's (para tornar algumas informações especificas do módulo disponivel), verifique as documentações dos módulos para saber mais.

Váriaveis pré-definidas pelo core listadas em ordem alfabética.

URI in SIP Request's P-Asserted-Identity header

$ai - referencia a URI no cabeçalho P-Asserted-Identity (veja RFC 3325 para mais detalhes)

Authentication Digest URI

$adu - URI do cabeçalho Authorization ou Proxy-Authorization, esta URI é utilizada quando calculando a resposta do resposta do HTTP Digest (autenticação).

Authentication realm

$ar - referencia (dominio ou ip) no cabeçalho de Authorization ou Proxy-Authorization

Auth username user

$au - parte referente ao nome do usuário no cabeçalho de Authorization ou Proxy-Authorization

Auth username domain

$ad - parte referente ao dominio do usuário no cabeçalho de Authorization ou Proxy-Authorization

Auth nonce

$an - Hash do cebçalho Authorization ou Proxy-Authorization Nota: na documentação fala nounce, não achei tradução para isso (ex de valor: nonce: 526442e200000000b8d49749e4bdd108e58cd246de209a50)

Auth response

$auth.resp - A resposta da autenticação para um cabeçalho Authorization ou Proxy-Authorization

Auth nonce

$auth.nonce - the nonce string from Authorization or Proxy-Authorization header

Auth opaque

$auth.opaque - the opaque string from Authorization or Proxy-Authorization header

Auth algorithm

$auth.alg - A string referente ao algoritimos utilizado para Authorization ou Proxy-Authorization.

Auth QOP

$auth.qop - O valor do parametro qop (quality of protection) do caebaçalho Authorization ou Proxy-Authorization

Auth nonce count (nc)

$auth.nc - the value of nonce count parameter from Authorization or Proxy-Authorization header

Auth whole username

$aU - Nome do usuário no cabeçalho Authorization or Proxy-Authorization

Acc username

$Au - usuário para proposito de accounting , é uma pseudo variavel seletiva (dependente do modulo acc) , se existir ela retorna seu valor ou retorna o valor do campo From em todo caso

Argument options

$argv - Permite acesso a argumentos de linha de comando especificados com o parametro -o

Exemplo:

  # for option '-o foo=0'
  xlog("foo is $argv(foo) \n");

Branch flags

$bf - Exibe a lista de branch flags definidas para a requisição atual

!!!!Branch flags (hexadecimal) %red%(Removed in OpenSIPS 1.9)%%

Branch

$branch - Esta variavel é utilizada para criação de novas branches (pernas) escrevendo as mesmas no valor da SIP URI Exemplos

  # creates a new branch
  $branch = "sip:new@doamin.org";
  # print its URI
  xlog("last added branch has URI $(branch(uri)[-1]) \n");

Branch fields

$branch() - Esta variavel permite acesso de leitura e escrita para todos os campos/atributos de uma branch existente (previamente criada com append_branch()), os campos da branche são:

• uri - a RURI da branch (string)
• duri - a URI e destino da branch (proxy the saida da branch) (sting)
• q - o valor q da branch (inteiro)
• path - a string PATH desta branch (string)
• flags - as flags para esta branch (inteiro)
• socket - o scoket local para ser utilizado para fazer o relay desta branch (string)

A variavel aceita também index $(branch(uri)[1]) para acessar uma branch especifica (multiplas branches podem ser especificadas autalmente), o index inicia em 0 (primeira branch), se o index for negativo ele é considerado o valor n do fim ( index -1 é ultima branch)

Para todas as branches é utilizado o index * - $(branch(uri)[*]).

Exemplo:

   # creates the first branch
   append_branch();
   # creates the second branch
   force_send_socket(udp:192.168.1.10:5060);
   $du = "sip:192.168.2.10";
   append_branch("sip:foo@bar.com","0.5");

   # display branches
   xlog("----- branch 0: $(branch(uri)[0]) , $(branch(q)[0]), $(branch(duri)[0]), $(branch(path)[0]), $(branch(flags)[0]), $(branch(socket)[0]) \n");
   xlog("----- branch 1: $(branch(uri)[1]) , $(branch(q)[1]), $(branch(duri)[1]), $(branch(path)[1]), $(branch(flags)[1]), $(branch(socket)[1]) \n");

   # do some changes over the branches
   $branch(uri) = "sip:user@domain.ro";   # set URI for the first branch
   $(branch(q)[0]) = 1000;  # set to 1.00 for the first branch
   $(branch(socket)[1]) = NULL;  # reset the socket of the second branch
   $branch(duri) = NULL;  # reset the destination URI or the first branch

Esta é uma variavel de leitura e escrita (você pode definir valores apartir do script de roteamento)

Call-Id

$ci - Referencia para o valor do cabeçalho call-id

Content-Length

$cl - Referencia para o valor do cabeçalho content-length

CSeq number

$cs - Referencia ao valor do cabeçalho cseq

Contact instance

$ct - referencia a 'contact instance/body' do cabeçalho contact, uma contact instance é o display_name + URI + contact_params, como um cabeçalho de contato pode conter multiplos valores e uma mensagem pode conter vários cabeçalhos, um index é adicionado a $ct neste caso:

• $ct -first primeiro 'contact instance' da mensagem
• $(ct[n]) - 'contact instance' na posição n do inicio da mensagem, iniciando com index 0
• $(ct[-n]) - 'contact instance' na posição n apartir do fim da mensagem (iniciando em -1 (ultimo contato)

Fields of a contact instance

A contact instance possue também campos que podem ser acessados

$ct.fields() - referencia os campos da 'contact instance' (veja abaixo)

Campos suportados são:

• name - display name
• uri - contact uri
• q - parametro q (valor apenas)
• expires - parametro expires (valor apenas)
• methods - parametro metodo (valor apenas)
• received - parametro received (valor appenas)
• params - Todos os parametros (incluindo nomes)

Exemplos:

• $ct.fields(uri) - URI da primeira 'contact instance'
• $(ct.fields(name)[1]) - O display nae da segunda 'contact instance'

Content-Type

$cT - Referencia ao cabeçalho content-type

Domain of destination URI

$dd - Referencia do dominio da destination uri

Esta é uma variável de leitura e escrita

Diversion header URI

$di - Referencia ao Diversion header URI

Diversion "privacy" parameter

$dip - Referencia ao parametro 'privacy' do Diversion header

Diversion "reason" parameter

$dir - Referencia ao parametro 'reason' do Diversion header

Port of destination URI

$dp - Referencia a porta da destination URI

Váriavel de leitura e escrita

Transport protocol of destination URI

$dP - referencia ao protocolo de transporte da destination uri

Destination set

$ds - referencia para a destination set

Destination URI

$du - referencia a destination uri (outbound proxy que deve ser utilizado para enviar a requisição), se a loose_route() retornar TRUE a destination uri é definida de acordo com o primeiro Route header

Esta é uma variável de leitura e escrita

!!!!Error class

$err.class - the class of error (now is '1' for parsing errors)

!!!!Error level

$err.level - severity level for the error

!!!!Error info

$err.info - text describing the error

!!!!Error reply code

$err.rcode - recommended reply code

!!!!Error reply reason

$err.rreason - recommended reply reason phrase

!!!!From URI domain

$fd - reference to domain in URI of 'From' header

!!!!From display name

$fn - reference to display name of 'From' header

!!!!Forced socket

$fs - reference to the forced socket for message sending (if any) in the form proto:ip:port

%red%It is R/W variable (you can assign values to it routing script)%%

!!!!From tag

$ft - reference to tag parameter of 'From' header

!!!!From URI

$fu - reference to URI of 'From' header

!!!!From URI username

$fU - reference to username in URI of 'From' header

!!!!SIP message buffer

$mb - reference to SIP message buffer

!!!!Message Flags

$mf - displays a list with the message/transaction flags set for the current SIP request

!!!!Message Flags (hexadecimal) %red%(Removed in OpenSIPS 1.9)%%

$mF -reference to message/transaction flags set for current SIP request in hexa

!!!!SIP message ID

$mi - reference to SIP message id

!!!!SIP message length

$ml - reference to SIP message length

!!!!Domain in SIP Request's original URI

$od - reference to domain in request's original R-URI

!!!!Port of SIP request's original URI

$op - reference to port of original R-URI

!!!!Transport protocol of SIP request original URI

$oP - reference to transport protocol of original R-URI

!!!!SIP Request's original URI

$ou - reference to request's original URI

!!!!Username in SIP Request's original URI

$oU - reference to username in request's original URI

!!!!Route parameter $param(idx) - retrieves the parameters of the route. The index can be an integer, or a pseudo-variable (index starts at 1).\\ Example: [@

  route {
     ...
     $var(debug) = "DBUG:"
     route(PRINT_VAR, $var(debug), "param value");
     ...
  }

  route[PRINT_VAR] {
     $var(index) = 2;
     xlog("$param(1): The parameter value is <$param($var(index))>\n");
  }

@]

!!!!Domain in SIP Request's P-Preferred-Identity header URI

$pd - reference to domain in request's P-Preferred-Identity header URI (see RFC 3325)

!!!!Display Name in SIP Request's P-Preferred-Identity header

$pn - reference to Display Name in request's P-Preferred-Identity header (see RFC 3325)

!!!!Process id

$pp - reference to process id (pid)

!!!!Protocol of received message $pr or $proto - protocol of received message (UDP, TCP, TLS, SCTP)

!!!!User in SIP Request's P-Preferred-Identity header URI

$pU - reference to user in request's P-Preferred-Identity header URI (see RFC 3325)

!!!!URI in SIP Request's P-Preferred-Identity header

$pu - reference to URI in request's P-Preferred-Identity header (see RFC 3325)

!!!!Domain in SIP Request's URI

$rd - reference to domain in request's URI

%red%It is R/W variable (you can assign values to it routing script)%%

!!!!Body of request/reply

$rb - reference to message body

!!!!Returned code

$rc - reference to returned code by last invoked function

$retcode - same as **$rc**

!!!!Remote-Party-ID header URI

$re - reference to Remote-Party-ID header URI

!!!!SIP request's method

$rm - reference to request's method

!!!!SIP request's port

$rp - reference to port of R-URI

%red%It is R/W variable (you can assign values to it routing script)%%

!!!!Transport protocol of SIP request URI

$rP - reference to transport protocol of R-URI

!!!!SIP reply's reason

$rr - reference to reply's reason

!!!!SIP reply's status

$rs - reference to reply's status

!!!!Refer-to URI

$rt - reference to URI of refer-to header

!!!!SIP Request's URI

$ru - reference to request's URI

%red%It is R/W variable (you can assign values to it routing script)%%

!!!!Username in SIP Request's URI

$rU - reference to username in request's URI

%red%It is R/W variable (you can assign values to it routing script)%%

!!!!Q value of the SIP Request's URI

$ru_q - reference to q value of the R-URI

%red%It is R/W variable (you can assign values to it routing script)%%

!!!!Received IP address

$Ri - reference to IP address of the interface where the request has been received

!!!!Received port

$Rp - reference to the port where the message was received

!!!!Script flags

$sf - displays a list with the script flags set for the current SIP request

!!!!Script flags (hexadecimal) %red%(Removed in OpenSIPS 1.9)%%

$sF - reference to script flags - hexa output

!!!!IP source address

$si - reference to IP source address of the message

!!!!Source port

$sp - reference to the source port of the message

!!!!To URI Domain

$td - reference to domain in URI of 'To' header

!!!!To display name

$tn - reference to display name of 'To' header

!!!!To tag

$tt - reference to tag parameter of 'To' header

!!!!To URI

$tu - reference to URI of 'To' header

!!!!To URI Username

$tU - reference to username in URI of 'To' header

!!!!Formatted date and time

$time(format) - returns the string formatted time according to UNIX date (see: man date).

!!!!Branch index

$T_branch_idx - the index (starting with 1 for the first branch) of the branch for which is executed the branch_route[]. If used outside of branch_route[] block, the value is '0'. This is exported by TM module.

!!!!String formatted time

$Tf - reference string formatted time

!!!!Current unix time stamp in seconds

$Ts - reference to current unix time stamp in seconds

!!!!Current microseconds of the current second

$Tsm - reference to current microseconds of the current second

!!!!Startup unix time stamp

$TS - reference to startup unix time stamp

!!!!User agent header

$ua - reference to user agent header field

!!!!SIP Headers

$(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. To print the last header of that type, use -1, no other negative values are supported now. No white spaces are allowed inside the specifier (before }, before or after {, [, ] symbols). When N='*', all headers of that type are printed.

The module should identify most of compact header names (the ones recognized by OpenSIPS which should be all at this moment), if not, the compact form has to be specified explicitly. It is recommended to use dedicated specifiers for headers (e.g., %ua for user agent header), if they are available -- they are faster.

$(hdrcnt(name)) -- returns number of headers of type given by 'name'. Uses same rules for specifying header names as $hdr(name) above. Many headers (e.g., Via, Path, Record-Route) may appear more than once in the message. This variable returns the number of headers of a given type.

Note that some headers (e.g., Path) may be joined together with commas and appear as a single header line. This variable counts the number of header lines, not header values.

For message fragment below, $hdrcnt(Path) will have value 2 and $(hdr(Path)[0]) will have value <a.com>: [@

   Path: <a.com>
   Path: <b.com>

@]

For message fragment below, $hdrcnt(Path) will have value 1 and $(hdr(Path)[0]) will have value <a.com>,<b.com>: [@

   Path: <a.com>,<b.com>

@]

Note that both examples above are semantically equivalent but the variables take on different values.

#varavps

!!!Escape Sequences

These sequences are exported, and mainly used, by xlog module to print messages in many colors (foreground and background) using escape sequences.

!!!!Foreground and background colors

$C(xy) - reference to an escape sequence. ¿x¿ represents the foreground color and ¿y¿ represents the background color.

Colors could be:

• x : default color of the terminal
• s : Black
• r : Red
• g : Green
• y : Yellow
• b : Blue
• p : Purple
• c : Cyan
• w : White

!!!!Examples

A few examples of usage.

[@ ... route { ...

   $avp(uuid)="caller_id";
   $avp(tmp)= $avp(uuid) + ": " + $fu;
   xdbg("$(C(bg))avp(tmp)$(C(xx)) [$avp(tmp)] $(C(br))cseq$(C(xx))=[$hdr(cseq)]\n");

... } ... @]