Class OverSIP::SIP::Client

The parent class of OverSIP::SIP::Proxy and OverSIP::SIP::Uac. This class is the responsible of performing SIP routing procedures and managing client transactions.

Class instance methods

on_provisional_response(&block)

NEW in 1.4.x

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

Multiple callbacks can be given by calling multiple times to this method. Callbacks will be executed in the order they were set.

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)

NEW in 1.4.x

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

Multiple callbacks can be given by calling multiple times to this method. Callbacks will be executed in the order they were set.

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)

NEW in 1.4.x

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

Multiple callbacks can be given by calling multiple times to this method. Callbacks will be executed in the order they were set.

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

NEW in 1.4.x

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 408INVITE Timeout” SIP response.

Multiple callbacks can be given by calling multiple times to this method. Callbacks will be executed in the order they were set.

Example

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

on_target(&block)

NEW in 1.4.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.

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

Multiple callbacks can be given by calling multiple times to this method. Callbacks will be executed in the order they were set.

Block parameters

target
An instance of OverSIP::SIP::RFC3263::Target.

Example

proxy.on_target do |target|
  log_info "request will be sent to #{target.transport}:#{target.ip}:#{target.port}"
end

on_error(&block)

NEW in 1.4.x

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

Multiple callbacks can be given by calling multiple times to this method. Callbacks will be executed in the order they were set.

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.
code
The internal cause of the error (Symbol).

The callback is called in the following cases:

Error Description Status Code Reason Phrase Code
Client transaction timeout. Timer B for INVITE request expires or Timer F for non-INVITE request expires. 408 “Client Timeout” :client_timeout
Connection error (for TCP and TLS). 500 “Connection Error” :connection_error
Server TLS certificate was not validated. 500 TLS Validation Failed” :tls_validation_failed
Destination belongs to an Outbound TCP/TLS/WS/WSS connection but such a connection is closed. 430 “Flow Failed” :flow_failed
Unresolvable destination, RFC 3263 procedures failed for the request destination. 404 “No DNS Resolution” :no_dns_resolution
Unsupported URI scheme. 416 “Unsupported URI scheme” :unsupported_uri_scheme
Unsupported transport. 478 “Unsupported transport” :unsupported_transport
Destination requires unsupported IPv4. 478 “Destination Requires Unsupported IPv4” :no_ipv4
Destination requires unsupported IPv6. 478 “Destination Requires Unsupported IPv6” :no_ipv6
Destination requires unsupported DNS resolution. 478 “Destination Requires Unsupported DNS Resolution” :no_dns
Destination requires unsupported DNS resolution. 478 “Destination Requires Unsupported DNS Resolution” :no_dns
Destination aborted (via abort_routing() method). 403 “Destination Aborted” :destination_aborted
Destination blacklisted (via add_target_to_blacklist() method. 403 “Destination Blacklisted” :destination_blacklisted

Example

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

clear_on_provisional_response

NEW in 1.4.x

Clear all the callbacks passed to on_provisional_response().

clear_on_success_response

NEW in 1.4.x

Clear all the callbacks passed to on_success_response().

clear_on_failure_response

NEW in 1.4.x

Clear all the callbacks passed to on_failure_response().

clear_on_invite_timeout

NEW in 1.4.x

Clear all the callbacks passed to on_invite_timeout().

clear_on_error

NEW in 1.4.x

Clear all the callbacks passed to on_error().

clear_on_target

NEW in 1.4.x

Clear all the callbacks passed to on_target().

clear_callbacks

NEW in 1.4.x

Clear all the callbacks.

abort_routing

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 Aborted” internal response (with code :destination_aborted) 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

add_target_to_blacklist(timeout=nil, status_code=403, reason_phrase="Destination Blacklisted")

This method should be used within the on_target() callback. By calling it the current target is blacklisted for future requests being sent to the same destination (transport, IP and port).

NOTE: The current SIP request is not rejected after calling this method. For that call to abort_routing().

Parameters

timeout
Duration (in seconds) of the target in the blacklist (Fixnum between 2 and 600). By default the blacklist_time parameter value of the current Proxy profile.
status_code
SIP status code (Fixnum) of the autogenerated response for future requests to same target.
reason_phrase
Reason phrase (String) of the autogenerated response for future requests to same target.

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 and
                blacklist this target for 500 seconds"
    proxy.abort_routing
    proxy.add_target_to_blacklist 500, 403, "Never here!"
  end
end

proxy.route request