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 methods

parse(uri)

NEW in 1.4.x

Parses the given uri into a OverSIP::SIP::Uri instance and returns it.

Parameters

uri
String containing the URI to parse.

Examples

uri = OverSIP::SIP::Uri.parse "sip:ibc@aliax.net"
uri = OverSIP::SIP::Uri.parse "tel:+123456789"

Class instance methods

initialize(scheme=:sip, user=nil, host=nil, port=nil)

Initializer method for the OverSIP::SIP::Uri instance. It should be just used for SIP, SIPS or TEL URI’s.

Parameters

scheme
URI scheme (:sip, :sips or :tel Symbol).
user
SIP URI username or TEL URI number (String).
host
SIP URI host value.
port
SIP URI port value.

Examples

uri = OverSIP::SIP::Uri.new :sip, "alice", "example.net"
uri = OverSIP::SIP::Uri.new :tel, "+12345678"

sip?

Returns true if the URI scheme is :sip or :sips.

tel?

Returns true if the URI scheme is :tel.

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

has_param?(param)

NEW in 1.4.x

Returns true if the given parameter exists in the URI, false otherwise. If the URI scheme is unknown then this method returns nil.

Parameters

param
The parameter name (String).

Example

sip_uri.has_param? "foo"
#=> true

tel_uri.has_param? "LALALA"
#=> false

http_uri.has_param? "foo"
#=> nil

get_param(param)

Gets the given parameter value in the URI (or nil if not present). If the URI scheme is unknown then this method returns nil.

Parameters

param
The parameter name (String).

Example

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

tel_uri.get_param "foo"
#=> "bar"

http_uri.get_param "foo"
#=> 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

clear_params

NEW in 1.4.x

Removes all the parameters from the URI. If the URI scheme is unknown then this method does nothing.

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

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