Transformações

Transformação é basicamente a função que é aplicada a uma variável (variavel de script, pseudo-variavel, AVPS, strings staticas), para pegar um valor especial, o valor da variável horiginal não é alterado.

Exemplo utilizando diferentes tipos de variáveis em no script OpenSIPS

# verificando se o usuário no cabeçalho From é igual ao usuário no cabeçalho To 

if($fU==$tU) {
   ...
}

# checagem de usuário baseado em r-uri 

switch($ruri.user) {
   case "1234":
      ...
   break;
   case "5678":
      ...
   break;
   default:
     ...
}

# definindo um valor inteiro para um AVP 
$avp(i:11) = 1;

# definindo um valor de texto (string) para um AVP
$avp(i:22) = "opensips";

# Definir o valor de $ruri para um avp
$avp(i:33) = $ruri;

# concatenando "sip:" + usuário no From + "@" + dominio no To na variável x
$var(x) = "sip:" + $fU +"@" + $td;

As transformações possuem o intuito de facilitar o acesso a diferentes atributos de variáveis, como o tamanho da string (strlen) , partes do valor, substring ou valores diferentes de variaveis (encoded em hexa, valor md5, escapar valores para operações em banco).

A transformação é representada entre '{' e '}' e segue o nome da variável. Quando utilizando transformação, o nome da variável e transformações devem estar dentro de parentesis '(' e ')' .

Exemplo:

# o tamanho do From URI ( $fu é uma pseudo-variável para From URI)

$(fu{s.len})

Muitas transformações podem ser aplicadas ao mesmo tempo na mesma variável.

# O tamanho do cabeçalho 'Test' (escapado) .

$(hdr(Test){s.escape.common}{s.len})

A transformação pode ser utilizada em qualquer lugar, sendo considerada parte das variáveis no script --- no xlog, avpops ou outros módulos, funções e parametros, a direita de expressões de atribuição ou em comparações.

Para aprender que variável pode ser utilizada com transformações veja [Variáveis Core]

Transformação de string

O nome destas trasnformações iniciam com 's.' , são utilizadas para aplicar operações de string nas variáveis.

Transformações disponiveis nesta classe:

{s.len}

Retorna o tamanho do valor de uma variável

$var(x) = "abc";
if($(var(x){s.len}) == 3)
{
   ...
}

{s.int}

Retorna o valor inteiro de uma string númerica.

$var(x) = "1234";
if($(var(x){s.int})==1234) {
  ...
}

{s.md5}

Retorna o md5 do valor da variável

xlog("MD4 over From username: $(fU{s.md5})");

{s.substr,offset,length}

Retornar o pedaço (substring) iniciando no valor de offset até o valor de length . Se offset é negativo, então a contagem começa no fim, onde -1 é o último caracter. Em caso de valor positivo, 0 é o primeiro valor, o tamanho (length) deve ser positivo, em caso de 0, a substring retornará até o fim do valor, offset e length podem ser variáveis também.

Example:

$var(x) = "abcd";
$(var(x){s.substr,1,0}) = "bcd"

{s.select,index,separator}

Retorna um campo do valor da variável. O campo é selecionado baseado no spearador (separator) e indice (index). O separador deve ser um caractere usado para identificar os campos. Indice (index) deve ser um valor inteiro ou uma variavel. Se o index for negativo a contagem de campos começa do fim do valor, -1 é o último campo, se o index é positivo, 0 é o primeiro campo.

Exemplo:

$var(x) = "12,34,56";
$(var(x){s.select,1,,}) => "34" ;

$var(x) = "12,34,56";
$(var(x){s.select,-2,,}) => "34"

{s.encode.hexa}

Retorna o valor da variável em hexa.

{s.decode.hexa}

Decodifica o valor hexa da variável.

{s.escape.common}

Retorna a string scapada do valor da variável. Caracteres escapados são ', ", e 0 , este recurso é util quando necessário realizar consultas em banco de dados ( deve se atentar quando utilizando caracteres que não fazem parte do LATIN )

{s.unescape.common}

Retorna o valor sem escape de uma variável, o inverso da transformação acima.

{s.escape.user}

Retorna o valor escapado da variavel, alterando para '%hexa' os caracteres nao permitidos na area SIP URI seguindos as recomendações da RFC.

{s.unescape.user}

Retorna o valor sem escape da variável, alterando de '%hexa' para caracter, o inverso da transformação acima.

{s.escape.param}

Retorna o valor escapado da variável, alterando para '%hexa' o caractere que não é permitido na area param da SIP URI seguindo as recomendações da RFC.

{s.unescape.param}

Retorna o valor sem escape da variavel alterando de '%hexa' para caractere, inverso da transformação acima.

{s.tolower}

Retorna a string em lower case (caixa baixa)

{s.toupper}

Retorna a string em upper case (caixa alta)

URI Transformations

O nome da transformação inicia-se com 'uri.'. O valor da variável é considerado ser parte da SIP URI. Esta transformação retorna partes da SIP URI (veja struct sip_uri). Se a parte estiver faltando o valor retornando será uma string vazia.

Transformações disponiveis nesta classe:

{uri.user}

Retorna o usuário no schema URI

{uri.host}

(mesmo que {uri.domain})

Retorna a parte do dominio no schema URI.

{uri.passwd}

Retorna a parte da senha no schema URI.

{uri.port}

Retorna a parte da porta no schema URI.

{uri.params}

Retorna todos os parametros da URI em uma única string.

{uri.param,name}

Retorna o valor do parametro da URI com nome de "name"

{uri.headers}

Retorna os cabeçalhos URI

{uri.transport}

Retorna o valor do parametro transport da URI.

{uri.ttl}

Retorna o valor do parametro TTL da URI.

{uri.uparam}

Retorna o valor do parametro user da URI.

{uri.maddr}

Retorna o valor do parametro maddr da URI.

{uri.method}

Retorna o valor do parametro metodo da URI.

{uri.lr}

Retorna o valor do parametro lr da URI.

{uri.r2}

Retorna o valor do parametro r2 da URI.

VIA Transformations

Estas são as tranformações para o cabeçalho Via e todas iniciam com @@via@@. O valor da variável é considerado estar no cabeçalho SIP Via. Esta transformação retornará partes do cabeçalho vai ( veja struct via_body ). Se parte requisitada estiver faltando então o valor de retorna será uma variável vazia. A transformação irá falhar (com erro no script) se a variável que contem o cabeçalho Via estiver vazia. A menos que especificado abaixo, o resultado da transformação será uma string (não um inteiro).

Exemplos:

   $var(upstreamtransport) = $(hdr(Via)[1]{via.transport}{s.tolower});
   $var(upstreamip) = $(hdr(Via)[1]{via.param,received});
   $var(clientport) = $(hdr(Via)[-1]{via.param,rport});

Transformações disponíveis nesta classe:

{via.name}

Retorna o @@protocol-name@@ ( RFC3261 BNF ), geralmente @@SIP@@.

{via.version}

Retorna o @@protocol-version@@ ( RFC3261 BNF ), geralmente @@2.0@@.

{via.transport}

Retorna o @@transport@@ ( RFC3261 BNF ), ex: @@UDP@@, @@TCP@@, @@TLS@@. Este é o protocolo de transporte utilizado para enviar a mensagem.

{via.host}

(mesmo que @@{via.domain}@@)

Retorna o @@host@@ do @@sent-by@@ (RFC3261 BNF). Tipicamente é o IP de quem enviou a requisição, e claro, é o endereço para onde a resposta será envaida.

{via.port}

Retorna a @@port@@ to @@sent-by@@ (RFC3261). Tipicamente é a Porta de quem enviou a requisição e o endereço para onde a resposta será enviada, o resultado da transformação é valido tanto como inteiro quanto string.

{via.comment}

O comment associado com o cabeçalho via. A @@struct via_body@@ contém este capmo, mas ele não é claro que a RFC3261 permite a utilização de comentarios em cabeçalho Via ( veja o texto no topo da pagina 221 , e a BNF não explicita se permite comentário em Via). O texto da comment deve ser fechado por parenteses.

{via.params}

Retorna Todos os parametros do cabeçalho Via ( @@via-param@@ da RFC3261 BNF ) como uma string única. O resultado pode ser processado através da transformação @@{param.*}@@ . Isso é basicamente tudo após o host e porta.

{via.param,name}

Retorna o valor do parametro do cabeçalho Via especificado por @@name@@. Tipicamente parametros incluem @@branch@@, @@rport@@ e @@received@@.

{via.branch}

Retorna o valor do parametro branch no cabeçalho VIA.

{via.received}

Retorna o valor do parametro received no cabeçalho Via , se existir.

{via.rport}

Retorna o valor do parametro rport no cabeçalho VIA, se existir.

Parameters List Transformations

O nome da transformação inicia por "param." . O valor da variavel é considerado uma string como nome1=valor1; nome2=valor2;..." . A transformação retorna o valor de um parametro especifico ou o nome do parametro especificado no indice.

Transformações disponiveis nesta classe:

{param.value,name}

Retorna o valor do parametro 'name'

Exemplo:

"a=1;b=2;c=3"{param.value,c} = "3"

O valor de 'name' pode ser uma variável.

{param.exist,name}

Retorna 1 se o parametro @@name@@ existir (com ou sem valor), caso contrário retorna 0. O valor retornado é tanto string quanto inteiro. @@name@@ pode ser uma variável. Esta função pode ser utilizada para testar se um parametro possue ou não valores.

Exemplo:

"a=0;b=2;ob;c=3"{param.exist,ob};         # returns 1
"a=0;b=2;ob;c=3"{param.exist,a};          # returns 1
"a=0;b=2;ob;c=3"{param.exist,foo};        # returns 0

{param.valueat,index}

Retorna o valor do parametro na posição fornecida por 'index' (0-based index)

"a=1;b=2;c=3"{param.valueat,1} = "2"

'index' pode ser uma variável

{param.name,index}

Retorna o nome do parametro na posição 'index'.

Exemplo:

"a=1;b=2;c=3"{param.name,1} = "b"

{param.count}

Retorna o número de parametros na lista.

Exemplo:

"a=1;b=2;c=3"{param.count} = 3

Name-address Transformations

A nome da transformação inica com 'nameaddr.' . O valor da variável é considerado ser uma string como '[display_name] uri'. A transformação retorna o valor especificado no campo.

Transformações disponiveis para esta classe:

{nameaddr.name}

Retorna o valor de display name

Exemplo:

'"test" <sip:test@opensips.org>' {nameaddr.name} = "test"

{nameaddr.uri}

Retorna o valor da URI

Exemplo:

'"test" <sip:test@opensips.org>' {nameaddr.uri} = sip:test@opensips.org

{nameaddr.len}

Retorna o tamanho da name-addr

{nameaddr.param,param_name}

Retorna o valor do parametro com o nome 'param_name'.

Exemplo:

'"test" <sip:test@opensips.org>;tag=dat43h' {nameaddr.param,tag} = dat43h

{nameaddr.params}

Retorna os parametros e seus valores correspondentes.

Exemplo:

'"test" <sip:test@opensips.org>;tag=dat43h;private=yes' {nameaddr.params} = "tag=dat43h;private=yes"

IP Transformations

O nome da transformação inicia com 'ip.'

Transformações disponiveis para esta classe:

{ip.pton}

Retorna a representação binária do IP

Exemplo:

"192.168.2.134" {ip.pton} returns a 4 byte binary representation of the IP provided

{ip.ntop}

Retorna a representação de um binário de IP

Exemplo:

"192.168.2.134"{ip.pton}{ip.ntop} = "192.168.2.134"

{ip.isip}

Retorna 1 ou 0, se a string provida for um ip válido ou não.

Exemplo:

"192.168.2.134" {ip.isip} = 1
"192.168.2.134.1" {ip.isip} = 0

{ip.family}

Retorna INET ou INET6 se a representação binária provida for um IPv4 ou IPv6.

Exemplo:

"192.168.2.134" {ip.pton}{ip.family} = "INET"

{ip.resolve}

Retorna o IP de um host.dominio informado. a transformação não tem efeito se um IP for forncido.

Exemplo:

"opensips.org" {ip.resolve} = "78.46.64.50"

CSV Transformations

O nome da transformação inicia com "csv." . O valor da variável é considerado ser uma string como "campo1,campo2,....". A transformação retorna o numero de entradas no CSV informado, ou o campo de uma posição especifica do CSV.

Tranformações disponiveis nesta classe:

{csv.count}

Retorna o número de entradas no CSV provido.

Exemplo:

"a,b,c" {csv.count} = 3

{csv.value}

Retorna a entrada na posição especifica. Index inicia em 0

Exemplo:

"a,b,c" {csv.value,2} = c

SDP Transformations

O nome da transformação inica com "sdp.". O valor da variaável é considerado ser um body SDP válido. A transformação retorna uma linha especifica no body SDP.

Transformações disponiveis para esta classe:

={sdp.line}

Retorna a linha especifica do body SDP. A transformação também aceita um segundo parametro, este especificado é o número da linha do primeiro parametro para pegar do body SDP. Index inicia em 0. Se o segundo parametro estiver faltando ele assume 0.

Exemplo

if (is_method("INVITE"))
   {
      $var(aline) = $(rb{sdp.line,a,1});
      xlog("The second a line in the SDP body is $var(aline)\n");
   }

if (is_method("INVITE"))
   {
      $var(mline) = $(rb{sdp.line,m});
      xlog("The first m line in the SDP body is $var(mline)\n");
   }

Regular Expression Transformations

O nome da trasnformação inicia-se com "re." . O valor de entrada pode ser qualquer string.

{re.subst,reg_exp}

O parametro reg_exp pode ser tanto uma string quanto uma variável.

O formato da reg_exp é:

   /posix_match_expression/replacement_expression/flags

As flags podem ser:

   i - match ignore case
   s - match within multi-lines strings
   g - replace all matches

Exemplo:

$var(reg_input)="abc";
$var(reg) = "/a/A/g";
xlog("Applying reg exp $var(reg) to $var(reg_input) : $(var(reg_input){re.subst,$var(reg)})\n");

...
...
xlog("Applying reg /b/B/g to $var(reg_input) : $(var(reg_input){re.subst,/b/B/g})\n");

Exemplos

Em uma variável, muitas trasnformações podem ser aplicadas, começando da esquerda para a direita.

• O tamanho do valor da variavel do parametro na posição 1 (lembre-se que 0 é a primeira posição, 1 é a segunda)

$var(x) = "a=1;b=22;c=333";
$(var(x){param.value,$(var(x){param.name,1})}{s.len}) = 2

• Testa se é des-registro ou não

if(is_method("REGISTER") && is_present_hf("Expires") && $(hdr(Expires){s.int})==0)
    xlog("This is an un-registrationn");

Voltar