/ home / Documentation / 1.1.x / API / SIP API / OverSIP::SIP::Proxy

Class OverSIP::SIP::Proxy

An OverSIP::SIP::Proxy class instance is created for routing a received SIP request.

Class instance methods

new(proxy_profile=:default_proxy)

Creates an instance of OverSIP::SIP::Proxy with the given profile.

Parameters

proxy_profile
Must be a Symbol or String with a Proxy profile name existing in proxies.conf. Otherwise an OverSIP::RuntimeError is raised. If no value is given then :default_proxy profile is used.

Example

proxy = OverSIP::SIP::Proxy.new :proxy_out

route(request, dst_host=nil, dst_port=nil, dst_transport=nil)

Routes the given SIP request to the given destination (if given) or by following common SIP routing procedures with the information retrieved from the SIP request (Route headers or Request-URI).

OverSIP performs RFC 3263 and RFC 5626 (Outbound) procedures for choosing the destination(s) of the SIP request.

Parameters

request
The OverSIP::SIP::Request instance being routed.
dst_host
The destination host. A domain or IP (String).
dst_port
The destination port (Fixnum).
dst_transport
The transport to use for sending the request (:udp, :tcp or :tls Symbols).

Examples

proxy.route request

proxy.route request, "1.2.3.4", 9060, :tcp

proxy.route request, "oversip.net"

on_provisional_response(&block)

User programmable callback for processing SIP provisional responses (status code between 101 and 199).

Block parameters

response
The received OverSIP::SIP::Response instance.

Example

proxy.on_provisional_response do |response|
  log_info "received a provisional response with status code #{response.status_code}"
end

on_success_response(&block)

User programmable callback for processing SIP final responses with status code between 200 and 299.

Block parameters

response
The received OverSIP::SIP::Response instance.

Example

proxy.on_success_response do |response|
  log_info "received a final response with status code #{response.status_code}"
end

on_failure_response(&block)

User programmable callback for processing SIP final responses with status code between 300 and 699.

Block parameters

response
The received OverSIP::SIP::Response instance.

Example

proxy.on_failure_response do |response|
  log_info "received a final response with status code #{response.status_code}"
end

on_canceled(&block)

User programmable callback for the case in which the INVITE transaction has been canceled by the caller (by sending a CANCEL request).

Example

proxy.on_canceled do
  log_info "canceled by the peer"
end

on_invite_timeout(&block)

User programmable callback for the case in which the INVITE client transaction does not receive a final response before Timer C expires (regardless 100 and/or provisional responses have been received).

When this occurs OverSIP automatically generates a 408 “INVITE Timeout” SIP response.

Example

proxy.on_invite_timeout do
  log_info "INVITE timeout, no final response before Timer C expires."
end

on_error(&block)

User programmable callback for processing an error sending the SIP request (which means that the SIP request was not sent).

Block parameters

status_code
The SIP status code (Fixnum) of the internally generated response.
reason_phrase
The reason phrase (String) of the internally generated response.

The callback is called in the following cases:

Error Description Status Code Reason Phrase
Client transaction timeout. Timer B for INVITE request expires or Timer F for non-INVITE request expires. 408 “Client Timeout”
Connection error (for TCP and TLS). 500 “Connection Error”
Server TLS certificate was not validated. 500 “TLS Validation Failed”
Destination belongs to an Outbound TCP/TLS/WS/WSS connection but such a connection is closed. 430 “Flow Failed”
Unresolvable destination, RFC 3263 procedures failed for the request destination. 404 “No DNS Resolution”
Unsupported URI scheme. 416 “Unsupported URI scheme”
Unsupported transport. 478 “Unsupported transport”
Destination requires unsupported IPv4. 478 “Destination Requires Unsupported IPv4”
Destination requires unsupported IPv6. 478 “Destination Requires Unsupported IPv6”
Destination requires unsupported DNS resolution. 478 “Destination Requires Unsupported DNS Resolution”
Destination requires unsupported DNS resolution. 478 “Destination Requires Unsupported DNS Resolution”

Example

proxy.on_error do |status_code, reason_phrase|
  log_info "error sending the request: #{status_code} #{reason_phrase}"
end

drop_response

Drops the received response (so it is not forwarded upstream). This is useful for implementing SIP serial forking or for replacing a final response received from downstream.

Example

proxy.on_failure_response do |response|
  if response.status_code == 486
    log_info "user busy, forwarding to voicemail server"
    proxy.drop_response
    proxy.route request, "voicemail.example.net", 5060
  elsif response.status_code == 500
    proxy.drop_response
    request.reply 480, "Destination Not Available"
  end
end

proxy.route request

/ home / Documentation / 1.1.x / API / SIP API / OverSIP::SIP::Proxy