001: /**
002: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
003: * Unpublished - rights reserved under the Copyright Laws of the United States.
004: * Copyright © 2003 Sun Microsystems, Inc. All rights reserved.
005: * Copyright © 2005 BEA Systems, Inc. All rights reserved.
006: *
007: * Use is subject to license terms.
008: *
009: * This distribution may include materials developed by third parties.
010: *
011: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
012: *
013: * Module Name : JSIP Specification
014: * File Name : ViaHeader.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty
020: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
021: */package javax.sip.header;
022:
023: import java.text.ParseException;
024: import javax.sip.InvalidArgumentException;
025:
026: /**
027: * The Via header field indicates the transport used for the transaction and
028: * identifies the location where the response is to be sent. A Via header
029: * field value is added only after the transport that will be used to reach
030: * the next hop has been selected. When the UAC creates a request, it MUST
031: * insert a Via into that request. The protocol name and protocol version in
032: * the header field MUST be SIP and 2.0, respectively. The Via header field
033: * value MUST contain a branch parameter. This parameter is used to identify
034: * the transaction created by that request. This parameter is used by both the
035: * client and the server.
036: * <p>
037: * <b>Branch Parameter:<br></b>
038: * The branch parameter value MUST be unique across space and time for all
039: * requests sent by the User Agent. The exceptions to this rule are CANCEL and ACK for
040: * non-2xx responses. A CANCEL request will have the same value of the branch
041: * parameter as the request it cancels. An ACK for a non-2xx response will also
042: * have the same branch ID as the INVITE whose response it acknowledges.
043: * <p>
044: * The uniqueness property of the branch ID parameter, to facilitate its use as
045: * a transaction ID, was not part of RFC 2543. The branch ID inserted by an
046: * element compliant with this specification MUST always begin with the
047: * characters "z9hG4bK". These 7 characters are used as a magic cookie (7 is
048: * deemed sufficient to ensure that an older RFC 2543 implementation would not
049: * pick such a value), so that servers receiving the request can determine that
050: * the branch ID was constructed in the fashion described by this specification
051: * (that is, globally unique). Beyond this requirement, the precise format of
052: * the branch token is implementation-defined. JSIP defines a convenience
053: * function to generate unique branch identifiers at
054: * {@link javax.sip.Transaction#getBranchId()}
055: * <p>
056: * A common way to create the branch value is to compute a cryptographic hash
057: * of the To tag, From tag, Call-ID header field, the Request-URI of the
058: * request received (before translation), the topmost Via header, and the
059: * sequence number from the CSeq header field, in addition to any Proxy-Require
060: * and Proxy-Authorization header fields that may be present. The algorithm
061: * used to compute the hash is implementation-dependent.
062: * <p>
063: * <b>Via Processing Rules</b>
064: * <ul>
065: * <li>Generating Requests (UAC): The client originating the Request must insert
066: * into the Request a ViaHeader containing its host name or network address
067: * and, if not the default port number, the port number at which it wishes to
068: * receive Responses. (Note that this port number can differ from the UDP
069: * source port number of the Request.) A fully-qualified domain name is
070: * recommended.
071: * <li>Request Forwarding by Proxies: The proxy MUST insert a Via header field
072: * value into the copy before the existing Via header field values. This
073: * implies that the proxy will compute its own branch parameter, which will be
074: * globally unique for that branch, and contain the requisite magic cookie. Note
075: * that this implies that the branch parameter will be different for different
076: * instances of a spiraled or looped request through a proxy. If a proxy server
077: * receives a Request which contains its own address in a ViaHeader, it must
078: * respond with a 482 (Loop Detected) Response. A proxy server must not forward
079: * a Request to a multicast group which already appears in any of the ViaHeaders.
080: * This prevents a malfunctioning proxy server from causing loops. Also, it
081: * cannot be guaranteed that a proxy server can always detect that the address
082: * returned by a location service refers to a host listed in the ViaHeader list,
083: * as a single host may have aliases or several network interfaces.
084: * <li>Response processing by UAC and proxies:
085: * <ul>
086: * <li>The first ViaHeader should indicate the proxy or client processing this
087: * Response. If it does not, discard the Response. Otherwise, remove this
088: * ViaHeader.
089: * <li>If there is no second ViaHeader, this Response is destined for this
090: * client. Otherwise, the processing depends on whether the ViaHeader contains
091: * a maddr parameter or is a receiver-tagged field.
092: * <li>If the second ViaHeader contains a maddr parameter, send the Response to
093: * the multicast address listed there, using the port indicated in "sent-by",
094: * or port 5060 if none is present. The Response should be sent using the TTL
095: * indicated in the ttl parameter, or with a TTL of 1 if that parameter is not
096: * present. For robustness, Responses must be sent to the address indicated in
097: * the maddr parameter even if it is not a multicast address.
098: * <li>If the second ViaHeader does not contain a maddr parameter and is a
099: * receiver-tagged ViaHeader, send the Response to the address in the received
100: * parameter, using the port indicated in the port value, or using port 5060
101: * if none is present.
102: * <li>If neither of the previous cases apply, send the Response to the address
103: * indicated by the host value in the second ViaHeader.
104: * </ul>
105: * <li>Sending Responses (UAS):
106: * <ul>
107: * <li>If the first ViaHeader in the Request contains a maddr parameter, send
108: * the Response to the multicast address listed there, using the port indicated,
109: * or port 5060 if none is present. The Response should be sent using the TTL
110: * indicated in the ttl parameter, or with a TTL of 1 if that parameter is not
111: * present. For robustness, Responses must be sent to the address indicated in
112: * the maddr parameter even if it is not a multicast address.
113: * <li>If the address in the first ViaHeader differs from the source address of
114: * the packet, send the Response to the actual packet source address, similar
115: * to the treatment for receiver-tagged ViaHeaders.
116: * <li>If neither of these conditions is true, send the Response to the address
117: * contained in the host value. If the Request was sent using TCP, use the
118: * existing TCP connection if available.
119: * </ul>
120: * </ul>
121: * <b>Via Parameters:</b>
122: * A Via header field value contains the transport protocol used to send the
123: * message, the client's host name or network address, and possibly the port
124: * number at which it wishes to receive responses. Transport protocols defined
125: * here are "UDP", "TCP", "TLS", and "SCTP". "TLS" means TLS over TCP. When a
126: * request is sent to a SIPS URI, the protocol still indicates "SIP", and the
127: * transport protocol is TLS. A Via header field value can also contain
128: * parameters such as "maddr", "ttl", "received", and "branch". A proxy sending
129: * a Request to a multicast address must add the maddr parameter to its
130: * ViaHeader, and should add the ttl parameter. If a server receives a Request
131: * which contained an maddr parameter in the topmost ViaHeader, it should send
132: * the Response to the multicast address listed in the maddr parameter. The
133: * received parameter is added only for receiver-added ViaHeaders.
134: * <p>
135: * Two Via header fields are equal if their sent-protocol and sent-by fields
136: * (including port) are equal, both have the same set of parameters, and the
137: * values of all parameters are equal.
138: *
139: * @author BEA Systems, NIST
140: * @version 1.2
141: */
142: public interface ViaHeader extends Parameters, Header {
143:
144: /**
145: * Set the host part of this ViaHeader to the newly supplied <code>host</code>
146: * parameter.
147: *
148: * @param host - the new value of the host of this ViaHeader
149: * @throws ParseException which signals that an error has been reached
150: * unexpectedly while parsing the host value.
151: */
152: public void setHost(String host) throws ParseException;
153:
154: /**
155: * Returns the host part of this ViaHeader.
156: *
157: * @return the string value of the host
158: */
159: public String getHost();
160:
161: /**
162: * Set the port part of this ViaHeader to the newly supplied <code>port</code>
163: * parameter.
164: *
165: * @param port - the new integer value of the port of this ViaHeader
166: * @throws InvalidArgumentException when the port value is not -1 and <1 or >65535
167: */
168: public void setPort(int port) throws InvalidArgumentException;
169:
170: /**
171: * Returns the port part of this ViaHeader.
172: *
173: * @return the integer value of the port, -1 if not present
174: */
175: public int getPort();
176:
177: /**
178: * Returns the value of the transport parameter.
179: *
180: * @return the string value of the transport paramter of the ViaHeader
181: */
182: public String getTransport();
183:
184: /**
185: * Sets the value of the transport. This parameter specifies
186: * which transport protocol to use for sending requests and responses to
187: * this entity. The following values are defined: "udp", "tcp", "sctp",
188: * "tls", but other values may be used also.
189: *
190: * @param transport - new value for the transport parameter
191: * @throws ParseException which signals that an error has been reached
192: * unexpectedly while parsing the transport value.
193: */
194: public void setTransport(String transport) throws ParseException;
195:
196: /**
197: * Returns the value of the protocol used.
198: *
199: * @return the string value of the protocol paramter of the ViaHeader
200: */
201: public String getProtocol();
202:
203: /**
204: * Sets the value of the protocol parameter. This parameter specifies
205: * which protocol is used, for example "SIP/2.0".
206: *
207: * @param protocol - new value for the protocol parameter
208: * @throws ParseException which signals that an error has been reached
209: * unexpectedly while parsing the protocol value.
210: */
211: public void setProtocol(String protocol) throws ParseException;
212:
213: /**
214: * Returns the value of the ttl parameter, or -1 if this is not set.
215: *
216: * @return the integer value of the <code>ttl</code> parameter
217: */
218: public int getTTL();
219:
220: /**
221: * Sets the value of the ttl parameter. The ttl parameter specifies the
222: * time-to-live value when packets are sent using UDP multicast.
223: *
224: * @param ttl - new value of the ttl parameter
225: * @throws InvalidArgumentException if supplied value is less than zero or
226: * greater than 255, excluding -1 the default not set value.
227: */
228: public void setTTL(int ttl) throws InvalidArgumentException;
229:
230: /**
231: * Returns the value of the <code>maddr</code> parameter, or null if this
232: * is not set.
233: *
234: * @return the string value of the maddr parameter
235: */
236: public String getMAddr();
237:
238: /**
239: * Sets the value of the <code>maddr</code> parameter of this ViaHeader. The
240: * maddr parameter indicates the server address to be contacted for this
241: * user, overriding any address derived from the host field.
242: *
243: * @param mAddr new value of the <code>mAddr</code> parameter
244: * @throws ParseException which signals that an error has been reached
245: * unexpectedly while parsing the mAddr value.
246: */
247: public void setMAddr(String mAddr) throws ParseException;
248:
249: /**
250: * Gets the received paramater of the ViaHeader. Returns null if received
251: * does not exist.
252: *
253: * @return the string received value of ViaHeader
254: */
255: public String getReceived();
256:
257: /**
258: * Sets the received parameter of ViaHeader.
259: *
260: * @param received - the newly supplied received parameter.
261: * @throws ParseException which signals that an error has been reached
262: * unexpectedly while parsing the received value.
263: */
264: public void setReceived(String received) throws ParseException;
265:
266: /**
267: * Gets the branch paramater of the ViaHeader. Returns null if branch
268: * does not exist.
269: *
270: * @return the string branch value of ViaHeader
271: */
272: public String getBranch();
273:
274: /**
275: * Sets the branch parameter of the ViaHeader to the newly supplied
276: * branch value. Note that when sending a Request within a transaction,
277: * branch id management will be the responsibility of the SipProvider;
278: * that is the application should not set this value. This method should
279: * only be used by the application when sending Requests outside of a
280: * transaction.
281: *
282: * @param branch - the new string branch parmameter of the ViaHeader.
283: * @throws ParseException which signals that an error has been reached
284: * unexpectedly while parsing the branch value.
285: */
286: public void setBranch(String branch) throws ParseException;
287:
288: /**
289: * Set the rport part of this ViaHeader. This method indicates to the
290: * remote party that you want it to use rport. It is the applications
291: * responsisbility to call this method to inform the implementation to set
292: * the value of the rport. This allows a client
293: * to request that the server send the response back to the source IP
294: * address and port from which the request originated.
295: * See <a href = "http://www.ietf.org/rfc/rfc3581.txt">RFC3581</a>
296: *
297: *
298: * @throws InvalidArgumentException if rport value is an illegal integer ( <=0 ).
299: * @since v1.2
300: */
301: public void setRPort() throws InvalidArgumentException;
302:
303: /**
304: * Returns the rport part of this ViaHeader.
305: *
306: * @return the integer value of the rport or -1 if the rport parameter
307: * is not set.
308: * @since v1.2
309: */
310: public int getRPort();
311:
312: /**
313: * Compare this ViaHeader for equality with another. This method
314: * overrides the equals method in javax.sip.Header. This method specifies
315: * object equality as outlined by
316: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>.
317: * Two Via header fields are equal if their sent-protocol and sent-by fields
318: * are equal, both have the same set of parameters, and the values of all
319: * parameters are equal. When comparing header fields, field names are always
320: * case-insensitive. Unless otherwise stated in the definition of a
321: * particular header field, field values, parameter names, and parameter
322: * values are case-insensitive. Tokens are always case-insensitive. Unless
323: * specified otherwise, values expressed as quoted strings are case-sensitive.
324: *
325: * @param obj the object to compare this ViaHeader with.
326: * @return <code>true</code> if <code>obj</code> is an instance of this class
327: * representing the same ViaHeader as this, <code>false</code> otherwise.
328: * @since v1.2
329: */
330: public boolean equals(Object obj);
331:
332: /**
333: * Name of ViaHeader
334: */
335: public final static String NAME = "Via";
336:
337: }
|