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 : ContactHeader.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 javax.sip.InvalidArgumentException;
024:
025: /**
026: * A Contact header field value provides a URI whose meaning depends on
027: * the type of request or response it is in. A Contact header field value
028: * can contain a display name, a URI with URI parameters, and header
029: * parameters.
030: * <p>
031: * The Contact header field provides a SIP or SIPS URI that can be used
032: * to contact that specific instance of the User Agent for subsequent requests.
033: * The Contact header field MUST be present and contain exactly one SIP
034: * or SIPS URI in any request that can result in the establishment of a
035: * dialog. For the methods defined in this specification, that includes
036: * only the INVITE request. For these requests, the scope of the
037: * Contact is global. That is, the Contact header field value contains
038: * the URI at which the User Agent would like to receive requests, and this URI
039: * MUST be valid even if used in subsequent requests outside of any
040: * dialogs.
041: * <p>
042: * If the Request-URI or top Route header field value contains a SIPS URI, the
043: * Contact header field MUST contain a SIPS URI as well.
044: * <p>
045: * <b>Messages and Contact Headers</b>
046: * <ul>
047: * <li>Requests: A contact header is mandatory for INVITE's and optional for
048: * ACK, OPTIONS and REGISTER requests. This allows the callee to send future
049: * Requests, such as BYE Requests, directly to the caller instead of through a
050: * series of proxies.
051: * <li>Informational Responses - A contact header is optional in a Informational
052: * Response to an INVITE request. It has the same semantics in an Informational
053: * Response as a Success Response.
054: * <li>Success Responses - A contact header is mandatory in response to INVITE's
055: * and optional in response to OPTIONS and REGISTER requests. An user agent
056: * server sending a Success Response to an INIVTE must insert a ContactHeader
057: * in the Response indicating the SIP address under which it is reachable most
058: * directly for future SIP Requests.
059: * <li>Redirection Responses - A contact header is optional in response to
060: * INVITE's, OPTIONS, REGISTER and BYE requests. A proxy may also delete the
061: * contact header.
062: * <li>Ambiguous Header: - A contact header is optional in response to
063: * INVITE, OPTIONS, REGISTER and BYE requests.
064: * </ul>
065: *
066: * The ContactHeader defines the Contact parameters "q" and "expires".
067: * The <code>q-value</code> value is used to prioritize addresses in a
068: * list of contact addresses. The <code>expires</code> value suggests an
069: * expiration interval that indicates how long the client would like a
070: * registration to be valid for a specific address. These parameters are only
071: * used when the Contact is present in a:
072: * <ul>
073: * <li>REGISTER request
074: * <li>REGISTER response
075: * <li>3xx response
076: * </ul>
077: *
078: * For Example:<br>
079: * <code> Contact: "Mr. Watson" sip:watson@worcester.jcp.org;
080: * q=0.7; expires=3600, "Mr. Watson" mailto:watson@jcp.org.com; q=0.1
081: * </code>
082: * @see HeaderAddress
083: * @see Parameters
084: *
085: * @author BEA Systems, NIST
086: * @version 1.2
087: */
088:
089: public interface ContactHeader extends HeaderAddress, Parameters,
090: Header {
091:
092: /**
093: * Sets the value of the <code>expires</code> parameter as delta-seconds.
094: * When a client sends a REGISTER request, it MAY suggest an expiration
095: * interval that indicates how long the client would like the registration
096: * to be valid for a specific address. There are two ways in which a client
097: * can suggest an expiration interval for a binding:
098: * <ul>
099: * <li>through an Expires header field
100: * <li>an "expires" Contact header parameter.
101: * </ul>
102: * The latter allows expiration intervals to be suggested on a per-binding
103: * basis when more than one binding is given in a single REGISTER request,
104: * whereas the former suggests an expiration interval for all Contact
105: * header field values that do not contain the "expires" parameter. If
106: * neither mechanism for expressing a suggested expiration time is present
107: * in a REGISTER, the client is indicating its desire for the server to
108: * choose.
109: * <p>
110: * A User Agent requests the immediate removal of a binding by specifying an
111: * expiration interval of "0" for that contact address in a REGISTER
112: * request. User Agents SHOULD support this mechanism so that bindings can be
113: * removed before their expiration interval has passed. The
114: * REGISTER-specific Contact header field value of "*" applies to all
115: * registrations, but it MUST NOT be used unless the Expires header
116: * field is present with a value of "0". The "*" value can be determined
117: * if "this.getNameAddress().isWildcard() = = true".
118: *
119: * @param expires new relative value of the expires parameter.
120: * 0 implies removal of Registration specified in Contact Header.
121: * @throws InvalidArgumentException if supplied value is less than zero.
122: */
123:
124: public void setExpires(int expires) throws InvalidArgumentException;
125:
126: /**
127: * Returns the value of the <code>expires</code> parameter or -1 if no
128: * expires parameter was specified or if the parameter value cannot be
129: * parsed as an int.
130: *
131: * @return value of the <code>expires</code> parameter measured in
132: * delta-seconds, O implies removal of Registration specified in Contact
133: * Header.
134: */
135:
136: public int getExpires();
137:
138: /**
139:
140: * Sets the <code>qValue</code> value of the Name Address. If more than
141:
142: * one Contact is sent in a REGISTER request, the registering UA intends
143:
144: * to associate all of the URIs in these Contact header field values with
145:
146: * the address-of-record present in the To field. This list can be
147:
148: * prioritized with the "q" parameter in the Contact header field. The "q"
149:
150: * parameter indicates a relative preference for the particular Contact
151:
152: * header field value compared to other bindings for this address-of-record.
153:
154: * A value of <code>-1</code> indicates the <code>qValue</code> paramater
155:
156: * is not set.
157: *
158: * @param qValue - the new float value of the q-value parameter.
159: * @throws InvalidArgumentException if the q-value parameter value is not
160: * <code>-1</code> or between <code>0 and 1</code>.
161: */
162: public void setQValue(float qValue) throws InvalidArgumentException;
163:
164: /**
165:
166: * Returns the value of the <code>q-value</code> parameter of this
167:
168: * ContactHeader. The <code>q-value</code> parameter indicates the relative
169:
170: * preference amongst a set of locations. <code>q-values</code> are
171:
172: * decimal numbers from 0 to 1, with higher values indicating higher
173:
174: * preference.
175:
176: *
177:
178: * @return the <code>q-value</code> parameter of this ContactHeader, -1 if
179:
180: * the q-value is not set.
181:
182: */
183:
184: public float getQValue();
185:
186: /**
187: * Sets a wildcard on this contact address that is "*" is assigned to the
188: * contact header so that the header will have the format of Contact: *.
189: *
190: * @since v1.2
191: */
192: public void setWildCard();
193:
194: /**
195: * Returns a boolean value that indicates if the contact header
196: * has the format of Contact: *.
197: * @return true if this is a wildcard address, false otherwise.
198: * @since v1.2
199: */
200: public boolean isWildCard();
201:
202: /**
203: * Name of ContactHeader
204: */
205: public final static String NAME = "Contact";
206:
207: }
|