sip.header.CallIdHeader Maven / Gradle / Ivy

/**
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * Unpublished - rights reserved under the Copyright Laws of the United States.
 * Copyright ? 2003 Sun Microsystems, Inc. All rights reserved.
 * Copyright ? 2005 BEA Systems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * This distribution may include materials developed by third parties. 
 *
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 *
 * Module Name   : JSIP Specification
 * File Name     : CallIdHeader.java
 * Author        : Phelim O'Doherty
 *
 *  HISTORY
 *  Version   Date      Author              Comments
 *  1.1     08/10/2002  Phelim O'Doherty    
 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */
package javax.sip.header;



import java.text.ParseException;



/**

 * The Call-ID header field uniquely identifies a particular invitation or all 
 * registrations of a particular client. A single multimedia conference can give rise to

 * several calls with different Call-IDs, for example, if a user invites a

 * single individual several times to the same (long-running) conference.

 * Call-IDs are case-sensitive and are simply compared byte-by-byte.

 * 

 * Call-ID is generated by the combination of a random string and the

 * softphone's host name or IP address.  The combination of the To tag,

 * From tag, and Call-ID completely defines a peer-to-peer SIP relationship

 * between two users and is referred to as a dialog. It MUST be the same for 
 * all requests and responses sent by either User Agent in a dialog.  It SHOULD be the 
 * same in each registration from a User Agent.

 * 


 * All SIP User Agents must have a means to guarantee that the Call-ID header fields

 * they produce will not be inadvertently generated by any other User Agent.  Note

 * that when requests are retried after certain failure responses that solicit

 * an amendment to a request (for example, a challenge for authentication),

 * these retried requests are not considered new requests, and therefore do

 * not need new Call-ID header fields.

 * 


 * Use of cryptographically random identifiers in the generation of Call-IDs is

 * RECOMMENDED.  Implementations MAY use the form "localid@host".

 * 

 * For Example:


 * Call-ID: [email protected]

 *

 * @author BEA Systems, NIST
 * @version 1.2

 *

 */



public interface CallIdHeader extends Header {



    /**

     * Sets the Call-Id of the CallIdHeader. The CallId parameter uniquely

     * identifies a serious of messages within a dialogue.

     *

     * @param callId - the string value of the Call-Id of this CallIdHeader.

     * @throws ParseException which signals that an error has been reached

     * unexpectedly while parsing the callId value.

     */

    public void setCallId(String callId) throws ParseException;



    /**

     * Returns the Call-Id of CallIdHeader. The CallId parameter uniquely

     * identifies a series of messages within a dialogue.

     *

     * @return the String value of the Call-Id of this CallIdHeader

     */

    public String getCallId();

    /**
     * Compare this CallIdHeader for equality with another. This method 
     * overrides the equals method in javax.sip.Header. This method specifies 
     * object equality as outlined by  
     * RFC3261. 
     * Call-IDs are case-sensitive and are simply compared byte-by-byte. 
     *
     * @param obj the object to compare this CallIdHeader with.
     * @return true if obj is an instance of this class
     * representing the same CallIdHeader as this, false otherwise.
     * @since v1.2
     */
    public boolean equals(Object obj);    



    /**

     * Name of CallIdHeader

     */

    public final static String NAME = "Call-ID";

}