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 : CallIdHeader.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:
025: /**
026:
027: * The Call-ID header field uniquely identifies a particular invitation or all
028: * registrations of a particular client. A single multimedia conference can give rise to
029:
030: * several calls with different Call-IDs, for example, if a user invites a
031:
032: * single individual several times to the same (long-running) conference.
033:
034: * Call-IDs are case-sensitive and are simply compared byte-by-byte.
035:
036: * <p>
037:
038: * Call-ID is generated by the combination of a random string and the
039:
040: * softphone's host name or IP address. The combination of the To tag,
041:
042: * From tag, and Call-ID completely defines a peer-to-peer SIP relationship
043:
044: * between two users and is referred to as a dialog. It MUST be the same for
045: * all requests and responses sent by either User Agent in a dialog. It SHOULD be the
046: * same in each registration from a User Agent.
047:
048: * <p>
049:
050: * All SIP User Agents must have a means to guarantee that the Call-ID header fields
051:
052: * they produce will not be inadvertently generated by any other User Agent. Note
053:
054: * that when requests are retried after certain failure responses that solicit
055:
056: * an amendment to a request (for example, a challenge for authentication),
057:
058: * these retried requests are not considered new requests, and therefore do
059:
060: * not need new Call-ID header fields.
061:
062: * <p>
063:
064: * Use of cryptographically random identifiers in the generation of Call-IDs is
065:
066: * RECOMMENDED. Implementations MAY use the form "localid@host".
067:
068: * <p>
069:
070: * For Example:<br>
071:
072: * <code>Call-ID: f81d4fae-7dec-11d0-a765-00a0c91e6bf6@jcp.org</code>
073:
074: *
075:
076: * @author BEA Systems, NIST
077: * @version 1.2
078:
079: *
080:
081: */
082:
083: public interface CallIdHeader extends Header {
084:
085: /**
086:
087: * Sets the Call-Id of the CallIdHeader. The CallId parameter uniquely
088:
089: * identifies a serious of messages within a dialogue.
090:
091: *
092:
093: * @param callId - the string value of the Call-Id of this CallIdHeader.
094:
095: * @throws ParseException which signals that an error has been reached
096:
097: * unexpectedly while parsing the callId value.
098:
099: */
100:
101: public void setCallId(String callId) throws ParseException;
102:
103: /**
104:
105: * Returns the Call-Id of CallIdHeader. The CallId parameter uniquely
106:
107: * identifies a series of messages within a dialogue.
108:
109: *
110:
111: * @return the String value of the Call-Id of this CallIdHeader
112:
113: */
114:
115: public String getCallId();
116:
117: /**
118: * Compare this CallIdHeader for equality with another. This method
119: * overrides the equals method in javax.sip.Header. This method specifies
120: * object equality as outlined by
121: * <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>.
122: * Call-IDs are case-sensitive and are simply compared byte-by-byte.
123: *
124: * @param obj the object to compare this CallIdHeader with.
125: * @return <code>true</code> if <code>obj</code> is an instance of this class
126: * representing the same CallIdHeader as this, <code>false</code> otherwise.
127: * @since v1.2
128: */
129: public boolean equals(Object obj);
130:
131: /**
132:
133: * Name of CallIdHeader
134:
135: */
136:
137: public final static String NAME = "Call-ID";
138:
139: }
|