Class OverSIP::SIP::Uri

An instance of the OverSIP::SIP::Uri class contains a parsed URI.

Given the following parsed URIs (OverSIP::SIP::Uri instances), OverSIP provides the methods below for retrieving information from them:

sip_uri

sip:%63lice@ATLANTA.com:5060;Transport=TCP;FOO=123;baz?X-Header-1=qwe

tel_uri

Tel:(94)-499-12-12;Phone-Context=+34;FOO=bar

http_uri

http://www.oversip.net/documentation/

Class instance methods

unknown_scheme?

Returns true if the URI scheme is not :sip, :sips or :tel (so it contains a String value rather than a known Symbol).

scheme

Gets the scheme of the URI. If it is a known scheme then it has a Symbol value (:sip, :sips or :tel). Otherwise it is a String (i.e. "http").

Example

sip_uri.scheme
#=> :sip

tel_uri.scheme
#=> :tel

http_uri.scheme
#=> "http"

scheme=(value)

Modifies the scheme of the URI. If the original URI scheme was unknown then this method does nothing.

Parameters

value

The new scheme. It can be a Symbol (:sip, :sips or :tel) or a String (i.e. "http").

Example

sip_uri.scheme = :sips
#=> :sips

tel_uri.scheme = :tel
#=> :tel

http_uri.scheme = :sip
#=> nil

user

Gets the SIP URI user part (String) or the TEL URI number (String). When a SIP URI the user part is hexadecimal unescaped, when a TEL URI the visual separators (-, ., (, )) are removed.

Returns nil if the URI scheme is unknown or if the SIP URI has no user part.

Example

sip_uri.user
#=> "alice"

tel_uri.user
#=> "944991212"

http_uri.user
#=> nil

number

Alias for user() method.

user=(value)

Modifies the URI user part. If the URI scheme is unknown then this method does nothing.

Parameters

value

The new user (String).

Example

sip_uri.user = "bob"
#=> "bob"

tel_uri.user = "1234"
#=> "1234"

http_uri.user = "foo"
#=> nil

number=(value)

Alias for user=() method.

host

Gets the SIP URI host part (String). When the SIP URI host part is a domain this method returns its lowcase value.

Returns nil if the URI scheme is not :sip or :sips.

Example

sip_uri.host
#=> "atlanta.com"

tel_uri.host
#=> nil

http_uri.host
#=> nil

domain

Alias for host() method.

host=(value)

Modifies the SIP URI host part (and updates the SIP URI host_type). If the URI scheme is not :sip or :sips then this method does nothing.

Parameters

value

The new host (String).

Example

sip_uri.host = "oversip.net"
#=> "oversip.net

tel_uri.host = "oversip.net"
#=> nil

http_uri.host = "oversip.net"
#=> nil

domain=(value)

Alias for host=() method.

host_type

Gets the type of the SIP URI host part (:domain, :ipv4 or :ipv6_reference Symbols).

Returns nil if the URI scheme is not :sip or :sips.

Example

sip_uri.host_type
#=> :domain

tel_uri.host_type
#=> nil

http_uri.host_type
#=> nil

port

Gets the SIP URI port (Fixnum or nil if not present).

Returns nil if the URI scheme is not :sip or :sips.

Example

sip_uri.port
#=> 5060

tel_uri.port
#=> nil

http_uri.port
#=> nil

port=(value)

Modifies the SIP URI port. If the URI scheme is not :sip or :sips then this method does nothing.

Parameters

value

The new port (Fixnum or nil for removing the port from the SIP URI).

Example

sip_uri.port = 9090
#=> port

tel_uri.port = 9090
#=> nil

http_uri.port = 9090
#=> nil

params

Returns a Hash with the SIP or TEL URI parameters.

Returns an empty Hash if the URI scheme is unknown.

Example

sip_uri.params
#=> {"Transport"=>"TCP", "FOO"=>"123", "baz"=>nil}

tel_uri.params
#=> {"Phone-Context"=>"+34", "FOO"=>"bar"}

http_uri.params
#=> nil

set_param=(param, value)

Creates or replaces a SIP or TEL URI parameter. If the URI scheme is unknown then this method does nothing.

NOTE: Don’t use this method for setting (or removing) the ;transport parameter in a SIP URI or the ;phone-context parameter in a TEL URI. Instead use the methods transport_param=() and phone_context_param=() below.

Parameters

param

The parameter name (String).

value

The parameter value (String or nil for creating a parameter with no value).

Example

sip_uri.set_param "new-param", "1234"
#=> "1234"

tel_uri.set_param "new-param", "1234"
#=> "1234"

http_uri.set_param "new-param", "1234"
#=> nil

del_param(param)

Deletes a SIP or TEL URI parameter and returns its value (String) or nil if such a parameter does not exist in the URI. If the URI scheme is unknown then this method does nothing.

Parameters

param

The parameter name (String).

Example

sip_uri.del_param "foo"
#=> "123"

tel_uri.del_param "abc"
#=> false

http_uri.del_param "abc"
#=> nil

transport_param

Returns the value of the ;transport parameter in a SIP URI. The value can be :udp, :tcp, :tls, :ws or :sctp Symbols, or a String when it is an unknown transport.

Returns nil if the URI scheme is not :sip or :sips.

Example

sip_uri.transport_param
#=> :tcp

tel_uri.transport_param
#=> nil

http_uri.transport_param
#=> nil

transport_param=(value)

Creates or replaces the ;transport parameter in a SIP URI. If the original URI scheme is not :sip or :sips then this method does nothing.

Parameters

value

It can be :udp, :tcp, :tls, :ws or :sctp Symbols, or a String when it is an unknown transport. If it is nil then the parameter is removed from the SIP URI.

Example

sip_uri.transport_param = :udp
#=> :udp

tel_uri.transport_param = :udp
#=> nil

http_uri.transport_param = :udp
#=> nil

phone_context_param

Returns the value (String) of the ;phone-context parameter in a TEL URI.

Returns nil if the URI scheme is not :tel.

Example

sip_uri.phone_context_param
#=> nil

tel_uri.phone_context_param
#=> "+34"

http_uri.phone_context_param
#=> nil

phone_context_param=(value)

Creates or replaces the ;phone-context parameter in a TEL URI. If the original URI scheme is not :tel then this method does nothing.

Parameters

value

A String or nil for removing the parameter from the TEL URI.

headers

Returns the full headers component of a SIP URI as a String (or nil if the SIP URI has no headers).

Returns nil if the URI scheme is not :sip or :sips.

Example

sip_uri.headers
#=> "?X-Header-1=qwe"

tel_uri.headers
#=> nil

http_uri.headers
#=> nil

headers=(value)

Sets the full headers component of a SIP URI. If the URI scheme is not :sip or :sips then this method does nothing.

value

The SIP URI headers (String).

Example

sip_uri.headers = "?X-Header-1=AAA&X-Header-2=BBB"
#=> "?X-Header-1=AAA&X-Header-2=BBB"

tel_uri.headers = "?X-Header-1=AAA&X-Header-2=BBB"
#=> nil

http_uri.headers = "?X-Header-1=AAA&X-Header-2=BBB"
#=> nil

uri

Returns the full URI value as a String. If any of the fields of the URI has been modified (via the above methods) the URI is updated.

Example

sip_uri.uri
#=> "sips:bob@oversip.net:9090;transport=TCP;baz;new-param=1234?X-Header-1=AAA&X-Header-2=BBB"

tel_uri.uri
#=> "tel:1234;phone-context=+34;foo=bar;new-param=1234"

http_uri.uri
#=> "http://www.oversip.net/documentation/"

aor

NEW in 1.2.x

Returns the simplified AoR (String) of the URI:

• For a SIP URI it returns sip:user@domain by ignoring port, parameters, and forcing SIP scheme regardless the URI has SIPS scheme.
• For a TEL URI it returns tel:number by ignoring parameters.
• For other schemes it returns nil.

Example

sip_uri.aor
#=> "sip:bob@oversip.net"

tel_uri.aor
#=> "tel:1234"

http_uri.aor
#=> nil