===== t_relay() clarification =====

The aim of this page is to clarify ''t_relay()'' behaviour and response codes in case of failure.

The documentation of ''t_relay()'' function is a bit confusing and not well detailed. Let's examine some sections of the [[http://www.kamailio.org/docs/modules/devel/tm.html#id2506628|function documentation]]:


=== Server transaction creation ===

> The coresponding transaction may or may not be already created. If not yet created, the function will automatically create it.

  * Is always a server transaction created?
    * //ibc: It seems that when ''t_relay()'' returns a negative code the transaction is not created.//
    * //jh: I have verified that transaction is created when t_relay() returns -4 or -6.  I suspect that transaction is also created with return value -5 and that it is NOT created when return value is -1, -2, or -3.//
  * Also in case of failure?
    * //ibc: The server transaction is not created in case of failure (negative return code of ''t_relay()''.//
  * If so, in which cases a server transaction is **not** created?
    * //ibc: In any negative response of ''t_relay()''.//
  * Does it depend on the destination transport?
    * //ibc: No.//


=== Returned error codes ===

> In case of error, the function returns the following codes: 
> -1 - generic internal error 
> -2 - bad message (parsing errors) 
> -3 - no destination available (no branches were added or request already cancelled) 
> -4 - bad destination (unresolvable address) 
> -5 - destination filtered (black listed) 
> -6 - generic send failed

  * When "//-1 - generic internal error//" is returned?
  * When "//-6 - generic send failed//" is returned?
  * Do the returned codes depend on the type of destination transport protocol?


=== Failure route invocation ===

  * In which cases ''failure_route'' is invoked when the destination transport is UDP?
    * //jh: I suspect that failure route is called only when t_relay() returns 1.//
    * //ibc: Checked that if the destination host is down or doesn't exist then t_relay(UDP) returns 1 and ''failure_route'' is executed. If the destination IP is not routable (not routes or default gw for it) then t_relay(UDP) returns -6 and ''failure_route'' is not executed.//
  * In which cases ''failure_route'' is invoked when the destination transport is TCP?
    * //jh: I suspect that failure route is called only when t_relay() returns 1.//
    * //ibc: Checked that if the destination host is down or doesn't exist then t_relay(TCP)://
      * //t_relay() returns nothing, auto-reply is generated and ''failure_route'' is **not** executed.//
      * //t_relay("0x02") returns false (-6) and ''failure_route'' is **not** executed. This is because the TCP connection couldn't be established.//


=== Transport erros ===

  * What is exactly a "transport error" when destination is UDP?
    * //jh: I suspect that UDP transport error results if sending out UDP packet fails, for example, when there is no route for the destination.//
  * What is exactly a "transport error" when destination is TCP?
    * //jh: I suspect that TCP transport error results if TCP connection to the destination cannot be establised.//
    * //ibc: This means that having a default gw, sending an UDP SIP request to a non responding IP will cause t_relay() to return 1 and failure_route to be invoked, while the same request to the same destination using TCP will cause t_relay() to return -6 and failure_route not to be invoked. This is because the UDP request was successfully sent while the TCP connection couldn't be established.//