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 : WarningHeader.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 Warning header field is used to carry additional information about the
028: * status of a response. Warning header field values are sent with responses
029: * and contain a three-digit warning code, agent name, and warning text.
030: * <ul>
031: * <li>Warning Text: The "warn-text" should be in a natural language that is
032: * most likely to be intelligible to the human user receiving the response.
033: * This decision can be based on any available knowledge, such as the location
034: * of the user, the Accept-Language field in a request, or the Content-Language
035: * field in a response.
036: * <li>Warning Code: The currently-defined "warn-code"s have a recommended
037: * warn-text in English and a description of their meaning. These warnings
038: * describe failures induced by the session description. The first digit of
039: * warning codes beginning with "3" indicates warnings specific to SIP. Warnings
040: * 300 through 329 are reserved for indicating problems with keywords in the
041: * session description, 330 through 339 are warnings related to basic network
042: * services requested in the session description, 370 through 379 are warnings
043: * related to quantitative QoS parameters requested in the session description,
044: * and 390 through 399 are miscellaneous warnings that do not fall into one of
045: * the above categories. Additional "warn-code"s can be defined.
046: * </ul>
047: * Any server may add WarningHeaders to a Response. Proxy servers must place
048: * additional WarningHeaders before any AuthorizationHeaders. Within that
049: * constraint, WarningHeaders must be added after any existing WarningHeaders
050: * not covered by a signature. A proxy server must not delete any WarningHeader
051: * that it received with a Response.
052: * <p>
053: * When multiple WarningHeaders are attached to a Response, the user agent
054: * should display as many of them as possible, in the order that they appear
055: * in the Response. If it is not possible to display all of the warnings, the
056: * user agent first displays warnings that appear early in the Response.
057: * <p>
058: * Examples of using Warning Headers are as follows:
059: * <ul>
060: * <li>A UAS rejecting an offer contained in an INVITE SHOULD return a 488 (Not
061: * Acceptable Here) response. Such a response SHOULD include a Warning header
062: * field value explaining why the offer was rejected.
063: * <li>If the new session description is not acceptable, the UAS can reject it
064: * by returning a 488 (Not Acceptable Here) response for the re-INVITE. This
065: * response SHOULD include a Warning header field.
066: * <li>A 606 (Not Acceptable) response means that the user wishes to communicate,
067: * but cannot adequately support the session described. The 606 (Not Acceptable)
068: * response MAY contain a list of reasons in a Warning header field describing
069: * why the session described cannot be supported.
070: * <li>Contact header fields MAY be present in a 200 (OK) response and have the
071: * same semantics as in a 3xx response. That is, they may list a set of
072: * alternative names and methods of reaching the user. A Warning header field
073: * MAY be present.
074: * </ul>
075: * For Example:<br>
076: * <code>Warning: 307 isi.edu "Session parameter 'foo' not understood"</code>
077: *
078: * @author BEA Systems, NIST
079: * @version 1.2
080: */
081:
082: public interface WarningHeader extends Header {
083:
084: /**
085: * Gets the agent of the server that created this WarningHeader.
086: *
087: * @return the agent of the WarningHeader
088: */
089: public String getAgent();
090:
091: /**
092: * Sets the agent value of the WarningHeader to the new value passed to the
093: * method.
094: *
095: * @param agent - the new agent value of WarningHeader
096: * @throws ParseException which signals that an error has been reached
097: * unexpectedly while parsing the agent value.
098: */
099: public void setAgent(String agent) throws ParseException;
100:
101: /**
102: * Gets text of WarningHeader.
103: *
104: * @return the string text value of the WarningHeader.
105: */
106: public String getText();
107:
108: /**
109: * Sets the text of WarningHeader to the newly supplied text value.
110: *
111: * @param text - the new text value of the Warning Header.
112: * @throws ParseException which signals that an error has been reached
113: * unexpectedly while parsing the text value.
114: */
115: public void setText(String text) throws ParseException;
116:
117: /**
118: * Sets the code of the WarningHeader. The standard RFC3261 codes are
119: * defined as constants in this class.
120: *
121: * @param code - the new code that defines the warning code.
122: * @throws InvalidArgumentException if an invalid integer code is given for
123: * the WarningHeader.
124: */
125: public void setCode(int code) throws InvalidArgumentException;
126:
127: /**
128: * Gets the code of the WarningHeader.
129: *
130: * @return the integer code value of the WarningHeader
131: */
132: public int getCode();
133:
134: /**
135: * Name of WarningHeader
136: */
137: public final static String NAME = "Warning";
138:
139: // Constants
140:
141: /**
142: * One or more network protocols contained in the session description
143: * are not available.
144: */
145: public final static int INCOMPATIBLE_NETWORK_PROTOCOL = 300;
146:
147: /**
148: * One or more network address formats contained in the session
149: * description are not available.
150: */
151: public final static int INCOMPATIBLE_NETWORK_ADDRESS_FORMATS = 301;
152:
153: /**
154: * One or more transport protocols described in the session description
155: * are not available.
156: */
157: public final static int INCOMPATIBLE_TRANSPORT_PROTOCOL = 302;
158:
159: /**
160: * One or more bandwidth measurement units contained in the session
161: * description were not understood.
162: */
163: public final static int INCOMPATIBLE_BANDWIDTH_UNITS = 303;
164:
165: /**
166: * One or more media types contained in the session description are
167: * not available.
168: */
169: public final static int MEDIA_TYPE_NOT_AVAILABLE = 304;
170:
171: /**
172: * One or more media formats contained in the session description are
173: * not available.
174: */
175: public final static int INCOMPATIBLE_MEDIA_FORMAT = 305;
176:
177: /**
178: * One or more of the media attributes in the session description are
179: * not supported.
180: */
181: public final static int ATTRIBUTE_NOT_UNDERSTOOD = 306;
182:
183: /**
184: * A parameter other than those listed above was not understood.
185: */
186: public final static int SESSION_DESCRIPTION_PARAMETER_NOT_UNDERSTOOD = 307;
187:
188: /**
189: * The site where the user is located does not support multicast.
190: */
191: public final static int MULTICAST_NOT_AVAILABLE = 330;
192:
193: /**
194: * The site where the user is located does not support unicast
195: * communication (usually due to the presence of a firewall).
196: */
197: public final static int UNICAST_NOT_AVAILABLE = 331;
198:
199: /**
200: * The bandwidth specified in the session description or defined by the
201: * media exceeds that known to be available.
202: */
203: public final static int INSUFFICIENT_BANDWIDTH = 370;
204:
205: /**
206: * The warning text can include arbitrary information to be presented to
207: * a human user, or logged. A system receiving this warning MUST NOT
208: * take any automated action.
209: */
210: public final static int MISCELLANEOUS_WARNING = 399;
211:
212: }
|