JSIP API v1.2
November 2006

javax.sip.header
Interface ViaHeader

All Superinterfaces:
java.lang.Cloneable, Header, Parameters, java.io.Serializable

public interface ViaHeader
extends Parameters, Header

The Via header field indicates the transport used for the transaction and identifies the location where the response is to be sent. A Via header field value is added only after the transport that will be used to reach the next hop has been selected. When the UAC creates a request, it MUST insert a Via into that request. The protocol name and protocol version in the header field MUST be SIP and 2.0, respectively. The Via header field value MUST contain a branch parameter. This parameter is used to identify the transaction created by that request. This parameter is used by both the client and the server.

Branch Parameter:
The branch parameter value MUST be unique across space and time for all requests sent by the User Agent. The exceptions to this rule are CANCEL and ACK for non-2xx responses. A CANCEL request will have the same value of the branch parameter as the request it cancels. An ACK for a non-2xx response will also have the same branch ID as the INVITE whose response it acknowledges.

The uniqueness property of the branch ID parameter, to facilitate its use as a transaction ID, was not part of RFC 2543. The branch ID inserted by an element compliant with this specification MUST always begin with the characters "z9hG4bK". These 7 characters are used as a magic cookie (7 is deemed sufficient to ensure that an older RFC 2543 implementation would not pick such a value), so that servers receiving the request can determine that the branch ID was constructed in the fashion described by this specification (that is, globally unique). Beyond this requirement, the precise format of the branch token is implementation-defined. JSIP defines a convenience function to generate unique branch identifiers at Transaction.getBranchId()

A common way to create the branch value is to compute a cryptographic hash of the To tag, From tag, Call-ID header field, the Request-URI of the request received (before translation), the topmost Via header, and the sequence number from the CSeq header field, in addition to any Proxy-Require and Proxy-Authorization header fields that may be present. The algorithm used to compute the hash is implementation-dependent.

Via Processing Rules

Via Parameters: A Via header field value contains the transport protocol used to send the message, the client's host name or network address, and possibly the port number at which it wishes to receive responses. Transport protocols defined here are "UDP", "TCP", "TLS", and "SCTP". "TLS" means TLS over TCP. When a request is sent to a SIPS URI, the protocol still indicates "SIP", and the transport protocol is TLS. A Via header field value can also contain parameters such as "maddr", "ttl", "received", and "branch". A proxy sending a Request to a multicast address must add the maddr parameter to its ViaHeader, and should add the ttl parameter. If a server receives a Request which contained an maddr parameter in the topmost ViaHeader, it should send the Response to the multicast address listed in the maddr parameter. The received parameter is added only for receiver-added ViaHeaders.

Two Via header fields are equal if their sent-protocol and sent-by fields (including port) are equal, both have the same set of parameters, and the values of all parameters are equal.

Author:
BEA Systems, NIST

Field Summary
static java.lang.String NAME
          Name of ViaHeader
 
Method Summary
 boolean equals(java.lang.Object obj)
          Compare this ViaHeader for equality with another.
 java.lang.String getBranch()
          Gets the branch paramater of the ViaHeader.
 java.lang.String getHost()
          Returns the host part of this ViaHeader.
 java.lang.String getMAddr()
          Returns the value of the maddr parameter, or null if this is not set.
 int getPort()
          Returns the port part of this ViaHeader.
 java.lang.String getProtocol()
          Returns the value of the protocol used.
 java.lang.String getReceived()
          Gets the received paramater of the ViaHeader.
 int getRPort()
          Returns the rport part of this ViaHeader.
 java.lang.String getTransport()
          Returns the value of the transport parameter.
 int getTTL()
          Returns the value of the ttl parameter, or -1 if this is not set.
 void setBranch(java.lang.String branch)
          Sets the branch parameter of the ViaHeader to the newly supplied branch value.
 void setHost(java.lang.String host)
          Set the host part of this ViaHeader to the newly supplied host parameter.
 void setMAddr(java.lang.String mAddr)
          Sets the value of the maddr parameter of this ViaHeader.
 void setPort(int port)
          Set the port part of this ViaHeader to the newly supplied port parameter.
 void setProtocol(java.lang.String protocol)
          Sets the value of the protocol parameter.
 void setReceived(java.lang.String received)
          Sets the received parameter of ViaHeader.
 void setRPort()
          Set the rport part of this ViaHeader.
 void setTransport(java.lang.String transport)
          Sets the value of the transport.
 void setTTL(int ttl)
          Sets the value of the ttl parameter.
 
Methods inherited from interface javax.sip.header.Parameters
getParameter, getParameterNames, removeParameter, setParameter
 
Methods inherited from interface javax.sip.header.Header
clone, getName, hashCode, toString
 

Field Detail

NAME

static final java.lang.String NAME
Name of ViaHeader

See Also:
Constant Field Values
Method Detail

setHost

void setHost(java.lang.String host)
             throws java.text.ParseException
Set the host part of this ViaHeader to the newly supplied host parameter.

Parameters:
host - - the new value of the host of this ViaHeader
Throws:
java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the host value.

getHost

java.lang.String getHost()
Returns the host part of this ViaHeader.

Returns:
the string value of the host

setPort

void setPort(int port)
             throws InvalidArgumentException
Set the port part of this ViaHeader to the newly supplied port parameter.

Parameters:
port - - the new integer value of the port of this ViaHeader
Throws:
InvalidArgumentException - when the port value is not -1 and <1 or >65535

getPort

int getPort()
Returns the port part of this ViaHeader.

Returns:
the integer value of the port, -1 if not present

getTransport

java.lang.String getTransport()
Returns the value of the transport parameter.

Returns:
the string value of the transport paramter of the ViaHeader

setTransport

void setTransport(java.lang.String transport)
                  throws java.text.ParseException
Sets the value of the transport. This parameter specifies which transport protocol to use for sending requests and responses to this entity. The following values are defined: "udp", "tcp", "sctp", "tls", but other values may be used also.

Parameters:
transport - - new value for the transport parameter
Throws:
java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the transport value.

getProtocol

java.lang.String getProtocol()
Returns the value of the protocol used.

Returns:
the string value of the protocol paramter of the ViaHeader

setProtocol

void setProtocol(java.lang.String protocol)
                 throws java.text.ParseException
Sets the value of the protocol parameter. This parameter specifies which protocol is used, for example "SIP/2.0".

Parameters:
protocol - - new value for the protocol parameter
Throws:
java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the protocol value.

getTTL

int getTTL()
Returns the value of the ttl parameter, or -1 if this is not set.

Returns:
the integer value of the ttl parameter

setTTL

void setTTL(int ttl)
            throws InvalidArgumentException
Sets the value of the ttl parameter. The ttl parameter specifies the time-to-live value when packets are sent using UDP multicast.

Parameters:
ttl - - new value of the ttl parameter
Throws:
InvalidArgumentException - if supplied value is less than zero or greater than 255, excluding -1 the default not set value.

getMAddr

java.lang.String getMAddr()
Returns the value of the maddr parameter, or null if this is not set.

Returns:
the string value of the maddr parameter

setMAddr

void setMAddr(java.lang.String mAddr)
              throws java.text.ParseException
Sets the value of the maddr parameter of this ViaHeader. The maddr parameter indicates the server address to be contacted for this user, overriding any address derived from the host field.

Parameters:
mAddr - new value of the mAddr parameter
Throws:
java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the mAddr value.

getReceived

java.lang.String getReceived()
Gets the received paramater of the ViaHeader. Returns null if received does not exist.

Returns:
the string received value of ViaHeader

setReceived

void setReceived(java.lang.String received)
                 throws java.text.ParseException
Sets the received parameter of ViaHeader.

Parameters:
received - - the newly supplied received parameter.
Throws:
java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the received value.

getBranch

java.lang.String getBranch()
Gets the branch paramater of the ViaHeader. Returns null if branch does not exist.

Returns:
the string branch value of ViaHeader

setBranch

void setBranch(java.lang.String branch)
               throws java.text.ParseException
Sets the branch parameter of the ViaHeader to the newly supplied branch value. Note that when sending a Request within a transaction, branch id management will be the responsibility of the SipProvider; that is the application should not set this value. This method should only be used by the application when sending Requests outside of a transaction.

Parameters:
branch - - the new string branch parmameter of the ViaHeader.
Throws:
java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the branch value.

setRPort

void setRPort()
              throws InvalidArgumentException
Set the rport part of this ViaHeader. This method indicates to the remote party that you want it to use rport. It is the applications responsisbility to call this method to inform the implementation to set the value of the rport. This allows a client to request that the server send the response back to the source IP address and port from which the request originated. See RFC3581

Throws:
InvalidArgumentException - if rport value is an illegal integer ( <=0 ).
Since:
v1.2

getRPort

int getRPort()
Returns the rport part of this ViaHeader.

Returns:
the integer value of the rport or -1 if the rport parameter is not set.
Since:
v1.2

equals

boolean equals(java.lang.Object obj)
Compare this ViaHeader for equality with another. This method overrides the equals method in javax.sip.Header. This method specifies object equality as outlined by RFC3261. Two Via header fields are equal if their sent-protocol and sent-by fields are equal, both have the same set of parameters, and the values of all parameters are equal. When comparing header fields, field names are always case-insensitive. Unless otherwise stated in the definition of a particular header field, field values, parameter names, and parameter values are case-insensitive. Tokens are always case-insensitive. Unless specified otherwise, values expressed as quoted strings are case-sensitive.

Specified by:
equals in interface Header
Overrides:
equals in class java.lang.Object
Parameters:
obj - the object to compare this ViaHeader with.
Returns:
true if obj is an instance of this class representing the same ViaHeader as this, false otherwise.
Since:
v1.2

JSIP API v1.2
November 2006

If you have any comments, please mail them to JAIN-SIP-INTEREST@java.sun.com after subscribing at http://archives.java.sun.com
Copyright - 2006 BEA Systems and Sun Microsystems