| javax.sip.header.ViaHeader
| ViaHeader | | public interface ViaHeader extends Parameters,Header(Code) | | 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
javax.sip.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
- Generating Requests (UAC): The client originating the Request must insert
into the Request 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 Responses. (Note that this port number can differ from the UDP
source port number of the Request.) A fully-qualified domain name is
recommended.
- Request Forwarding by Proxies: The proxy MUST insert a Via header field
value into the copy before the existing Via header field values. This
implies that the proxy will compute its own branch parameter, which will be
globally unique for that branch, and contain the requisite magic cookie. Note
that this implies that the branch parameter will be different for different
instances of a spiraled or looped request through a proxy. If a proxy server
receives a Request which contains its own address in a ViaHeader, it must
respond with a 482 (Loop Detected) Response. A proxy server must not forward
a Request 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.
- Response processing by UAC and proxies:
- The first ViaHeader should indicate the proxy or client processing this
Response. If it does not, discard the Response. Otherwise, remove this
ViaHeader.
- If there is no second ViaHeader, this Response 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 Response to
the multicast address listed there, using the port indicated in "sent-by",
or port 5060 if none is present. The Response 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, Responses 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 Response 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 Response to the address
indicated by the host value in the second ViaHeader.
- Sending Responses (UAS):
- If the first ViaHeader in the Request contains a maddr parameter, send
the Response to the multicast address listed there, using the port indicated,
or port 5060 if none is present. The Response 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, Responses 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 Response to the address
contained in the host value. If the Request was sent using TCP, use the
existing TCP connection if available.
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
version:
1.2 |
| Method Summary | |
| public boolean | equals(Object obj)
Compare this ViaHeader for equality with another. | | public String | getBranch()
Gets the branch paramater of the ViaHeader. | | public String | getHost()
Returns the host part of this ViaHeader. | | public String | getMAddr()
Returns the value of the maddr parameter, or null if this
is not set. | | public int | getPort()
Returns the port part of this ViaHeader. | | public String | getProtocol()
Returns the value of the protocol used. | | public int | getRPort()
Returns the rport part of this ViaHeader. | | public String | getReceived()
Gets the received paramater of the ViaHeader. | | public int | getTTL()
Returns the value of the ttl parameter, or -1 if this is not set. | | public String | getTransport()
Returns the value of the transport parameter. | | public void | setBranch(String branch)
Sets the branch parameter of the ViaHeader to the newly supplied
branch value. | | public void | setHost(String host)
Set the host part of this ViaHeader to the newly supplied host
parameter. | | public void | setMAddr(String mAddr)
Sets the value of the maddr parameter of this ViaHeader. | | public void | setPort(int port)
Set the port part of this ViaHeader to the newly supplied port
parameter. | | public void | setProtocol(String protocol)
Sets the value of the protocol parameter. | | public void | setRPort()
Set the rport part of this ViaHeader. | | public void | setReceived(String received)
Sets the received parameter of ViaHeader. | | public void | setTTL(int ttl)
Sets the value of the ttl parameter. | | public void | setTransport(String transport)
Sets the value of the transport. |
| equals | | public boolean equals(Object obj)(Code) | | 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.
Parameters:
obj - the object to compare this ViaHeader with. true if obj is an instance of this classrepresenting the same ViaHeader as this, false otherwise.
since:
v1.2 |
| getBranch | | public String getBranch()(Code) | | Gets the branch paramater of the ViaHeader. Returns null if branch
does not exist.
the string branch value of ViaHeader |
| getHost | | public String getHost()(Code) | | Returns the host part of this ViaHeader.
the string value of the host |
| getMAddr | | public String getMAddr()(Code) | | Returns the value of the maddr parameter, or null if this
is not set.
the string value of the maddr parameter |
| getPort | | public int getPort()(Code) | | Returns the port part of this ViaHeader.
the integer value of the port, -1 if not present |
| getProtocol | | public String getProtocol()(Code) | | Returns the value of the protocol used.
the string value of the protocol paramter of the ViaHeader |
| getRPort | | public int getRPort()(Code) | | Returns the rport part of this ViaHeader.
the integer value of the rport or -1 if the rport parameter is not set.
since:
v1.2 |
| getReceived | | public String getReceived()(Code) | | Gets the received paramater of the ViaHeader. Returns null if received
does not exist.
the string received value of ViaHeader |
| getTTL | | public int getTTL()(Code) | | Returns the value of the ttl parameter, or -1 if this is not set.
the integer value of the ttl parameter |
| getTransport | | public String getTransport()(Code) | | Returns the value of the transport parameter.
the string value of the transport paramter of the ViaHeader |
| setBranch | | public void setBranch(String branch) throws ParseException(Code) | | 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:
ParseException - which signals that an error has been reachedunexpectedly while parsing the branch value. |
| setHost | | public void setHost(String host) throws ParseException(Code) | | 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:
ParseException - which signals that an error has been reachedunexpectedly while parsing the host value. |
| setMAddr | | public void setMAddr(String mAddr) throws ParseException(Code) | | 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:
ParseException - which signals that an error has been reachedunexpectedly while parsing the mAddr value. |
| setPort | | public void setPort(int port) throws InvalidArgumentException(Code) | | 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 |
| setProtocol | | public void setProtocol(String protocol) throws ParseException(Code) | | 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:
ParseException - which signals that an error has been reachedunexpectedly while parsing the protocol value. |
| setRPort | | public void setRPort() throws InvalidArgumentException(Code) | | 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 |
| setReceived | | public void setReceived(String received) throws ParseException(Code) | | Sets the received parameter of ViaHeader.
Parameters:
received - - the newly supplied received parameter.
throws:
ParseException - which signals that an error has been reachedunexpectedly while parsing the received value. |
| setTTL | | public void setTTL(int ttl) throws InvalidArgumentException(Code) | | 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. |
| setTransport | | public void setTransport(String transport) throws ParseException(Code) | | 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:
ParseException - which signals that an error has been reachedunexpectedly while parsing the transport value. |
|
|