jain.protocol.ip.sip.header
Class ViaHeader

java.lang.Object
  |
  +--jain.protocol.ip.sip.header.Header
        |
        +--jain.protocol.ip.sip.header.GeneralHeader
              |
              +--jain.protocol.ip.sip.header.ViaHeader

public final class ViaHeader

extends GeneralHeader

This class represents the Via general-header. ViaHeaders indicates the path taken by the RequestMessage so far. This prevents RequestMessage looping and ensures ResponseMessages take the same path as the RequestMessages, which assists in firewall traversal and other unusual routing situations.

RequestMessages

The client originating the RequestMessage must insert into the RequestMessage a ViaHeader containing its host name or network address and, if not the default port number, the port number at which it wishes to receive ResponseMessages. (Note that this port number can differ from the UDP source port number of the RequestMessage.) A fully-qualified domain name is recommended. Each subsequent proxy server that sends the RequestMessage onwards must add its own additional ViaHeader before any existing ViaHeaders. A proxy that receives a redirection ResponseMessage and then searches recursively, must use the same ViaHeaders as on the original proxied RequestMessage.

A proxy should check the top-most ViaHeader to ensure that it contains the sender's correct network address, as seen from that proxy. If the sender's address is incorrect, the proxy must add an additional received attribute.

A host behind a network address translator (NAT) or firewall may not be able to insert a network address into the ViaHeader that can be reached by the next hop beyond the NAT. Use of the received attribute allows SIP RequestMessages to traverse NAT's which only modify the source IP address. NAT's which modify port numbers, called Network Address Port Translator's (NAPT) will not properly pass SIP when transported on UDP, in which case an application layer gateway is required. When run over TCP, SIP stands a better chance of traversing NAT's, since its behavior is similar to HTTP in this case (but of course on different ports).

A proxy sending a RequestMessage to a multicast address must add the maddr parameter to its ViaHeader, and should add the ttl parameter. If a server receives a RequestMessage which contained an maddr parameter in the topmost ViaHeader, it should send the ResponseMessage to the multicast address listed in the maddr parameter.

If a proxy server receives a RequestMessage which contains its own address in a ViaHeader, it must respond with a LOOP_DETECTED ResponseMessage.

A proxy server must not forward a RequestMessage to a multicast group which already appears in any of the ViaHeaders. This prevents a malfunctioning proxy server from causing loops. Also, it cannot be guaranteed that a proxy server can always detect that the address returned by a location service refers to a host listed in the ViaHeader list, as a single host may have aliases or several network interfaces.

Receiver-tagged Via Headers

Normally, every host that sends or forwards a RequestMessage adds a ViaHeader indicating the path traversed. However, it is possible that Network Address Translators (NATs) changes the source address and port of the RequestMessage (e.g., from net-10 to a globally routable address), in which case the Via header field cannot be relied on to route replies. To prevent this, a proxy should check the top-most ViaHeader to ensure that it contains the sender's correct network address, as seen from that proxy. If the sender's address is incorrect, the proxy must add a received parameter to the ViaHeader inserted by the previous hop. Such a modified ViaHeader is known as a receiver-tagged ViaHeader.

ResponseMessages

ViaHeaders in ResponseMessages are processed by a proxy or UAC according to the following rules:

The first ViaHeader should indicate the proxy or client processing this ResponseMessage. If it does not, discard the ResponseMessage. Otherwise, remove this ViaHeader.

If there is no second ViaHeader, this ResponseMessage is destined for this client. Otherwise, the processing depends on whether the ViaHeader contains a maddr parameter or is a receiver-tagged field.

If the second ViaHeader contains a maddr parameter, send the ResponseMessage to the multicast address listed there, using the port indicated in "sent-by", or port 5060 if none is present. The ResponseMessage should be sent using the TTL indicated in the ttl parameter, or with a TTL of 1 if that parameter is not present. For robustness, ResponseMessages must be sent to the address indicated in the maddr parameter even if it is not a multicast address.

If the second ViaHeader does not contain a maddr parameter and is a receiver-tagged ViaHeader , send the ResponseMessage to the address in the received parameter, using the port indicated in the port value, or using port 5060 if none is present.

If neither of the previous cases apply, send the ResponseMessage to the address indicated by the host value in the second ViaHeader.

User Agent and Redirect Servers

A UAS or redirect server sends a ResponseMessage based on one of the following rules:

If the first ViaHeader in the RequestMessage contains a maddr parameter, send the ResponseMessage to the multicast address listed there, using the port indicated, or port 5060 if none is present. The ResponseMessage should be sent using the TTL indicated in the ttl parameter, or with a TTL of 1 if that parameter is not present. For robustness, ResponseMessages must be sent to the address indicated in the maddr parameter even if it is not a multicast address.

If the address in the first ViaHeader differs from the source address of the packet, send the response to the actual packet source address, similar to the treatment for receiver-tagged ViaHeaders.

If neither of these conditions is true, send the ResponseMessage to the address contained in the host value. If the RequestMessage was sent using TCP, use the existing TCP connection if available.

ViaHeader Parameters

The defaults for protocol-name and transport are "SIP" and "UDP", respectively. The maddr parameter, designating the multicast address, and the ttl parameter, designating the time-to-live (TTL) value, are included only if the RequestMessage was sent via multicast. The received parameter is added only for receiver-added ViaHeaders For reasons of privacy, a client or proxy may wish to hide its ViaHeader information by encrypting it. The hidden parameter is included if this ViaHeader was hidden by the upstream proxy. Note that privacy of the proxy relies on the cooperation of the next hop, as the next-hop proxy will, by necessity, know the IP address and port number of the source host.

The branch parameter is included by every forking proxy. The token must be unique for each distinct RequestMessage generated when a proxy forks. CancelMessages must have the same branch value as the corresponding forked RequestMessage. When a ResponseMessage arrives at the proxy it can use the branch value to figure out which branch the ResponseMessage corresponds to. A proxy which generates a single RequestMessage (non- forking) may also insert the branch parameter. The identifier has to be unique only within a set of isomorphic RequestMessages.

Version:

0.6

Field Summary

static java.lang.String

token Token of ViaHeader

Fields inherited from class jain.protocol.ip.sip.header.Header

ENTITY_HEADER, GENERAL_HEADER, REQUEST_HEADER, RESPONSE_HEADER

Constructor Summary

ViaHeader(java.net.InetAddress host, int port, java.lang.String protocolVersion, int transport)
Creates a ViaHeader based on given host, port, protocol name, protocol version and transport

ViaHeader(java.net.InetAddress host, java.lang.String protocolVersion, int transport)
Creates a ViaHeader based on given host, protocol name, protocol version and transport

ViaHeader(java.lang.String concealedHost, java.lang.String protocolVersion, int transport)
Creates a ViaHeader based on given concealed host, protocol name, protocol version and transport

Method Summary

java.lang.Object	clone() Creates and returns a copy of ViaHeader
boolean	equals(ViaHeader viaHeader) Indicates whether some other ViaHeader is "equal to" this one
java.lang.String	getBranch() Gets branch of ViaHeader
java.lang.String	getComment() Gets comment of ViaHeader
java.lang.String	getConcealedHost() Gets concealed host of ViaHeader
java.net.InetAddress	getHost() Gets host of ViaHeader
java.net.InetAddress	getMAddr() Gets MAddr of ViaHeader
int	getPort() Gets port of ViaHeader
java.lang.String	getProtocolName() Gets protocol name of ViaHeader
java.lang.String	getProtocolVersion() Gets protocol version of ViaHeader
java.net.InetAddress	getReceived() Gets received of ViaHeader
int	getTransport() Gets transport of ViaHeader
int	getTTL() Gets TTL of ViaHeader
java.lang.String	getValue() Gets value of ViaHeader
boolean	hasBranch() Returns boolean value indicating if ViaHeader has branch
boolean	hasComment() Returns boolean value indicating if ViaHeader has comment
boolean	hasConcealedHost() Returns boolean value indicating if ViaHeader has concealed host
boolean	hasHost() Returns boolean value indicating if ViaHeader has host
boolean	hasMAddr() Returns boolean value indicating if ViaHeader has MAddr
boolean	hasPort() Returns boolean value indicating if ViaHeader has port
boolean	hasReceived() Returns boolean value indicating if ViaHeader has received
boolean	hasTTL() Returns boolean value indicating if ViaHeader has TTL
boolean	isHidden() Returns boolean value indicating if ViaHeader is hidden
void	removeBranch() Removes branch from ViaHeader
void	removeComment() Removes pcomment from ViaHeader
void	removeMAddr() Removes MAddr from ViaHeader
void	removePort() Removes product version from ViaHeader
void	removeReceived() Removes received from ViaHeader
void	removeTTL() Removes TTL from ViaHeader
void	setBranch(java.lang.String branch) Sets branch of ViaHeader
void	setComment(java.lang.String comment) Sets comment of ViaHeader
void	setConcealedHost(java.lang.String concealedHost) Sets concealed host of ViaHeader
void	setHidden(boolean hidden) Sets whether ViaHeader is hidden or not
void	setHost(java.net.InetAddress host) Sets host of ViaHeader
void	setMAddr(java.net.InetAddress mAddr) Sets MAddr of ViaHeader
void	setPort(int port) Sets port of ViaHeader
void	setProtocolName(java.lang.String protocolName) Sets protocol name of ViaHeader
void	setProtocolVersion(java.lang.String protocolVersion) Sets protocol version of ViaHeader
void	setReceived(java.net.InetAddress received) Sets received of ViaHeader
void	setTransport(int transport) Sets transport of ViaHeader
void	setTTL(int ttl) Sets TTL of ViaHeader

Methods inherited from class jain.protocol.ip.sip.header.Header

equals, getHeaderType, getToken, setValue, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

token

public static final java.lang.String token

Token of ViaHeader

Constructor Detail

ViaHeader

public ViaHeader(java.lang.String concealedHost,
                 java.lang.String protocolVersion,
                 int transport)
          throws java.lang.IllegalArgumentException

Creates a ViaHeader based on given concealed host, protocol name, protocol version and transport

Parameters:

concealedHost - concealed host

protocolVersion - protocol version e.g. "2.0"

transport - transport

Throws:

java.lang.IllegalArgumentException - if concealedHost, or protocolVersion is null or zero-length, or if transport is an invalid transport type

ViaHeader

public ViaHeader(java.net.InetAddress host,
                 java.lang.String protocolVersion,
                 int transport)
          throws java.lang.IllegalArgumentException

Creates a ViaHeader based on given host, protocol name, protocol version and transport

Parameters:

host - host

protocolVersion - protocol version e.g. "2.0"

transport - transport

Throws:

java.lang.IllegalArgumentException - if host is null, or if protocolVersion is null or zero-length, or if transport is an invalid transport type

ViaHeader

public ViaHeader(java.net.InetAddress host,
                 int port,
                 java.lang.String protocolVersion,
                 int transport)
          throws java.lang.IllegalArgumentException

Creates a ViaHeader based on given host, port, protocol name, protocol version and transport

Parameters:

host - host

port - port

protocolVersion - protocol version e.g. "2.0"

transport - transport

Throws:

java.lang.IllegalArgumentException - if host is null, or if port is negative, or if protocolVersion is null or zero-length, or if transport is an invalid transport type

Method Detail

isHidden

public boolean isHidden()

Returns boolean value indicating if ViaHeader is hidden

Returns:

boolean value indicating if ViaHeader is hidden

setHidden

public void setHidden(boolean hidden)

Sets whether ViaHeader is hidden or not

Parameters:

hidden - whether ViaHeader is hidden or not

hasPort

public boolean hasPort()

Returns boolean value indicating if ViaHeader has port

Returns:

boolean value indicating if ViaHeader has port

getPort

public int getPort()
            throws ParameterNotSetException

Gets port of ViaHeader

Returns:

port of ViaHeader

Throws:

ParameterNotSetException - if port does not exist

setPort

public void setPort(int port)
             throws java.lang.IllegalArgumentException,
                    SipException

Sets port of ViaHeader

Parameters:

port - port

Throws:

SipException - if host does not exist

java.lang.IllegalArgumentException - if port is negative

removePort

public void removePort()

Removes product version from ViaHeader

getProtocolName

public java.lang.String getProtocolName()

Gets protocol name of ViaHeader

Returns:

protocol name of ViaHeader

setProtocolName

public void setProtocolName(java.lang.String protocolName)
                     throws java.lang.IllegalArgumentException

Sets protocol name of ViaHeader

Parameters:

protocolName - protocol name

Throws:

java.lang.IllegalArgumentException - if protocolName is null or zero-length

getProtocolVersion

public java.lang.String getProtocolVersion()

Gets protocol version of ViaHeader

Returns:

protocol version of ViaHeader

setProtocolVersion

public void setProtocolVersion(java.lang.String protocolVersion)
                        throws java.lang.IllegalArgumentException

Sets protocol version of ViaHeader

Parameters:

protocolVersion - protocol version

Throws:

java.lang.IllegalArgumentException - if protocolVersion is null or zero-length

getTransport

public int getTransport()

Gets transport of ViaHeader

Returns:

transport of ViaHeadert

setTransport

public void setTransport(int transport)
                  throws java.lang.IllegalArgumentException

Sets transport of ViaHeader

Parameters:

transport - transport

Throws:

java.lang.IllegalArgumentException - if transport is not type defined in ListeningPoint

getHost

public java.net.InetAddress getHost()
                             throws ParameterNotSetException

Gets host of ViaHeader

Returns:

host of ViaHeader

Throws:

ParameterNotSetException - if host does not exist

setHost

public void setHost(java.net.InetAddress host)
             throws java.lang.IllegalArgumentException

Sets host of ViaHeader

Parameters:

host - host

Throws:

java.lang.IllegalArgumentException - if host is null

getConcealedHost

public java.lang.String getConcealedHost()
                                  throws ParameterNotSetException

Gets concealed host of ViaHeader

Returns:

concealed host of ViaHeader

Throws:

ParameterNotSetException - if concealed host does not exist

setConcealedHost

public void setConcealedHost(java.lang.String concealedHost)
                      throws java.lang.IllegalArgumentException

Sets concealed host of ViaHeader

Parameters:

concealedHost - concealed host

Throws:

java.lang.IllegalArgumentException - if concealedHost is null or zero-length

getComment

public java.lang.String getComment()
                            throws ParameterNotSetException

Gets comment of ViaHeader

Returns:

comment of ViaHeader

Throws:

ParameterNotSetException - if comment does not exist

hasComment

public boolean hasComment()

Returns boolean value indicating if ViaHeader has comment

Returns:

boolean value indicating if ViaHeader has comment

hasConcealedHost

public boolean hasConcealedHost()

Returns boolean value indicating if ViaHeader has concealed host

Returns:

boolean value indicating if ViaHeader has concealed host

hasHost

public boolean hasHost()

Returns boolean value indicating if ViaHeader has host

Returns:

boolean value indicating if ViaHeader has host

setComment

public void setComment(java.lang.String comment)

Sets comment of ViaHeader

Parameters:

xcommentx - comment

Throws:

java.lang.IllegalArgumentException - if comment is null or zero-length

removeComment

public void removeComment()

Removes pcomment from ViaHeader

setTTL

public void setTTL(int ttl)
            throws java.lang.IllegalArgumentException

Sets TTL of ViaHeader

Parameters:

ttl - TTL

Throws:

java.lang.IllegalArgumentException - if ttl is not between 0 and 255

removeTTL

public void removeTTL()

Removes TTL from ViaHeader

getTTL

public int getTTL()
           throws ParameterNotSetException

Gets TTL of ViaHeader

Returns:

TTL of ViaHeader

Throws:

ParameterNotSetException - if TTL does not exist

hasTTL

public boolean hasTTL()

Returns boolean value indicating if ViaHeader has TTL

Returns:

boolean value indicating if ViaHeader has TTL

setMAddr

public void setMAddr(java.net.InetAddress mAddr)
              throws java.lang.IllegalArgumentException

Sets MAddr of ViaHeader

Parameters:

mAddr - MAddr

Throws:

java.lang.IllegalArgumentException - if mAddr is null

removeMAddr

public void removeMAddr()

Removes MAddr from ViaHeader

getMAddr

public java.net.InetAddress getMAddr()
                              throws ParameterNotSetException

Gets MAddr of ViaHeader

Returns:

MAddr of ViaHeader

Throws:

ParameterNotSetException - if MAddr does not exist

hasMAddr

public boolean hasMAddr()

Returns boolean value indicating if ViaHeader has MAddr

Returns:

boolean value indicating if ViaHeader has MAddr

setReceived

public void setReceived(java.net.InetAddress received)
                 throws java.lang.IllegalArgumentException

Sets received of ViaHeader

Parameters:

received - received

Throws:

java.lang.IllegalArgumentException - if received is null

removeReceived

public void removeReceived()

Removes received from ViaHeader

getReceived

public java.net.InetAddress getReceived()
                                 throws ParameterNotSetException

Gets received of ViaHeader

Returns:

received of ViaHeader

Throws:

ParameterNotSetException - if received does not exist

hasReceived

public boolean hasReceived()

Returns boolean value indicating if ViaHeader has received

Returns:

boolean value indicating if ViaHeader has received

setBranch

public void setBranch(java.lang.String branch)

Sets branch of ViaHeader

Parameters:

branch - branch

Throws:

java.lang.IllegalArgumentException - if branch is null or zero-length

removeBranch

public void removeBranch()

Removes branch from ViaHeader

getBranch

public java.lang.String getBranch()
                           throws ParameterNotSetException

Gets branch of ViaHeader

Returns:

branch of ViaHeader

Throws:

ParameterNotSetException - if branch does not exist

hasBranch

public boolean hasBranch()

Returns boolean value indicating if ViaHeader has branch

Returns:

boolean value indicating if ViaHeader has branch

getValue

public java.lang.String getValue()

Gets value of ViaHeader

Overrides:

getValue in class Header

Returns:

value of ViaHeader

clone

public java.lang.Object clone()

Creates and returns a copy of ViaHeader

Overrides:

clone in class Header

equals

public boolean equals(ViaHeader viaHeader)

Indicates whether some other ViaHeader is "equal to" this one

Parameters:

viaHeader - the ViaHeader with which to compare