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_target(&block)

NEW in 1.2.x

User programmable callback invoked for each destination target obtained via RFC 3263 procedures. The callback is invoked just before sending the request to the target. The user can here inspect the chosen destination of the request (IP family, IP, port and SIP transport) and decide to abort the routing by calling the abort_routing() method of the Proxy instance.

This callback is not called when the request destination is an Outbound connection already established by the destination peer.

Block parameters

ip_type

Target IP family (:ipv4 or :ipv6 Symbols).

ip

Target IP address (String).

port

Target port (Fixnum).

transport

Target SIP transport (:udp, :tcp or :tls Symbols).

Example

proxy.on_target do |ip_type, ip, port, transport|
  log_info "request will be sent to #{transport}:#{ip}:#{port}"
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:

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

abort_routing

NEW in 1.2.x

This method must be used within the on_target() callback. By calling it the request routing is aborted (no other targets obtained via DNS are tryed) and a 403 “Destination Not Allowed” internal response sent to the on_error() callback (if set).

The method is useful to avoid requests being routed to not allowed destinations.

Example

proxy.on_target do |target|
  if target.ip == MY_PSTN_GW_IP
    log_notice "attempt to reach the PSTN gateway without consent, abort routing"
    proxy.abort_routing
  end
end

proxy.route request