– Kamailio SIP Server –

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 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.