All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.sip.header.ViaHeader Maven / Gradle / Ivy

There is a newer version: 1.3.0-91
Show newest version
/**
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * Unpublished - rights reserved under the Copyright Laws of the United States.
 * Copyright ? 2003 Sun Microsystems, Inc. All rights reserved.
 * Copyright ? 2005 BEA Systems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * This distribution may include materials developed by third parties. 
 *
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 *
 * Module Name   : JSIP Specification
 * File Name     : ViaHeader.java
 * Author        : Phelim O'Doherty
 *
 *  HISTORY
 *  Version   Date      Author              Comments
 *  1.1     08/10/2002  Phelim O'Doherty    
 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */
package javax.sip.header;


import java.text.ParseException;
import javax.sip.InvalidArgumentException;

/**
 * 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 * {@link 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 */ public interface ViaHeader extends Parameters, Header { /** * Set the host part of this ViaHeader to the newly supplied host * parameter. * * @param host - the new value of the host of this ViaHeader * @throws ParseException which signals that an error has been reached * unexpectedly while parsing the host value. */ public void setHost(String host) throws ParseException; /** * Returns the host part of this ViaHeader. * * @return the string value of the host */ public String getHost(); /** * Set the port part of this ViaHeader to the newly supplied port * parameter. * * @param port - the new integer value of the port of this ViaHeader * @throws InvalidArgumentException when the port value is not -1 and <1 or >65535 */ public void setPort(int port) throws InvalidArgumentException; /** * Returns the port part of this ViaHeader. * * @return the integer value of the port, -1 if not present */ public int getPort(); /** * Returns the value of the transport parameter. * * @return the string value of the transport paramter of the ViaHeader */ public String getTransport(); /** * 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. * * @param transport - new value for the transport parameter * @throws ParseException which signals that an error has been reached * unexpectedly while parsing the transport value. */ public void setTransport(String transport) throws ParseException; /** * Returns the value of the protocol used. * * @return the string value of the protocol paramter of the ViaHeader */ public String getProtocol(); /** * Sets the value of the protocol parameter. This parameter specifies * which protocol is used, for example "SIP/2.0". * * @param protocol - new value for the protocol parameter * @throws ParseException which signals that an error has been reached * unexpectedly while parsing the protocol value. */ public void setProtocol(String protocol) throws ParseException; /** * Returns the value of the ttl parameter, or -1 if this is not set. * * @return the integer value of the ttl parameter */ public int getTTL(); /** * Sets the value of the ttl parameter. The ttl parameter specifies the * time-to-live value when packets are sent using UDP multicast. * * @param 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. */ public void setTTL(int ttl) throws InvalidArgumentException; /** * Returns the value of the maddr parameter, or null if this * is not set. * * @return the string value of the maddr parameter */ public String getMAddr(); /** * 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. * * @param mAddr new value of the mAddr parameter * @throws ParseException which signals that an error has been reached * unexpectedly while parsing the mAddr value. */ public void setMAddr(String mAddr) throws ParseException; /** * Gets the received paramater of the ViaHeader. Returns null if received * does not exist. * * @return the string received value of ViaHeader */ public String getReceived(); /** * Sets the received parameter of ViaHeader. * * @param received - the newly supplied received parameter. * @throws ParseException which signals that an error has been reached * unexpectedly while parsing the received value. */ public void setReceived(String received) throws ParseException; /** * Gets the branch paramater of the ViaHeader. Returns null if branch * does not exist. * * @return the string branch value of ViaHeader */ public String getBranch(); /** * 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. * * @param branch - the new string branch parmameter of the ViaHeader. * @throws ParseException which signals that an error has been reached * unexpectedly while parsing the branch value. */ public void setBranch(String branch) throws ParseException; /** * 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 */ public void setRPort() throws InvalidArgumentException; /** * Returns the rport part of this ViaHeader. * * @return the integer value of the rport or -1 if the rport parameter * is not set. * @since v1.2 */ public int getRPort(); /** * 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. * * @param obj the object to compare this ViaHeader with. * @return true if obj is an instance of this class * representing the same ViaHeader as this, false otherwise. * @since v1.2 */ public boolean equals(Object obj); /** * Name of ViaHeader */ public final static String NAME = "Via"; }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy