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 : ErrorInfoHeader.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty Initial version
020: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
021: */package javax.sip.header;
022:
023: import java.text.ParseException;
024: import javax.sip.address.URI;
025:
026: /**
027:
028: * The Error-Info header field provides a pointer to additional information
029:
030: * about the error status response.
031:
032: * SIP UACs have user interface capabilities ranging from pop-up windows and
033:
034: * audio on PC softclients to audio-only on "black" phones or endpoints
035:
036: * connected via gateways. Rather than forcing a server generating an error
037:
038: * to choose between sending an error status code with a detailed reason
039:
040: * phrase and playing an audio recording, the Error-Info header field allows
041:
042: * both to be sent. The UAC then has the choice of which error indicator to
043:
044: * render to the caller.
045:
046: * <p>
047:
048: * A UAC MAY treat a SIP or SIPS URI in an Error-Info header field as if it
049:
050: * were a Contact in a redirect and generate a new INVITE, resulting in a
051:
052: * recorded announcement session being established. A non-SIP URI MAY be
053:
054: * rendered to the user.
055:
056: * <p>
057:
058: * Examples:<br>
059:
060: * <code>SIP/2.0 404 The number you have dialed is not in service<br>
061:
062: * Error-Info: sip:not-in-service-recording@atlanta.com</code>
063:
064: *
065:
066: * @author BEA Systems, NIST
067: * @version 1.2
068:
069: */
070:
071: public interface ErrorInfoHeader extends Parameters, Header {
072:
073: /**
074:
075: * Sets the ErrorInfo of the ErrorInfoHeader to the <var>errorInfo</var>
076:
077: * parameter value.
078:
079: *
080:
081: * @param errorInfo the new ErrorInfo of this ErrorInfoHeader.
082:
083: */
084:
085: public void setErrorInfo(URI errorInfo);
086:
087: /**
088:
089: * Returns the ErrorInfo value of this ErrorInfoHeader. This message
090:
091: * may return null if a String message identifies the ErrorInfo.
092:
093: *
094:
095: * @return the URI representing the ErrorInfo.
096:
097: */
098:
099: public URI getErrorInfo();
100:
101: /**
102:
103: * Sets the Error information message to the new <var>message</var> value
104:
105: * supplied to this method.
106:
107: *
108:
109: * @param message - the new string value that represents the error message.
110:
111: * @throws ParseException which signals that an error has been reached
112:
113: * unexpectedly while parsing the error message.
114:
115: */
116:
117: public void setErrorMessage(String message) throws ParseException;
118:
119: /**
120:
121: * Get the Error information message of this ErrorInfoHeader.
122:
123: *
124:
125: * @return the stringified version of the ErrorInfo header.
126:
127: */
128:
129: public String getErrorMessage();
130:
131: /**
132:
133: * Name of the ErroInfoHeader
134:
135: */
136:
137: public final static String NAME = "Error-Info";
138:
139: }
|