Mudanças entre as edições de "Funções Core"

De opensipsbrasil - wiki
Ir para navegação Ir para pesquisar
 
(4 revisões intermediárias pelo mesmo usuário não estão sendo mostradas)
Linha 87: Linha 87:
 
  cache_store("redis:cluster1","passwd_$tu","$var(x)");
 
  cache_store("redis:cluster1","passwd_$tu","$var(x)");
  
Exemplos mais complexos podem ser encontrados em [[http://www.opensips.org/Documentation/Tutorials-KeyValueInterface]].
+
Exemplos mais complexos podem ser encontrados em [http://www.opensips.org/Documentation/Tutorials-KeyValueInterface]
  
  
Linha 103: Linha 103:
 
  cache_remove("redis:cluster1","my_attr");
 
  cache_remove("redis:cluster1","my_attr");
  
Exempos mais complexos podem ser encontrados em [[http://www.opensips.org/Documentation/Tutorials-KeyValueInterface]].
+
Exemplos mais complexos podem ser encontrados em [http://www.opensips.org/Documentation/Tutorials-KeyValueInterface]
  
  
Linha 121: Linha 121:
  
  
Exempos mais complexos podem ser encontrados em [[http://www.opensips.org/Documentation/Tutorials-KeyValueInterface]].
+
Exemplos mais complexos podem ser encontrados em [http://www.opensips.org/Documentation/Tutorials-KeyValueInterface]
  
 
==cache_counter_fetch( storage_id, counter_attribute_name, result_avp)==
 
==cache_counter_fetch( storage_id, counter_attribute_name, result_avp)==
Linha 140: Linha 140:
 
==cache_add( storage_id, attribute_name,increment_value,expire)==
 
==cache_add( storage_id, attribute_name,increment_value,expire)==
  
Esta função incrementa um atributo em  
+
Esta função incrementa um atributo em um memory-cache-like-storage (armazenamento em memória) que suporte esta opração ,o atributo pode conter uma pseudo-variavel, se o atributo não existe ele será criado com o valor do incremento, se o valor de expire for maior que 0 a chave irá expirar no tempo especificado (em segundos)
This increments an attribute in a memory-cache-like-storage system that supports such an operation. The attribute name may contain pseudo-variables. If the attribute does not exit, it will be created with the increment_value. If expire > 0, the key will also expire in the specified number of seconds.
+
 
 +
A função retorna false se o incremento falhar
 +
 
 +
 
 +
modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
 +
...
 +
cache_add("redis:cluster1",5);
 +
 
 +
 
 +
Exemplos mais complexos podem ser encontrados em [[http://www.opensips.org/Documentation/Tutorials-KeyValueInterface]].
 +
 
 +
==cache_sub( storage_id, attribute_name,increment_value,expire)==
 +
 
 +
Esta função decrementa um atributo em um memory-cache-like-storage (armazenamento em memória) que suporte esta operação, o atributo pode conter uma pseudo variavel, se o valor de expire for maior que 0 a chave irá expirar no tempo especificado (em segundos)
  
Function returns false if increment fails.
 
  
[@
+
A função retorna false se o decremento falhar
  
modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
+
modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
+
...
cache_add("redis:cluster1",5);
+
cache_sub("redis:cluster1",5);
@]
+
  
More complex examples can be found in the [[Documentation.Tutorials-KeyValueInterface | Key-Value Interface Tutorial]].
+
Exemplos mais complexos podem ser encontrados em [http://www.opensips.org/Documentation/Tutorials-KeyValueInterface]
  
!!!!cache_sub( storage_id, attribute_name,increment_value,expire)
+
==cache_raw_query( storage_id, raw_query,result_avp)==
  
This decrements an attribute in a memory-cache-like-storage system that supports such an operation. The attribute name may contain pseudo-variables. If expire > 0, the key will also expire in the specified number of seconds.
+
Esta função executa a query ( dependendo da linguagem do back-end informado ) e retorna o resultado (se algum) na AVP informada, a '''result_avp''' pode nao existir se não houver resultados.
  
Function returns false if decrement fails.
+
A função retorna false se a query falhar
  
[@
 
  
modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
+
...
...
+
cache_raw_query("mongodb","{ \"op\" : \"count\",\"query\": { \"username\" : $rU} }","$avp(mongo_count_result)");
cache_sub("redis:cluster1",5);
+
...
@]
 
  
More complex examples can be found in the [[Documentation.Tutorials-KeyValueInterface | Key-Value Interface Tutorial]].
 
  
!!!!cache_raw_query( storage_id, raw_query,result_avp)
+
Exemplos mais complexos podem ser encontrados em [http://www.opensips.org/Documentation/Tutorials-KeyValueInterface]
  
The function runs the provided raw query ( in the back-end dependent language ) and returns the results ( if any ) in the provided AVP. The result_avp can be missing, if the query returns no results.
+
==break()==
  
Function returns false if query fails.
+
Apartir da versão 0.10.0-dev3 a função 'break' não pode mais ser utilizada para parar a execução de uma rota, o único lugar que a mesma pode ser utilizada é para finalizar um bloco 'case' em um statement 'switch', para a função de parar o roteamento deve ser utilizado 'return' invés de 'break'
  
[@
+
as funções 'return' e 'break' tem agora um significado similar a linguagem c ou shell
...
 
cache_raw_query("mongodb","{ \"op\" : \"count\",\"query\": { \"username\" : $rU} }","$avp(mongo_count_result)");
 
...
 
@]
 
  
More complex examples can be found in the [[Documentation.Tutorials-KeyValueInterface | Key-Value Interface Tutorial]].
 
  
!!!!break()
+
==construct_uri(proto,user,domain,port,extra,result_avp)==
  
Since v0.10.0-dev3, 'break' can no longer be used to stop the execution of a route. The only place to use is to end a 'case' block in a 'switch' statement. 'return' must be now used instead of old 'break'.
+
Esta função constrói um uri sip valida baseada nos argumentos recebidos, o resultado (se algum) será armazenado na '''result_avp''' informada, pode ser utilizado argumento como texto puro assim como $var(nome) ou $avp(nome), se você quiser omitir parte da sip uri basta utilizar o parametro respectivo em branco.
  
'return' and 'break' have now a similar meaning as in c/shell.
+
Exemplo de uso:
  
!!!!construct_uri(proto,user,domain,port,extra,result_avp)
+
construct_uri("$var(proto)", "vlad", "$var(domain)", "", "$var(params)",$avp(s:newuri));
The function builds a valid sip uri based on the arguments it receives. The result (if any) will be stored in the result_avp AVP variable.
+
xlog("Constructed URI is <$avp(s:newuri)> \n");
The function accepts plain text arguments, as well as $var and $avp variables. If you want to omit a part of the sip uri, just set the respective parameter to a blank string.
 
  
Example usage:
 
[@
 
construct_uri("$var(proto)", "vlad", "$var(domain)", "", "$var(params)",$avp(s:newuri));
 
xlog("Constructed URI is <$avp(s:newuri)> \n");
 
@]
 
  
!!!!drop()
+
==drop()==
  
Stop the execution of the configuration script and alter the implicit action which is done afterwards.
+
Para a execução de um script e altera a ação implícita feita na sequência.
  
If the function is called in a 'branch_route' then the branch is discarded (implicit action for 'branch_route' is to forward the request).
+
Se a função é chamada em uma 'branch_route' então esta perna é descartada (ação implicita em um 'branch_route' é encaminhar a requisição)
  
If the function is called in a 'onreply_route' then any provisional reply is discarded (implicit action for 'onreply_route' is to send the reply upstream according to Via header).
+
Se a função é chamada em um 'onreply_route' então qualquer reply será descartado ( a ação implicita em uma 'onreply_route' é enviar o reply de acordo com o cabeçalho via)
  
Example of usage:
+
Exemplo de uso:
  
 
     onreply_route {
 
     onreply_route {
Linha 215: Linha 213:
 
     }
 
     }
  
!!!!exit()
+
==exit()==
 +
 
 +
Para a execução do script, tem o mesmo propósito de '''return(0)''', esta função não afeta a ação implicita após a execução do script
  
Stop the execution of the configuration script -- it has the same behaviour as return(0). It does not affect the implicit action to be taken after script execution.
 
  
 
   route {
 
   route {
Linha 238: Linha 237:
 
   }
 
   }
  
!!!!force_rport()
+
==force_rport()==
Force_rport() adds the rport parameter to the first Via header. Thus, '''OpenSIPS''' will add the received IP port to the top most via header in the SIP message, even if the client does not indicate support for rport. This enables subsequent SIP messages to return to the proper port later on in a SIP transaction.
+
 
 +
A função force_rport() adiciona o parametro rport no primeiro cabeçalho Via, assim o '''OpenSIPS''' irá adicionar a porta para o cebaçalho mais alto da mensagem SIP mesmo se o cliente não indicar suporte a isso, desta forma as mensagens subsequentes para retornarem o valor correto de porta em uma transação posterior
 +
 
 +
O parametro rport é definido pela RFC 3581
  
The rport parameter is defined in RFC 3581.
 
  
Example of usage:
+
Exemplo de uso
  
 
     force_rport();
 
     force_rport();
  
!!!!force_send_socket([proto:]address[:port])
+
==force_send_socket([proto:]address[:port])==
 +
 
 +
Esta função força o '''OpenSIPS''' para enviar a mensagem apartir do socket especificado ( _DEVE_ ser um dos endereços (sockets) que o '''OpenSIPS''' está executando (escutando)) , se o protocolo não corresponder (ex: mensagem udp forçando para tcp) o socket mais proximo para o protocolo especificado será utilizado.
  
Force '''OpenSIPS''' to send the message from the specified socket (it _must_ be one of the sockets '''OpenSIPS''' listens on). If the protocol doesn't match (e.g. UDP message "forced" to a TCP socket) the closest socket of the same protocol is used.
 
  
Example of usage:
+
Exemplo de uso:
  
 
     force_send_socket(10.10.10.10:5060);
 
     force_send_socket(10.10.10.10:5060);
  
  
!!!!force_tcp_alias()
+
==force_tcp_alias()==
 +
 
 +
force_tcp_alias(port)     
 +
 
 +
Esta função adiciona uma porta alias para a conexão atual (se tcp), esta função é útil se você quer enviar todo o seu trafego pela '''port_alias''' através da mesma conexão que a requisição foi recebida [ isso pode ajudar com firewall ou nat traversal ].
  
force_tcp_alias(port)    
+
Se nenhum parametro for adicionado para a porta então a porta onde a mensagem foi recebida será adicionada como alias.
 +
Quando a conexão for fechada todas as portas em alias serão removidas (ex: conexão idle por muito tempo)
  
adds a tcp port alias for the current connection (if tcp).
+
==forward(destination)==
Usefull if you want to send all the trafic to port_alias through
 
the same connection this request came from [it could help
 
for firewall or nat traversal].
 
With no parameters adds the port from the message via as the alias.
 
When the "aliased" connection is closed (e.g. it's idle for too
 
much time), all the port aliases are removed.
 
  
!!!!forward(destination)
+
Encaminha a requisição SIP para o endereço informado em modo stateless, o formato deve ser [proto:]host[:port], o host pode ser um IP ou um hostname, os protocolos uportados são UDP, TCP e TLS (para TLS você precisar ter o suporte a TLS no core).
 +
Se proto ou port não forem especificados então serão utilizadas consultas NAPTR e SRV para determinar (se possivel).
  
Forward the SIP request to the given destination in stateless mode. This has the format of [proto:]host[:port]. Host can be an IP or hostname; supported protocols are UDP, TCP and TLS. (For TLS, you need to compile the TLS support into core).
+
Se o destino não for informado o encaminhamento será feito baseado na RURI.
If proto or port are not specified, NAPTR and SRV lookups will be used to determine them (if possible).
 
  
If destination parameter is missing, the forward will be done based on RURI.
 
  
Example of usage:
+
Exemplo de uso
  
 
     forward("10.0.0.10:5060");
 
     forward("10.0.0.10:5060");
    #or
+
ou
 
     forward();
 
     forward();
  
!!!!get_timestamp(sec_avp,usec_avp)
+
==get_timestamp(sec_avp,usec_avp)==
 +
 
 +
Esta função retorna o timestamp atual, segundos e microsegundos do segundo atual apartir de uma unica chamada
 +
 
  
Returns the current timestamp, seconds and microseconds of the current second, from a single system call.
 
  
Example of usage:
+
Exemplo de uso:
  
 
     get_timestamp($avp(sec),$avp(usec));
 
     get_timestamp($avp(sec),$avp(usec));
  
  
!!!!isdsturiset()
+
==isdsturiset()==
 +
 
 +
Testa se o campo dst_uri (endereço de next hop) está definido
  
Test if the dst_uri field (next hop address) is set.
 
  
Example of usage:
+
Exemplo de uso
  
 
     if(isdsturiset()) {
 
     if(isdsturiset()) {
Linha 300: Linha 303:
 
     };
 
     };
  
!!!!isflagset(int)
+
==isflagset(int)==
 +
 
 +
Testa se uma determinada flag está definida no processamento atual (se o valor da flag é 1), o valor do parametro pode ser em um range de 0 a 31
  
Test if a flag is set for current processed message (if the flag value is 1). The value of the parameter can be in range of 0..31.
 
  
For more see [[Documentation/Script-Flags-1-9 | Flags Documentation]].
+
Para saber mais veja a [Scripting_Flags| Documentação de Flag]
  
Example of usage:
+
Exemplo de uso:
  
 
     if(isflagset(3)) {
 
     if(isflagset(3)) {
Linha 312: Linha 316:
 
     };
 
     };
  
!!!!isbflagset([branch_idx,] flag_idx)
+
==isbflagset([branch_idx,] flag_idx)==
  
Test if a flag is set for a specific branch (if the flag value is 1). The value of the "flag_idx" parameter can be in range of 0..31. "branch_idx" identify the branch for which the flags are tested - it must be a positiv number. Branch index 0 refers to the RURI branch. If this parameter is missing, 0 branch index is used as default.
+
Testa se uma flag está definida na perna (branch) especifica (se o valor é 1), o valor para 'flag_idx' pode ser um range de 0 a 31, a 'branch_idx' identifica a perna para qual a flag será testada , deve ser um número positivo, Branch index 0 referencia a RURI da perna, se o parametro não for especificado 0 será definido como padrão.
  
For more about script flags, see [[Documentation/Script-Flags-1-9 | Flags Documentation]].
+
Para saber mais veja a [[Scripting_Flags| Documentação de Flag]]
  
Example of usage:
+
Exemplo de uso:
  
 
     if(isbflagset(1,3)) {
 
     if(isbflagset(1,3)) {
Linha 324: Linha 328:
 
     };
 
     };
  
!!!!issflagset(flag_idx)
+
==issflagset(flag_idx)==
  
Test if a script flag is set (if the flag value is 1). The value of the "flag_idx" parameter can be in range of 0..31.
+
Teste se um flag de script está definida (se o valor da flag é 1) o valor de '''flag_idx''' pode ser um range de 0 até 31
  
For more about script flags, see [[Documentation/Script-Flags-1-9 | Flags Documentation]].
+
Para saber mais veja a [[Scripting_Flags| Documentação de Flag]]
  
Example of usage:
+
Exemplo de uso:
  
 
     if(issflagset(2)) {
 
     if(issflagset(2)) {
Linha 336: Linha 340:
 
     };
 
     };
  
!!!!log([level,] string)
 
  
Write text message to standard error terminal or syslog. You can specify the log level as first parameter.
+
==log([level,] string)==
 +
 
 +
Escreve uma mensagem para a saída de erro padrão ou para o syslog, você pode especificar o log level como primeiro parametro.
 +
 
  
Example of usage:
+
Exemplo de uso:
  
 
     log("just some text message\n");
 
     log("just some text message\n");
  
  
!!!!next_branches()
+
==next_branches()==
 +
 
 +
'''NOTA: nao entendi bem esta definição então a tradução pode não corresponder exatamente, desculpem por isso'''
 +
 
 +
Adiciona a requisição um novo destino que inclui todos os contatos altos (baseado em valor 'q') da branch serializada (veja função serialize_branches() para mais detalhes), se a função for chamada de um bloco de roteamento então irá re-escrever a uri da requisição com o primeiro contato e adicionar os demais como branches paralelas. Se chamada em uma rota de falha (failure route) adicionará todos os contatos em branches paralelas. Todos os contatos são removidos das branches serializadas.
 +
 
  
Adds to the request a new destination set that includes all highest priority class contacts ('q' value based) from the serialized branches (see serialize_branches()). If called from a route block, it rewrites the request uri with first contact and adds the remaining contacts as parallel branches.  If called from failure route block, adds all contacts as parallel branches.  All used
+
Retorna true se pelo menos um contato for adicionado para a requisição - retorna 1 se outras branches continuam pendentes, e retorna 2 se nenhuma branch ficou de fora para processamento posterior , resumindo, 2 -> esta é a ultima branch, 1-> outra branch ainda seguira.
contacts are removes the serialized branches.
 
  
Returns true if at least one contact was added for the request's destination set - returns 1 if other branches are still pending and return 2 if no other branches are left for future processing - shortly, if 2: this is the last branch, if 1: other will follow. False is return is nothing was done (no more serialized branches).
+
Falso será retornado se nada for feito (não existir mais branches para serializar)
  
Example of usage:
+
Exemplo de uso:
  
 
     next_branches();
 
     next_branches();
  
  
!!!!prefix(string)
+
==prefix(string)==
  
Add the string parameter in front of username in R-URI.
+
Adiciona o parametro na frente do username na R-URI  
  
Example of usage:
+
Exemplo de uso:
  
 
     prefix("00");
 
     prefix("00");
  
!!!!pv_printf(pv, string)
+
==pv_printf(pv, string)==
 +
 
 +
Faz um print da string formatada no AVP , o parametro 'string' pode incluir qualquer pseudo-variavel definida no '''OpenSIPS''', the '''pv''' pode ser qualquer pseu-variavel que possa ser escrita ( ex: AVPs, VARs, $ru, $rU, $rd, $du, $br, $fs)
  
Prints the formatted 'string' in the AVP 'pv'. The 'string' parameter can include any pseudo-variable defined in '''OpenSIPS'''. The 'pv' can be any writable pseudo-variable -- e.g.,: AVPs, VARs, $ru, $rU, $rd, $du, $br, $fs.
+
Esta função foi extendida da função avp_printf(...) das versões anteriores do módulo avpops, iniciando na versão 1.3.0  o avp_printf(...) é apenas um alias para pv_printf(....)
  
It was extended from the avp_printf(...) function exported in previous versions by the avpops module. Starting with 1.3.0, avp_printf(...) is just an alias to pv_printf(...).
 
  
Example of usage:
+
Exemplo de uso:
  
 
     pv_printf("$var(x)", "r-uri: $ru");
 
     pv_printf("$var(x)", "r-uri: $ru");
 
     pv_printf("$avp(i:3)", "from uri: $fu");
 
     pv_printf("$avp(i:3)", "from uri: $fu");
  
[[#raise_event]]
+
==raise_event(string[, avp[, avp]])==
!!!!raise_event(string[, avp[, avp]])
 
  
Raises from script an event through OpenSIPS Event Interface. The first parameter is a string that indicates the event which should be raised. The next two parameters should be AVPs and they are optional. If only one is present, it should contain the values attached to the event. If both of them are specified, the first one should contain the names of the attributes, and the last one the values attached to the event.
+
Cria apartir do script um evento na interface de eventos do OpenSIPS, o primeiro parametro é uma string que indica que o evento deve ser criado, os dois outros parametros devem ser AVP's e eles são opcionais, se apenas um estiver presente este deve conter os valores que serão atrelados ao evento, se os dois valores forem especificados o primeiro deve conter o nome dos atributos e o segundo os valores que serão atrelados ao evento.
  
This function triggers an event for all subscribers for that event, regardless the transport module used.
+
Esta função ativa um evento para todos os assinantes daquele evento dependendo do método de transporte usado.
  
Example of usage (raises an event with no attributes):
+
Exemplo de uso (criar um evento sem atributos)
  
[@
 
raise_event("E_NO_PARAM");
 
@]
 
  
Example of usage (raises an event with two attributes):
+
raise_event("E_NO_PARAM");
  
[@
+
Exemplo de uso (cria um evento com dois atributos)
 +
 
 +
<pre>
 
$avp(attr-name) = "param1";
 
$avp(attr-name) = "param1";
 
$avp(attr-name) = "param2";
 
$avp(attr-name) = "param2";
Linha 397: Linha 406:
 
$avp(attr-val) = "2"
 
$avp(attr-val) = "2"
 
raise_event("E_TWO_PARAMS", $avp(attr-name), $avp(attr-val));
 
raise_event("E_TWO_PARAMS", $avp(attr-name), $avp(attr-val));
@]
+
</pre>
  
!!!!remove_branch(pv|int)
+
==remove_branch(pv|int)==
  
Removes a given branch.  The branch to be removed can be given via an integer or a pseudovariable.
+
Remove a perna (branch) informada, a perna que será removida pode ser informada por um inteiro ou uma pseudo-variavel, no momento que a perna é removida todas as pernas subsequentes serão deslocadas (ex: se a perna n é removida, então a anterior n+1 será a nova perna, a anterior n+2 passará a ser a n+1 e assim por diante)
Once a branch is remove, all the subsequent branches are shifted (i.e. if branch n is removed, then the old n+1 branch becomes the new n branch, the old n+2 branch becomes n+1 and so on).
 
  
Example of usage (remove all branches with URI hostname "127.0.0.1"):
+
Exemplo de uso (remove todas as branches que contenham na URI o hostname '127.0.0.1')
 
+
<pre>
[@
 
 
$var(i) = 0;
 
$var(i) = 0;
 
while ($(branch(uri)[$var(i)]) != null) {
 
while ($(branch(uri)[$var(i)]) != null) {
Linha 417: Linha 424:
 
   }
 
   }
 
}
 
}
@]
+
</pre>
  
!!!!return(int)
+
==return(int)==
  
The return() function allows you to return any integer value from a called route() block.
+
A função return() permite que você retorne um valor inteiro de um bloco de roteamento, você pode testar o valor retornado usando a variavel '''$retcode'''.
You can test the value returned by a route using "$retcode" variable.
 
  
return(0) is same as "exit()";
+
return(0) é o mesmo que '''exit()'''
  
In bool expressions:
+
Expressão booleana:
  
   * Negative and ZERO is FALSE
+
   * Negativo e ZERO é FALSE
   * Positive is TRUE
+
   * Positivo é TRUE
  
Example usage:  
+
Exemplo de uso:
  
[@
+
<pre>
 
route {
 
route {
 
   if (route(2)) {
 
   if (route(2)) {
Linha 441: Linha 447:
 
   };
 
   };
 
}
 
}
@]
+
 
[@
 
 
route[2] {
 
route[2] {
 
   if (is_method("INVITE")) {
 
   if (is_method("INVITE")) {
Linha 452: Linha 457:
 
   };
 
   };
 
}
 
}
@]
+
</pre>
 +
 
 +
==resetdsturi()==
  
!!!!resetdsturi()
+
Define o valor do campo dst_uri para NULL, o campo dst_uri normalmente é definido após loose_route() ou lookup("location") se o endereço de contato está atrás de NAT
  
Set the value of dst_uri filed to NULL. dst_uri field is usually set after loose_route() or lookup("location") if the contact address is behind a NAT.
 
  
Example of usage:
+
Exemplo de uso:
  
 
     resetdsturi();
 
     resetdsturi();
  
!!!!resetflag(int)
+
==resetflag(int)==
 +
 
 +
Reseta o valor de uma flag para o processamento atual (define o valor para 0), o valor para o parametro poder ser um número de 0 até 31.
  
Reset a flag for current processed message (set the value to 0). The value of the parameter can be in range of 0..31.
 
  
For more see [[Documentation/Script-Flags-1-9 | Flags Documentation]].
+
Para saber mais veja a [[Scripting_Flags| Documentação de Flag]]
  
Example of usage:
+
Exemplo de uso
  
 
     resetflag(3);
 
     resetflag(3);
  
!!!!resetbflag([branch_idx,] flag_idx)
+
==resetbflag([branch_idx,] flag_idx)==
  
Reset a flag for a specific branch (set flag to value 0). The value of the "flag_idx" parameter can be in range of 0..31. "branch_idx" identify the branch for which the flag is reset - it must be a positiv number. Branch index 0 refers to the RURI branch. If this parameter is missing, 0 branch index is used as default.
+
Reseta a flag para uma perna especifica (define o valor para 0), o valor de '''flag_idx''' pode ser um número de 0 até 31, '''branch_idx''' identifica a perna para qual a flag será resetada, deve ser um numero positivo, a branch index 0 refere-se a RUR da branch em questão, se o parametro for omitido 0 será definido como padrão.
  
For more about script flags, see [[Documentation/Script-Flags-1-9 | Flags Documentation]].
+
Para saber mais veja a [[Scripting_Flags| Documentação de Flag]]
  
Example of usage:
+
Exemplo de uso
[@
+
<pre>
 
     resetbflag(1,3);
 
     resetbflag(1,3);
 
     # or
 
     # or
 
     resetbflag(3); # same with resetbflag(0,3)
 
     resetbflag(3); # same with resetbflag(0,3)
@]
+
</pre>
 +
 
  
  
 +
==resetsflag(flag_idx)==
  
!!!!resetsflag(flag_idx)
+
Reseta uma flag de script (define o valor para 0), o valor the '''flag_idx''' pode ser um número de 0 até 31
  
Reset a script flag (set flag to value 0). The value of the "flag_idx" parameter can be in range of 0..31.
 
  
For more about script flags, see [[Documentation/Script-Flags-1-9 | Flags Documentation]].
+
Para saber mais veja a [[Scripting_Flags| Documentação de Flag]]
  
Example of usage:
+
Exemplo de uso
  
 
     resetsflag(2);
 
     resetsflag(2);
  
!!!!revert_uri()
+
==revert_uri()==
 +
 
 +
Define a R-URI para o valor original de quando a mesma chegou no servidor (desfaz todas as alterações)
  
Set the R-URI to the value of the R-URI as it was when the request was received by server (undo all changes of R-URI).
 
  
Example of usage:
+
Exemplo de uso:
  
 
     revert_uri();
 
     revert_uri();
  
!!!!rewritehost() / sethost()
+
==rewritehost() / sethost()==
  
Rewrite the domain part of the R-URI with the value of function's parameter. Other parts of the R-URI like username, port and URI parameters remain unchanged.
+
re-escreve o dominio da R-URI com o valor especificado no parametro da função, outras partes da R-URI como username , porta e os parametros URI permancem inalterados.
  
Example of usage:
+
Exemplos de uso:
  
 
     rewritehost("1.2.3.4");
 
     rewritehost("1.2.3.4");
  
!!!!rewritehostport() / sethostport()
+
==rewritehostport() / sethostport()==
 +
 
 +
Re-escreve o dominio e porta da R-URI com o valor especificado no parametro da função, outras partes da R-URI como username e parametros de URI não são alterados
  
 
Rewrite the domain part and port of the R-URI with the value of function's parameter. Other parts of the R-URI like username and URI parameters remain unchanged.
 
Rewrite the domain part and port of the R-URI with the value of function's parameter. Other parts of the R-URI like username and URI parameters remain unchanged.
  
Example of usage:
+
Exemplo de uso:
  
 
     rewritehostport("1.2.3.4:5080");
 
     rewritehostport("1.2.3.4:5080");
  
!!!!rewriteuser(string) / setuser(string)
+
==rewriteuser(string) / setuser(string)==
 +
 
 +
Re-escreve o username na R-URI com o valor do parametro.
  
Rewrite the user part of the R-URI with the value of function's parameter.
 
  
Example of usage:
+
Exemplo de uso:
  
 
     rewriteuser("newuser");
 
     rewriteuser("newuser");
  
!!!!rewriteuserpass() / setuserpass()
+
==rewriteuserpass() / setuserpass()==
 +
 
 +
Re-escreve a parte referente ao password da R-URI com o valor definido no parametro.
  
Rewrite the password part of the R-URI with the value of function's parameter.
 
  
Example of usage:
+
Exemplo de uso:
  
 
     rewriteuserpass("my_secret_passwd");
 
     rewriteuserpass("my_secret_passwd");
  
!!!!rewriteport() / setport()
+
==rewriteport() / setport()==
 +
 
 +
Re-escreve/define a parte referente a porta da R-URI com o valor definido no parametro.
  
Rewrites/sets the port part of the R-URI with the value of function's parameter.
 
  
Example of usage:
+
Exemplo de uso:
  
 
     rewriteport("5070");
 
     rewriteport("5070");
  
!!!!rewriteuri(str) / seturi(str)
+
==rewriteuri(str) / seturi(str)==
 +
 
 +
Re-escreve a URI recebida
  
Rewrite the request URI.
 
  
Example of usage:
+
Exemplo de uso:
  
 
     rewriteuri("sip:test@opensips.org");
 
     rewriteuri("sip:test@opensips.org");
  
!!!! route(name [, param1 [, param2 [, ...] ] ] )
+
==route(name [, param1 [, param2 [, ...] ] ] )==
 +
 
 +
Esta função é utiliza para chamar uma rota declarada no script, opcionalmente ela pode receber diversos parametros (até 7) que podem ser recuperados depois com a pseudo-variavel $param(idx).
  
This function is used to run the code from the 'name' route, declared in the script. Optionally, it can receive several parameters (up to 7), that can be later retrieved using the '$param(idx)' pseudo-variable.
+
O nome da rota deve ser um identificador, os parametros podem ser o mesmo ou inteiro, string ou mesmo pseudo-variaveis
  
The name of the route is an identifier format, whereas the parameters can be either int, string, or a pseudo-variable.
 
  
Example of usage:
+
Exemplo de uso:
  
 
   route(HANDLE_SEQUENTIALS);
 
   route(HANDLE_SEQUENTIALS);
Linha 565: Linha 581:
  
  
!!!! script_trace( log_level, pv_format_string[, info_string])
+
==script_trace( log_level, pv_format_string[, info_string])==
 +
 
 +
Esta função inicia um tracing no script , isso ajuda a melhor entender o fluxo de execução do script do OpenSIPS, como que função é executada, que linha é e etc.., no mais você também pode traçar os valores das pseudo-variaveis como o progresso da execução do script.
  
This function start the script tracing - this helps to better understand the flow of execution in the OpenSIPS script, like what function is executed, what line it is, etc. Moreover, you can also trace the values of pseudo-variables, as script execution progresses.
+
O bloco do script onde o tracing é ativado irá exibir uma linha para cada ação individual que é realizada (ex: atribuições, testes condicionais, funções de módulos, funções de core etc...), multiplas pseudo-variaveis podem ser monitoradas especificando no formato '''pv_format_string''' (ex: "$ru---$avp(var1)" ).
  
The blocks of the script where script tracing is enabled will print a line for each individual action that is done (e.g. assignments, conditional tests, module functions, core functions, etc.). Multiple pseudo-variables can be monitored by specifying a '''pv_format_string''' (e.g. "$ru---$avp(var1)").
+
O log produzido por multiplas/diferentes regiões com tracert ativo podem ser diferenciadas (taggeadas) especificando uma string adicional  ('''info_string''') como terceiro parametro.
  
The logs produced by multiple/different traced regions of your script can be differentiated (tagged) by specifying an additional plain string - '''info_string''' - as the 3rd parameter.
+
Para desativar o tracert do script apenas chama script_trace() , em todo caso o tracer será parado no fim da execução do script
  
To disable script tracing, just do script_trace(). Otherwise, the tracing will automatically stop at the end the end of the top route.
 
  
Example of usage:
+
Exemplo de uso:
 
     script_trace( 1, "$rm from $si, ruri=$ru", "me");
 
     script_trace( 1, "$rm from $si, ruri=$ru", "me");
  
will produce:
+
irá gerar a seguinte saída:
[@
+
 
 
     [line 578][me][module consume_credentials] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
 
     [line 578][me][module consume_credentials] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
 
     [line 581][me][core setsflag] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
 
     [line 581][me][core setsflag] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
Linha 589: Linha 606:
 
     [line 587][me][module trace_dialog] -> (INVITE 127.0.0.1 , ruri=sip:tester@opensips.org)
 
     [line 587][me][module trace_dialog] -> (INVITE 127.0.0.1 , ruri=sip:tester@opensips.org)
 
     [line 590][me][core setflag] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)  
 
     [line 590][me][core setflag] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)  
@]
 
  
  
!!!!send(destination [, headers])
+
==send(destination [, headers])==
 +
 
 +
Envia a mensagem SIP original para um destino especifico em modo stateless, o destino deve ser especificado no formato [proto:]host[:port] , nenhuma alteração é realizada na mensagem, não é adicionado cabeçalho VIA a menos que você especifique, o host pode ser um IP ou hostname, os protocolos suportados são UDP, TCP e TLS (para TLS o suporte deve estar ativo no core), se proto ou port não forem especificados requisições de NAPTR e SRV serão realizadas (se possivel) para tentar identificar os dados. O parametro header deve terminar com '\r\n' e pode aceitar tanto texto puro quanto pseudo-variaveis.
  
Send the original SIP message to a specific destination in stateless mode. This is definied as [proto:]host[:port]. No changes are applied to received message, no Via header is added, unless headers parameter is specified. Host can be an IP or hostname; supported protocols are UDP, TCP and TLS. (For TLS, you need to compile the TLS support into core). If proto or port are not specified, NAPTR and SRV lookups will be used to determine them (if possible). The headers parameter should end in '\r\n' and can accept both plain text and pseudo variables.
+
O parametro é obrigatório e possue um formato de string.
  
Parameter is mandatory and has string format.
 
  
Example of usage:
+
Exemplo de uso:
  
 
   send("udp:10.10.10.10:5070");
 
   send("udp:10.10.10.10:5070");
Linha 605: Linha 622:
  
  
!!!!serialize_branches(clear)
+
==serialize_branches(clear)==
  
Takes all the branches added for parallel forking (with append_branch() and including the current RURI) and prepare them for serial forking. The ordering is done in increasing "q" order. The serialized branches are internally stored in AVPs - you will be able to fetch and use via the "next_branches()" function.\\
+
'''NOTA: não entendi muito bem o conceito e não achei a melhor forma pra traduzir, então pesço desculpas se estiver confuso'''
NOTE that (according to RFC3261), the branches with the same "q" value will still be parallel forked during a certain step in the serial forking (it will result a combination of serial with parallel forking).\\
 
NOTE that this function is not changing RURI in the messages - it is just converting from parallel to serial branches (preparing branches).
 
  
If "clear" is set to non-zero, all previous results of another "serialize_branches" (serialized branches which were not yet used) will be deleted before setting the new serialized branches.
+
Coloca todas as pernas em um processamento paralelo (com append_branch() e incluindo a RURI atual) e prepara as mesmas para processamento isolado, a ordenação é feita aumentando a ordenação "q" , as pernas serializadas são internamente armazenadas em AVPs, você poderá receber os valores através da função '''next_branch()'''
  
Example of usage:
+
NOTA: De acordo com a RFC3261, as pernas com o mesmo valor 'q' permanecerão separadas durante alguns processos da separação serial, isso irá resultar em uma combinação de separação serial e paralela).
 +
 
 +
NOTA: Esta função não ltera a RURI da mensagem, ela apenas converte de paralelo para serial
 +
 
 +
Se '''clear''' é definido para non-zero , todos os resultados de outras 'serialize_branches' (branches serializadas que ainda não foram utilizadas) serão deletadas antes de definir novas serialized branches.
 +
 
 +
 
 +
Exemplo de uso:
  
 
   serialize_branches(1);
 
   serialize_branches(1);
Linha 619: Linha 641:
  
  
!!!!set_advertised_address(ip|string)
+
==set_advertised_address(ip|string)==
 +
 
 +
Mesmo que 'advertised_address' mas afeta apenas a mensagem atual, esta tem prioridade se a 'advertised_address' também está definida.
  
Same as 'advertised_address' but it affects only the current message. It has priority if 'advertised_address' is also set.
 
  
Example of usage:
+
Exemplo de uso:
  
 
     set_advertised_address("opensips.org");
 
     set_advertised_address("opensips.org");
  
!!!!set_advertised_port(int)
 
  
Same as 'advertised_port' but it affects only the current message. It has priority over 'advertised_port'.
+
==set_advertised_port(int)==
 +
 
 +
Mesmo que 'advertised_port' mas tem efeito apenas a mensagme atual, possui prioridade sobre 'advertised_port'
 +
 
  
Example of usage:
+
Exemplo de uso:
  
 
     set_advertised_port(5080);
 
     set_advertised_port(5080);
  
 +
==setdebug([level])==
  
!!!!setdebug([level])
+
Altera o valor de debug do processo atual do script, se chamado sem parametro então o level de debug do processo será resetado para o level global, se for definido o parametro então o nivel será alterado no processo e então a alteração do debug geral (utilizando a MI por exemplo) não terá efeito sobre o mesmo, então tenha cuidado e tenha certeza de resetar o processo queando você terminar, esta função é muito útil se você estiver tracándo e debugando apenas uma parte especifica do código.
  
Changes the debug level of the current process from script. If called without the parameter then the debug level of the current process will be reset to the global level. If the debug level of the current process is changed then changing the global debug level (using MI function) does not affect it, so be careful and make sure to reset the process debug level when you are done. This function is very helpful if you are tracing and debugging only a specific piece of code.
 
  
Example of usage:
+
Exemplo de uso:
  
 
     debug= -1 # errors only
 
     debug= -1 # errors only
Linha 652: Linha 677:
 
     }
 
     }
  
!!!!setdsturi(string)
+
==setdsturi(string)==
 +
 
 +
Definie explicitamente o valor do campo dst_uri para o valor do parametro especificado, o parametro deve ser uma URI SIP valida.
  
Explicitely set the dst_uri field to the value of the paramater. The parameter has to be a valid SIP URI.
 
  
Example of usage:
+
Exemplo de uso
  
 
     setdsturi("sip:10.10.10.10:5090");
 
     setdsturi("sip:10.10.10.10:5090");
  
!!!!setflag(int)
+
==setflag(int)==
  
Set a flag for current processed message. The value of the parameter can be in range of 0..31. The flags are used to mark the message for special processing (e.g., accounting) or to keep some state (e.g., message authenticated).
+
Define uma flag para o processamento da mensagem atual, o valor do parametro pode ser um numero de 0 a 31, as flags são utilizadas para marcar a mensagem para processamento especifico (como accounting) ou para manter alguns statos (como mensagens autenticadas)
  
Example of usage:
+
Example of usage:Exemplo de uso.
  
 
     setflag(3);
 
     setflag(3);
  
  
!!!!setbflag([branch_idx,] flag_idx)
+
==setbflag([branch_idx,] flag_idx)==
  
Set a flag for a specific branch (set flag to value 1). The value of the "flag_idx" parameter can be in range of 0..31. "branch_idx" identify the branch for which the flag is set - it must be a positiv number. Branch index 0 refers to the RURI branch. If this parameter is missing, 0 branch index is used as default.
+
Define uma flag para um branch especifica (define o valor para 1) , o valor de '''flag_idx''' pode ser um numero de 0 a 31,  a '''branch_idx''' identifica a branch para qual a flag será aplicada, deve ser um numero positivo, index 0 refere-se a RURI da branch atual, se o parametro não for especificado o index 0 será utilizado.  
  
For more about script flags, see [[Documentation/Script-Flags-1-9 | Flags Documentation]].
 
  
Example of usage:
+
Para saber mais veja a [[Scripting_Flags| Documentação de Flag]]
 +
 
 +
Exemplo de uso
  
 
     setbflag(1,3);
 
     setbflag(1,3);
    # or
+
ou
 
     setbflag(3); # same with setbflag(0,3)
 
     setbflag(3); # same with setbflag(0,3)
  
  
 +
==setsflag(flag_idx)==
  
 +
Define uma flag de script (define para 0), o valor de '''falg_idx''' pode ser um numero de 0 a 31
  
!!!!setsflag(flag_idx)
+
Para saber mais veja a [[Scripting_Flags| Documentação de Flag]]
 
 
Set a script flag (set flag to value 0). The value of the "flag_idx" parameter can be in range of 0..31.
 
  
For more about script flags, see [[Documentation/Script-Flags-1-9 | Flags Documentation]].
 
  
Example of usage:
+
Exemplo de uso
  
 
     setsflag(2);
 
     setsflag(2);
  
!!!!strip(int)
+
==strip(int)==
  
Strip the first N-th characters from username of R-URI (N is the value of the parameter).
+
Remove os primeiros N caracteres do campo username da R-URI (N é o valor do parametro)
  
Example of usage:
+
Exemplo de uso:
  
 
     strip(3);
 
     strip(3);
  
!!!!strip_tail(int)
+
==strip_tail(int)==
 +
 
 +
Remove os ultimos N caracteres do campo username da R-URI (N é o valor do parametro)
  
Strip the last N-th characters from username of R-URI (N is the value of the parameter).
 
  
Example of usage:
+
Exemplo de uso:
  
 
   strip_tail(3);
 
   strip_tail(3);
  
[[#subscribe_event]]
 
!!!!subscribe_event(string, string [, int])
 
  
Subscribes an external application for a certain event for the OpenSIPS Event Interface. This is used for transport protocols that cannot subscribe by themselves (example event_rabbitmq). This function should be called only once in the startup_route if the subscription doesn't expire, or in a timer route if the subscription should be renewed once in a while.
+
==subscribe_event(string, string [, int])==
  
The first parameter is a string represents the name of the event an external application should be notified for. The second parameter is a string that specifies the socket of the external application. Note that this socket should follow the syntax of an existing loaded Event Interface transport module (example: event_datagram, event_rabbitmq). The last parameter is optional and specifies the expire time of the subscription. If it is not present, then the subscription does not expire at all.
+
Assina (subscribe) uma aplicação externa para um certo evento para a interface de eventos do OpenSIPS, esta opção é utilizada para protocolos de transportes que não podem assinar (subscribe) por si mesmos (ex: event_rabbitmq) , esta função deve ser chamada apenas uma vez na startup_route se a assinatura (susbcription) não expira, ou em uma '''timer route''' se a assinatura deve ser renovado em algum momento.
  
Example of usage (subscriber that never expires, notified by the RabbitMQ module):
+
O primeiro parametro é a sting que representa o nome do evento que uma aplicação externa deve ser notificada, o segundo parametro é a string que especifica o socket para a aplicação externa. veja que o socket deve seguir a syntax de um módulo de transporte carregado para interface de eventos (ex: event_datagram, event_rabbitmq), o último parametro é opcional e especifica o tempo de expiração da assinatura , se não está presente então a subscrição não irá expirar.
  
[@
+
Exemplo de uso (assinante que nunca espira, notificado pelo módulo rabbitmq)
 +
 
 +
<pre>
 
startup_route {
 
startup_route {
 
     subscribe_event("E_PIKE_BLOCKED", "rabbitmq:127.0.0.1/pike");
 
     subscribe_event("E_PIKE_BLOCKED", "rabbitmq:127.0.0.1/pike");
 
}
 
}
@]
+
</pre>
  
Example of usage (subscriber expires every 5 seconds, notified through UDP):
+
Exemplo de uso (assinante expira em 5 segundos, notificado via udp)
  
[@
+
<pre>
 
timer_route[event_subscribe, 4] {
 
timer_route[event_subscribe, 4] {
 
     subscribe_event("E_PIKE_BLOCKED", "udp:127.0.0.1:5051", 5);
 
     subscribe_event("E_PIKE_BLOCKED", "udp:127.0.0.1:5051", 5);
 
}
 
}
@]
+
</pre>
 +
 
 +
==use_blacklist(string)==
 +
 
 +
Ativa a blacklist de dns para o nome recebido no parametro, o proposito primario é prevenir enviar request para IP criticos (como gateways) devido ao DNS ou prevenir enviar chamadas para destinos que estão (temporario ou permanentemente) indisponiveis.
  
!!!!use_blacklist(string)
 
  
Enables the DNS blacklist name received as parameter. Its primary purposes will be to prevent sending requests to critical IPs (like GWs) due DNS or to avoid sending to destinations that are known to be unavailable (temporary or permanent).
 
[@
 
 
     use_blacklist("pstn-gws");
 
     use_blacklist("pstn-gws");
@]
+
 
 +
[[OpenSIPS_1.9_Manual|Voltar]]

Edição atual tal como às 19h27min de 19 de outubro de 2013

Esta sessão lista as funções exportadas pelo core do OpenSIPS para utilização no script (para ser utilizado no opensips.cfg)


Índice

add_local_rport()

Adiciona o parametro 'rport' no cabeçalho VIA gerado pelo servidor (confira a RFC3581 para entender o significado disso). Esta função afeta apenas a requisição atualmente processada.

Exemplo de uso:


   add_local_rport()

append_branch()

Similar ao t_fork_to, esta função extende o destino definindo uma nova entrada, a diferença é que a URI atual é pega como uma nova entrada

Sem um parametro a função copia a URI atual em uma nova branch, desta forma deixando a branch principal (a URI) para manipulação futura.

Se for definido um parametro a função copia a URI na nova branch, assim a URI atual não é manipulada.

Veja que não é possivel adicionar uma nova branch em um bloco "on_failure_route" se uma resposta 6XX foi recebida previamente ( isso iria contra a RFC 3261 )

Exemplo de uso:

    # if someone calls B, the call should be forwarded to C too.
    #
    if (method=="INVITE" && uri=~"sip:B@xx.xxx.xx ")
    {
        # copy the current branch (branches[0]) into
        # a new branch (branches[1])
        append_branch();
        # all URI manipulation functions work on branches[0]
        # thus, URI manipulation does not touch the 
        # appended branch (branches[1])
        seturi("sip:C@domain");
        
        # now: branch 0 = C@domain
        #      branch 1 = B@xx.xx.xx.xx
        
        # and if you need a third destination ...
        
        # copy the current branch (branches[0]) into
        # a new branch (branches[2])
        append_branch();
        
        # all URI manipulation functions work on branches[0]
        # thus, URI manipulation does not touch the 
        # appended branch (branches[1-2])
        seturi("sip:D@domain");
        
        # now: branch 0 = D@domain
        #      branch 1 = B@xx.xx.xx.xx
        #      branch 2 = C@domain
        
        t_relay();
        exit;
    };

    # You could also use append_branch("sip:C@domain") which adds a branch with the new URI:
    
    
    if(method=="INVITE" && uri=~"sip:B@xx.xxx.xx ") {
        # append a new branch with the second destination
        append_branch("sip:user@domain");
        # now: branch 0 = B@xx.xx.xx.xx
        # now: branch 1 = C@domain

        t_relay();
        exit;
}

cache_store( storage_id, attribute_name, attribute_name [,timeout])

Esta função define em um memory-cache-like-storage (armazenamento em memória) um novo valor para um atributo, tanto o nome do atributo quanto o valor deve conter pseudo-variaveis, se o atributo não existe ainda no memcache ele será inserido com os valores informados, se ele está presente o seu valor será substituido pelo valor informado, a função opcionalmente pode receber parametros , um valor de timeout (ou lifetime) para o atributo, após o tempo definido ser excedido o atributo é removido da memória.

A função retorna true se o novo atributo foi inserido com sucesso.


cache_store("local","my_attr","$avp(i:55)",1200);

OU

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_store("redis:cluster1","passwd_$tu","$var(x)");

Exemplos mais complexos podem ser encontrados em [1]


cache_remove( storage_id, attribute_name)

Esta função remove um atributo de um memory-cache-like-storage (armazenamento em memória), o atributo poder conter uma pseudo-variavel. A função retorna false apenas se o storage_id for inválido.

cache_remove("local","my_attr");

OU

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_remove("redis:cluster1","my_attr");

Exemplos mais complexos podem ser encontrados em [2]


cache_fetch( storage_id, attribute_name, result_pvar)

Esta função traz de um memory-cache-like-storage (armazenamento em memória) o valor de um atributo, o nome do atributo pode conter uma pseudo-variavel, o resultado (se algum) será armazenado na pseudo-variavel especificada por result_pvar .

A função retorna true se o atributo for encontrado e seu valor retornado.

cache_fetch("local","my_attr", $avp(i:11) );

OU

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_fetch("redis:cluster1","my_attr",$avp(i:11));


Exemplos mais complexos podem ser encontrados em [3]

cache_counter_fetch( storage_id, counter_attribute_name, result_avp)

Esta função pega de um memory-cache-like-storage (armazenamento em memória) o valor de um contador, o atributo pode contar pseudo-variaveis. O resultado (se algum) será armazenado na pseudo-variavel especificado por result_pvar.

A função retorna true se o atributo foi encontrado e o valor retornado.

cache_counter_fetch("local","my_counter", $avp(counter_val) );

OU

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_fetch("redis:cluster1","my_counter",$avp(redis_counter_val));


cache_add( storage_id, attribute_name,increment_value,expire)

Esta função incrementa um atributo em um memory-cache-like-storage (armazenamento em memória) que suporte esta opração ,o atributo pode conter uma pseudo-variavel, se o atributo não existe ele será criado com o valor do incremento, se o valor de expire for maior que 0 a chave irá expirar no tempo especificado (em segundos)

A função retorna false se o incremento falhar


modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_add("redis:cluster1",5);


Exemplos mais complexos podem ser encontrados em [[4]].

cache_sub( storage_id, attribute_name,increment_value,expire)

Esta função decrementa um atributo em um memory-cache-like-storage (armazenamento em memória) que suporte esta operação, o atributo pode conter uma pseudo variavel, se o valor de expire for maior que 0 a chave irá expirar no tempo especificado (em segundos)


A função retorna false se o decremento falhar

modparam("cachedb_redis","cachedb_url","redis:cluster1://192.168.2.134:6379/")
...
cache_sub("redis:cluster1",5);

Exemplos mais complexos podem ser encontrados em [5]

cache_raw_query( storage_id, raw_query,result_avp)

Esta função executa a query ( dependendo da linguagem do back-end informado ) e retorna o resultado (se algum) na AVP informada, a result_avp pode nao existir se não houver resultados.

A função retorna false se a query falhar


...
cache_raw_query("mongodb","{ \"op\" : \"count\",\"query\": { \"username\" : $rU} }","$avp(mongo_count_result)");
...


Exemplos mais complexos podem ser encontrados em [6]

break()

Apartir da versão 0.10.0-dev3 a função 'break' não pode mais ser utilizada para parar a execução de uma rota, o único lugar que a mesma pode ser utilizada é para finalizar um bloco 'case' em um statement 'switch', para a função de parar o roteamento deve ser utilizado 'return' invés de 'break'

as funções 'return' e 'break' tem agora um significado similar a linguagem c ou shell


construct_uri(proto,user,domain,port,extra,result_avp)

Esta função constrói um uri sip valida baseada nos argumentos recebidos, o resultado (se algum) será armazenado na result_avp informada, pode ser utilizado argumento como texto puro assim como $var(nome) ou $avp(nome), se você quiser omitir parte da sip uri basta utilizar o parametro respectivo em branco.

Exemplo de uso:

construct_uri("$var(proto)", "vlad", "$var(domain)", "", "$var(params)",$avp(s:newuri));
xlog("Constructed URI is <$avp(s:newuri)> \n");


drop()

Para a execução de um script e altera a ação implícita feita na sequência.

Se a função é chamada em uma 'branch_route' então esta perna é descartada (ação implicita em um 'branch_route' é encaminhar a requisição)

Se a função é chamada em um 'onreply_route' então qualquer reply será descartado ( a ação implicita em uma 'onreply_route' é enviar o reply de acordo com o cabeçalho via)

Exemplo de uso:

   onreply_route {
       if(status=="183") {
           drop();
       }
   }

exit()

Para a execução do script, tem o mesmo propósito de return(0), esta função não afeta a ação implicita após a execução do script


 route {
   if (route(2)) {
     xlog("L_NOTICE","method $rm is INVITE\n");
   } else {
     xlog("L_NOTICE","method is $rm\n");
   };
 }
 route[2] {
   if (is_method("INVITE")) {
     return(1);
   } else if (is_method("REGISTER")) {
     return(-1);
   } else if (is_method("MESSAGE")) {
     sl_send_reply("403","IM not allowed");
     exit;
   };
 }

force_rport()

A função force_rport() adiciona o parametro rport no primeiro cabeçalho Via, assim o OpenSIPS irá adicionar a porta para o cebaçalho mais alto da mensagem SIP mesmo se o cliente não indicar suporte a isso, desta forma as mensagens subsequentes para retornarem o valor correto de porta em uma transação posterior

O parametro rport é definido pela RFC 3581


Exemplo de uso

   force_rport();

force_send_socket([proto:]address[:port])

Esta função força o OpenSIPS para enviar a mensagem apartir do socket especificado ( _DEVE_ ser um dos endereços (sockets) que o OpenSIPS está executando (escutando)) , se o protocolo não corresponder (ex: mensagem udp forçando para tcp) o socket mais proximo para o protocolo especificado será utilizado.


Exemplo de uso:

   force_send_socket(10.10.10.10:5060);


force_tcp_alias()

force_tcp_alias(port)      

Esta função adiciona uma porta alias para a conexão atual (se tcp), esta função é útil se você quer enviar todo o seu trafego pela port_alias através da mesma conexão que a requisição foi recebida [ isso pode ajudar com firewall ou nat traversal ].

Se nenhum parametro for adicionado para a porta então a porta onde a mensagem foi recebida será adicionada como alias. Quando a conexão for fechada todas as portas em alias serão removidas (ex: conexão idle por muito tempo)

forward(destination)

Encaminha a requisição SIP para o endereço informado em modo stateless, o formato deve ser [proto:]host[:port], o host pode ser um IP ou um hostname, os protocolos uportados são UDP, TCP e TLS (para TLS você precisar ter o suporte a TLS no core). Se proto ou port não forem especificados então serão utilizadas consultas NAPTR e SRV para determinar (se possivel).

Se o destino não for informado o encaminhamento será feito baseado na RURI.


Exemplo de uso

   forward("10.0.0.10:5060");

ou

   forward();

get_timestamp(sec_avp,usec_avp)

Esta função retorna o timestamp atual, segundos e microsegundos do segundo atual apartir de uma unica chamada


Exemplo de uso:

    get_timestamp($avp(sec),$avp(usec));


isdsturiset()

Testa se o campo dst_uri (endereço de next hop) está definido


Exemplo de uso

   if(isdsturiset()) {
       log("dst_uri is set\n");
   };

isflagset(int)

Testa se uma determinada flag está definida no processamento atual (se o valor da flag é 1), o valor do parametro pode ser em um range de 0 a 31


Para saber mais veja a [Scripting_Flags| Documentação de Flag]

Exemplo de uso:

   if(isflagset(3)) {
       log("flag 3 is set\n");
   };

isbflagset([branch_idx,] flag_idx)

Testa se uma flag está definida na perna (branch) especifica (se o valor é 1), o valor para 'flag_idx' pode ser um range de 0 a 31, a 'branch_idx' identifica a perna para qual a flag será testada , deve ser um número positivo, Branch index 0 referencia a RURI da perna, se o parametro não for especificado 0 será definido como padrão.

Para saber mais veja a Documentação de Flag

Exemplo de uso:

   if(isbflagset(1,3)) {
       log("flag 3 is set in branch 1\n");
   };

issflagset(flag_idx)

Teste se um flag de script está definida (se o valor da flag é 1) o valor de flag_idx pode ser um range de 0 até 31

Para saber mais veja a Documentação de Flag

Exemplo de uso:

   if(issflagset(2)) {
       log("script flag 2 is set\n");
   };


log([level,] string)

Escreve uma mensagem para a saída de erro padrão ou para o syslog, você pode especificar o log level como primeiro parametro.


Exemplo de uso:

   log("just some text message\n");


next_branches()

NOTA: nao entendi bem esta definição então a tradução pode não corresponder exatamente, desculpem por isso

Adiciona a requisição um novo destino que inclui todos os contatos altos (baseado em valor 'q') da branch serializada (veja função serialize_branches() para mais detalhes), se a função for chamada de um bloco de roteamento então irá re-escrever a uri da requisição com o primeiro contato e adicionar os demais como branches paralelas. Se chamada em uma rota de falha (failure route) adicionará todos os contatos em branches paralelas. Todos os contatos são removidos das branches serializadas.


Retorna true se pelo menos um contato for adicionado para a requisição - retorna 1 se outras branches continuam pendentes, e retorna 2 se nenhuma branch ficou de fora para processamento posterior , resumindo, 2 -> esta é a ultima branch, 1-> outra branch ainda seguira.

Falso será retornado se nada for feito (não existir mais branches para serializar)

Exemplo de uso:

   next_branches();


prefix(string)

Adiciona o parametro na frente do username na R-URI

Exemplo de uso:

   prefix("00");

pv_printf(pv, string)

Faz um print da string formatada no AVP , o parametro 'string' pode incluir qualquer pseudo-variavel definida no OpenSIPS, the pv pode ser qualquer pseu-variavel que possa ser escrita ( ex: AVPs, VARs, $ru, $rU, $rd, $du, $br, $fs)

Esta função foi extendida da função avp_printf(...) das versões anteriores do módulo avpops, iniciando na versão 1.3.0 o avp_printf(...) é apenas um alias para pv_printf(....)


Exemplo de uso:

   pv_printf("$var(x)", "r-uri: $ru");
   pv_printf("$avp(i:3)", "from uri: $fu");

raise_event(string[, avp[, avp]])

Cria apartir do script um evento na interface de eventos do OpenSIPS, o primeiro parametro é uma string que indica que o evento deve ser criado, os dois outros parametros devem ser AVP's e eles são opcionais, se apenas um estiver presente este deve conter os valores que serão atrelados ao evento, se os dois valores forem especificados o primeiro deve conter o nome dos atributos e o segundo os valores que serão atrelados ao evento.

Esta função ativa um evento para todos os assinantes daquele evento dependendo do método de transporte usado.

Exemplo de uso (criar um evento sem atributos)


raise_event("E_NO_PARAM");

Exemplo de uso (cria um evento com dois atributos)

$avp(attr-name) = "param1";
$avp(attr-name) = "param2";
$avp(attr-val) = 1;
$avp(attr-val) = "2"
raise_event("E_TWO_PARAMS", $avp(attr-name), $avp(attr-val));

remove_branch(pv|int)

Remove a perna (branch) informada, a perna que será removida pode ser informada por um inteiro ou uma pseudo-variavel, no momento que a perna é removida todas as pernas subsequentes serão deslocadas (ex: se a perna n é removida, então a anterior n+1 será a nova perna, a anterior n+2 passará a ser a n+1 e assim por diante)

Exemplo de uso (remove todas as branches que contenham na URI o hostname '127.0.0.1')

$var(i) = 0;
while ($(branch(uri)[$var(i)]) != null) {
   xlog("L_INFO","$$(branch(uri)[$var(i)])=[$(branch(uri)[$var(i)])]\n");
   if ($(branch(uri)[$var(i)]{uri.host}) == "127.0.0.1") {
       xlog("L_INFO","removing branch $var(i) with URI=[$(branch(uri)[$var(i)])]\n");
       remove_branch($var(i));
   } else {
       $var(i) = $var(i) + 1;
   }
}

return(int)

A função return() permite que você retorne um valor inteiro de um bloco de roteamento, você pode testar o valor retornado usando a variavel $retcode.

return(0) é o mesmo que exit()

Expressão booleana:

 * Negativo e ZERO é FALSE
 * Positivo é TRUE

Exemplo de uso:

route {
  if (route(2)) {
    xlog("L_NOTICE","method $rm is INVITE\n");
  } else {
    xlog("L_NOTICE","method $rm is REGISTER\n");
  };
}

route[2] {
  if (is_method("INVITE")) {
    return(1);
  } else if (is_method("REGISTER")) {
    return(-1);
  } else {
    return(0);
  };
}

resetdsturi()

Define o valor do campo dst_uri para NULL, o campo dst_uri normalmente é definido após loose_route() ou lookup("location") se o endereço de contato está atrás de NAT


Exemplo de uso:

   resetdsturi();

resetflag(int)

Reseta o valor de uma flag para o processamento atual (define o valor para 0), o valor para o parametro poder ser um número de 0 até 31.


Para saber mais veja a Documentação de Flag

Exemplo de uso

   resetflag(3);

resetbflag([branch_idx,] flag_idx)

Reseta a flag para uma perna especifica (define o valor para 0), o valor de flag_idx pode ser um número de 0 até 31, branch_idx identifica a perna para qual a flag será resetada, deve ser um numero positivo, a branch index 0 refere-se a RUR da branch em questão, se o parametro for omitido 0 será definido como padrão.

Para saber mais veja a Documentação de Flag

Exemplo de uso

    resetbflag(1,3);
    # or
    resetbflag(3); # same with resetbflag(0,3)


resetsflag(flag_idx)

Reseta uma flag de script (define o valor para 0), o valor the flag_idx pode ser um número de 0 até 31


Para saber mais veja a Documentação de Flag

Exemplo de uso

   resetsflag(2);

revert_uri()

Define a R-URI para o valor original de quando a mesma chegou no servidor (desfaz todas as alterações)


Exemplo de uso:

   revert_uri();

rewritehost() / sethost()

re-escreve o dominio da R-URI com o valor especificado no parametro da função, outras partes da R-URI como username , porta e os parametros URI permancem inalterados.

Exemplos de uso:

   rewritehost("1.2.3.4");

rewritehostport() / sethostport()

Re-escreve o dominio e porta da R-URI com o valor especificado no parametro da função, outras partes da R-URI como username e parametros de URI não são alterados

Rewrite the domain part and port of the R-URI with the value of function's parameter. Other parts of the R-URI like username and URI parameters remain unchanged.

Exemplo de uso:

   rewritehostport("1.2.3.4:5080");

rewriteuser(string) / setuser(string)

Re-escreve o username na R-URI com o valor do parametro.


Exemplo de uso:

   rewriteuser("newuser");

rewriteuserpass() / setuserpass()

Re-escreve a parte referente ao password da R-URI com o valor definido no parametro.


Exemplo de uso:

   rewriteuserpass("my_secret_passwd");

rewriteport() / setport()

Re-escreve/define a parte referente a porta da R-URI com o valor definido no parametro.


Exemplo de uso:

   rewriteport("5070");

rewriteuri(str) / seturi(str)

Re-escreve a URI recebida


Exemplo de uso:

   rewriteuri("sip:test@opensips.org");

route(name [, param1 [, param2 [, ...] ] ] )

Esta função é utiliza para chamar uma rota declarada no script, opcionalmente ela pode receber diversos parametros (até 7) que podem ser recuperados depois com a pseudo-variavel $param(idx).

O nome da rota deve ser um identificador, os parametros podem ser o mesmo ou inteiro, string ou mesmo pseudo-variaveis


Exemplo de uso:

  route(HANDLE_SEQUENTIALS);
  route(HANDLE_SEQUENTIALS, 1, "param", $var(param));


script_trace( log_level, pv_format_string[, info_string])

Esta função inicia um tracing no script , isso ajuda a melhor entender o fluxo de execução do script do OpenSIPS, como que função é executada, que linha é e etc.., no mais você também pode traçar os valores das pseudo-variaveis como o progresso da execução do script.

O bloco do script onde o tracing é ativado irá exibir uma linha para cada ação individual que é realizada (ex: atribuições, testes condicionais, funções de módulos, funções de core etc...), multiplas pseudo-variaveis podem ser monitoradas especificando no formato pv_format_string (ex: "$ru---$avp(var1)" ).

O log produzido por multiplas/diferentes regiões com tracert ativo podem ser diferenciadas (taggeadas) especificando uma string adicional (info_string) como terceiro parametro.

Para desativar o tracert do script apenas chama script_trace() , em todo caso o tracer será parado no fim da execução do script


Exemplo de uso:

   script_trace( 1, "$rm from $si, ruri=$ru", "me");

irá gerar a seguinte saída:

   [line 578][me][module consume_credentials] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
   [line 581][me][core setsflag] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
   [line 583][me][assign equal] -> (INVITE from 127.0.0.1 , ruri=sip:111111@opensips.org)
   [line 592][me][core if] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
   [line 585][me][module is_avp_set] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
   [line 589][me][core if] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
   [line 586][me][module is_method] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org)
   [line 587][me][module trace_dialog] -> (INVITE 127.0.0.1 , ruri=sip:tester@opensips.org)
   [line 590][me][core setflag] -> (INVITE from 127.0.0.1 , ruri=sip:tester@opensips.org) 


send(destination [, headers])

Envia a mensagem SIP original para um destino especifico em modo stateless, o destino deve ser especificado no formato [proto:]host[:port] , nenhuma alteração é realizada na mensagem, não é adicionado cabeçalho VIA a menos que você especifique, o host pode ser um IP ou hostname, os protocolos suportados são UDP, TCP e TLS (para TLS o suporte deve estar ativo no core), se proto ou port não forem especificados requisições de NAPTR e SRV serão realizadas (se possivel) para tentar identificar os dados. O parametro header deve terminar com '\r\n' e pode aceitar tanto texto puro quanto pseudo-variaveis.

O parametro é obrigatório e possue um formato de string.


Exemplo de uso:

  send("udp:10.10.10.10:5070");
  send("udp:10.10.10.10:5070", "Server: opensips\r\n");


serialize_branches(clear)

NOTA: não entendi muito bem o conceito e não achei a melhor forma pra traduzir, então pesço desculpas se estiver confuso

Coloca todas as pernas em um processamento paralelo (com append_branch() e incluindo a RURI atual) e prepara as mesmas para processamento isolado, a ordenação é feita aumentando a ordenação "q" , as pernas serializadas são internamente armazenadas em AVPs, você poderá receber os valores através da função next_branch()

NOTA: De acordo com a RFC3261, as pernas com o mesmo valor 'q' permanecerão separadas durante alguns processos da separação serial, isso irá resultar em uma combinação de separação serial e paralela).

NOTA: Esta função não ltera a RURI da mensagem, ela apenas converte de paralelo para serial

Se clear é definido para non-zero , todos os resultados de outras 'serialize_branches' (branches serializadas que ainda não foram utilizadas) serão deletadas antes de definir novas serialized branches.


Exemplo de uso:

  serialize_branches(1);


set_advertised_address(ip|string)

Mesmo que 'advertised_address' mas afeta apenas a mensagem atual, esta tem prioridade se a 'advertised_address' também está definida.


Exemplo de uso:

   set_advertised_address("opensips.org");


set_advertised_port(int)

Mesmo que 'advertised_port' mas tem efeito apenas a mensagme atual, possui prioridade sobre 'advertised_port'


Exemplo de uso:

   set_advertised_port(5080);

setdebug([level])

Altera o valor de debug do processo atual do script, se chamado sem parametro então o level de debug do processo será resetado para o level global, se for definido o parametro então o nivel será alterado no processo e então a alteração do debug geral (utilizando a MI por exemplo) não terá efeito sobre o mesmo, então tenha cuidado e tenha certeza de resetar o processo queando você terminar, esta função é muito útil se você estiver tracándo e debugando apenas uma parte especifica do código.


Exemplo de uso:

   debug= -1 # errors only
   .....
   {
     ......
     setdebug(4); # set the debug level of the current process to DBG
     uac_replace_from(....);
     setdebug(); # reset the debug level of the current process to the global level
     .......
   }

setdsturi(string)

Definie explicitamente o valor do campo dst_uri para o valor do parametro especificado, o parametro deve ser uma URI SIP valida.


Exemplo de uso

   setdsturi("sip:10.10.10.10:5090");

setflag(int)

Define uma flag para o processamento da mensagem atual, o valor do parametro pode ser um numero de 0 a 31, as flags são utilizadas para marcar a mensagem para processamento especifico (como accounting) ou para manter alguns statos (como mensagens autenticadas)

Example of usage:Exemplo de uso.

   setflag(3);


setbflag([branch_idx,] flag_idx)

Define uma flag para um branch especifica (define o valor para 1) , o valor de flag_idx pode ser um numero de 0 a 31, a branch_idx identifica a branch para qual a flag será aplicada, deve ser um numero positivo, index 0 refere-se a RURI da branch atual, se o parametro não for especificado o index 0 será utilizado.


Para saber mais veja a Documentação de Flag

Exemplo de uso

   setbflag(1,3);

ou

   setbflag(3); # same with setbflag(0,3)


setsflag(flag_idx)

Define uma flag de script (define para 0), o valor de falg_idx pode ser um numero de 0 a 31

Para saber mais veja a Documentação de Flag


Exemplo de uso

   setsflag(2);

strip(int)

Remove os primeiros N caracteres do campo username da R-URI (N é o valor do parametro)

Exemplo de uso:

   strip(3);

strip_tail(int)

Remove os ultimos N caracteres do campo username da R-URI (N é o valor do parametro)


Exemplo de uso:

 strip_tail(3);


subscribe_event(string, string [, int])

Assina (subscribe) uma aplicação externa para um certo evento para a interface de eventos do OpenSIPS, esta opção é utilizada para protocolos de transportes que não podem assinar (subscribe) por si mesmos (ex: event_rabbitmq) , esta função deve ser chamada apenas uma vez na startup_route se a assinatura (susbcription) não expira, ou em uma timer route se a assinatura deve ser renovado em algum momento.

O primeiro parametro é a sting que representa o nome do evento que uma aplicação externa deve ser notificada, o segundo parametro é a string que especifica o socket para a aplicação externa. veja que o socket deve seguir a syntax de um módulo de transporte carregado para interface de eventos (ex: event_datagram, event_rabbitmq), o último parametro é opcional e especifica o tempo de expiração da assinatura , se não está presente então a subscrição não irá expirar.

Exemplo de uso (assinante que nunca espira, notificado pelo módulo rabbitmq)

startup_route {
    subscribe_event("E_PIKE_BLOCKED", "rabbitmq:127.0.0.1/pike");
}

Exemplo de uso (assinante expira em 5 segundos, notificado via udp)

timer_route[event_subscribe, 4] {
    subscribe_event("E_PIKE_BLOCKED", "udp:127.0.0.1:5051", 5);
}

use_blacklist(string)

Ativa a blacklist de dns para o nome recebido no parametro, o proposito primario é prevenir enviar request para IP criticos (como gateways) devido ao DNS ou prevenir enviar chamadas para destinos que estão (temporario ou permanentemente) indisponiveis.


   use_blacklist("pstn-gws");

Voltar