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 408 “INVITE 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:

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