Class OverSIP::SIP::Message

The parent class of both OverSIP::SIP::Request and OverSIP::SIP::Response thus it can be a SIP request or a SIP response.

Having the following INVITE message stored into a variable message (an OverSIP::SIP::Message instance), OverSIP provides the methods below for retrieving information from the message:

INVITE sip:bob@biloxi.com SIP/2.0
Via: SIP/2.0/UDP 192.168.200.123:5060;branch=z9hG4bKkdjuw;rport
From: "Alice" <sip:alice@atlanta.com>;tag=938asdi
To: "Bob" <sip:bob@biloxi.com>
Route: <sip:proxy.atlanta.com;lr>
Max-Forwards: 70
Call-ID: dsh8jkzxxlkj
CSeq: 234234 INVITE
Content-Type: application/sdp
Supported: path, outbound
Supported: GRUU
Contact: <sip:alice@192.168.200.123:5060;gr=urn:uuid:f81-7dec-14a06cf1;ob>"
X-Foo: AAA, Bbb
x-foo: ccc

v=0
o=abcd 29739 7272939 IN IP4 192.168.200.123
s=-
c=IN IP4 192.168.200.123
t=0 0
m=audio 49217 RTP/AVP 0 12
m=video 3227 RTP/AVP 31
a=rtpmap:31 LPC

Class instance methods

request?

Returns true if the message is an instance of OverSIP::SIP::Request.

response?

Returns true if the message is an instance of OverSIP::SIP::Response.

source_ip_type

Gets the IP type (:ipv4 or :ipv6 Symbols) of the message’s source address.

Example

message.source_ip_type
#=> :ipv4

source_ip

Gets the source IP (String) of the message.

Example

message.source_ip
#=> "203.0.113.22"

source_port

Gets the source port (Fixnum) of the message.

Example

message.source_port
#=> 35105

transport

Gets the SIP transport (:udp, :tcp, :tls, :ws or :wss Symbols) from which the message has been received.

Example

message.transport
#=> :udp

udp?

Returns true if transport is :udp.

tcp?

Returns true if transport is :tcp.

tls?

Returns true if transport is :tls.

ws?

Returns true if transport is :ws.

wss?

Returns true if transport is :wss.

websocket?

Returns true if transport is :ws or :wss.

sip_method

Gets the SIP method of the message (extracted from the Request line in a SIP request and from the CSeq header in a SIP response). If it is a known SIP method then it is a Symbol (i.e. :INVITE, :REGISTER, :MESSAGE). Otherwise it is a String (i.e. "CHICKEN").

Example

message.sip_method
#=> :INVITE

unknown_method?

Returns true if the message SIP method is unknown (so sip_method contains a String instead of a Symbol).

call_id

Gets the value (String) of the Call-ID header in the message.

Example

message.call_id
#=> "dsh8jkzxxlkj"

cseq

Gets the value (Fixnum) of the CSeq header in the message.

Example

message.cseq
#=> 234234

via_branch

Gets the Via ;branch parameter (String) of the message.

Example

message.via_branch
#=> "z9hG4bKkdjuw"

via_rport?

Returns true if the top Via header contains a ;rport parameter.

Example

message.via_rport?
#=> true

from

Gets the From header parsed as a OverSIP::SIP::NameAddr instance.

NEW in 1.2.x: If the fields of the OverSIP::SIP::NameAddr instance are modified in a SIP request then the From header will be rewritten when the request is forwarded and changes to the From header will be reverted when forwarding responses upstream.

Example

message.from.user
#=> "alice"

from_tag

Gets the From header ;tag value (String). nil if there is no From ;tag.

Example

message.from_tag
#=> "938asdi"

to

Gets the To header parsed as a OverSIP::SIP::NameAddr instance.

NEW in 1.2.x: If the fields of the OverSIP::SIP::NameAddr instance are modified in a SIP request then the To header will be rewritten when the request is forwarded and changes to the To header will be reverted when forwarding responses upstream.

Example

message.to.display_name
#=> "Bob"

to_tag

Gets the To header ;tag value (String). nil if there is no To ;tag.

Example

message.to_tag
#=> nil

contact

Gets the Contact header parsed as a OverSIP::SIP::NameAddr instance.

NOTE: The Contact header is parsed just in case the message contains a single Contact header field containing a single SIP URI. Otherwise this method returns nil.

NEW in 1.2.x: If the fields of the OverSIP::SIP::NameAddr instance are modified in a SIP request then the Contact header will be rewritten when the request is forwarded.

Example

message.contact.host
#=> "192.168.200.123"

contact_params

Gets the Contact header parameters (in a single String which starts with “;”). nil if the Contact header has no parameters.

NOTE: The Contact header is parsed just in case the message contains a single Contact header field containing a single SIP URI. Otherwise this method returns nil.

Example

message.contact_params
#=> nil

routes

Gets an Array of OverSIP::SIP::NameAddr instances with all the parsed Route values in the message.

Example

message.routes.size
#=> 1

message.routes[0].host
#=> "proxy.atlanta.com"

require

Gets an Array with the lowcase value (String) of each Require option tag in the message. It is nil if there are no Require option tags.

Example

message.require
#=> nil

proxy_require

Gets an Array with the lowcase value (String) of each Proxy-Require option tag in the message. It is nil if there are no Proxy-Require option tags.

Example

message.proxy_require
#=> nil

supported

Gets an Array with the lowcase value (String) of each Supported option tag in the message. It is nil if there are no Supported option tags.

Example

message.supported
#=> ["path", "outbound", "gruu"]

body

Gets the body (String or nil) of the message.

Example

message.body
#=> "v=0
o=abcd 29739 7272939 IN IP4 192.168.200.123
s=-
c=IN IP4 192.168.200.123
t=0 0
m=audio 49217 RTP/AVP 0 12
m=video 3227 RTP/AVP 31
a=rtpmap:31 LPC"

body=(value)

Sets the body of the message. This method can be applied to SIP requests and responses. Before forwarding the message, OverSIP checks the body size and updates the Content-Length header with the proper value.

Parameters

value
The new body (String) or nil for removing it.

Example

message.body = "HELLO"

has_header?(header_field)

Returns true if the given header field exists, false otherwise.

Parameters

header_field
The name of the header to search for. It’s automatically normalized.

Example

message.has_header? "X-FOO"
#=> true

header_top(header_field)

Returns the first value (String) of the given header field, nil if it does not exist.

Parameters

header_field
The name of the header to search for. It’s automatically normalized.

Example

message.header_top "X-FOO"
#=> "AAA, Bbb"

header_all(header_field)

Returns an Array with all the values (String) of the given header field, or an empty Array if such a header is not present.

Parameters

header_field
The name of the header to search for. It’s automatically normalized.

Example

message.header_all "X-FOO"
#=> ["AAA, Bbb", "ccc"]

set_header(header_field, value)

Creates a header field with the given value or entirely replaces the existing header fields with the new value.

Parameters

header_field
The name of the header to search for. It’s automatically normalized.
value
Can be a single value (String) or an Array of Strings.

Examples

message.set_header "X-BAZ", "Hello"
message.set_header "X-BAZ", ["Hello", "Bye"]

delete_header(header_field)

Deletes all the headers with the given name and returns an Array with all the values (Strings).

Parameters

header_field
The name of the header to search for. It’s automatically normalized.

Example

message.delete_header "X-FOO"
#=> ["AAA, Bbb", "ccc"]

delete_header_top(header_field)

Removes the first value of the given header field. Returns the extracted value (String) or nil if such a header does not exist.

Parameters

header_field
The name of the header to search for. It’s automatically normalized.

Example

message.delete_header_top "X-FOO"
#=> "AAA, Bbb"

insert_header(header_field, value)

Inserts the given value in the first position of the given header field (or creates it if such a header does not exist).

Parameters

header_field
The name of the header to search for. It’s automatically normalized.
value
The header value (String).

Example

message.insert_header "X-FOO", "000"

append_header(header_field, value)

Appends the given value in the last position of the given header field (or creates it if such a header does not exist).

Parameters

header_field
The name of the header to search for. It’s automatically normalized.
value
The header value (String).

Example

message.append_header "X-FOO", "ZZZ"

replace_header_top(header_field, value)

Replaces the top value of the given header field with the given value (or creates it if such a header does not exist).

Parameters

header_field
The name of the header to search for. It’s automatically normalized.
value
The header value (String).

Example

message.replace_header_top "X-FOO", "AAAAAA"

close_connection

Closes the TCP/TLS/WS/WSS connection from with the message has been received (it does nothing in case of UDP transport).