jain.protocol.ip.sip.message
Class CancelMessage

java.lang.Object
  |
  +--java.util.EventObject
        |
        +--jain.protocol.ip.sip.message.Message
              |
              +--jain.protocol.ip.sip.message.RequestMessage
                    |
                    +--jain.protocol.ip.sip.message.CancelMessage

public final class CancelMessage

extends RequestMessage

This class represents a CANCEL request message. A CancelMessage cancels a pending RequestMessage with the same CallIdHeader, ToHeader, FromHeader and CSeqHeader (sequence number only) values, but does not affect a completed RequestMessage. (A RequestMessage is considered completed if the server has returned a final ResponseMessage.)

A user agent client or proxy client may issue a CancelMessage at any time. A proxy, in particular, may choose to send a CancelMessage to destinations that have not yet returned a final ResponseMessage after it has received a Success or Global-Failure ResponseMessage for one or more of the parallel-search RequestMessages. A proxy that receives a CancelMessage forwards the it to all destinations with pending RequestMessages.

The CallIdHeader, ToHeader, FromHeader, and the sequence number of the CSeqHeader in the CancelMessage are identical to those in the original RequestMessage. This allows a CancelMessage to be matched with the RequestMessage it cancels. However, to allow the client to distinguish ResponseMessages to the CancelMessage from those to the original RequestMessage, the CSeq Method component is set to CancelMessage.method. The ViaHeader is initialized to the proxy issuing the CancelMessage. (Thus, ResponseMessages to this CancelMessage only reach the issuing proxy.)

Once a user agent server has received a CancelMessage, it must not issue a Success ResponseMessage for the cancelled original RequestMessage.

A redirect or user agent server receiving a CancelMessage responds with a status of OK if the transaction exists and a status of CALL_LEG_OR_TRANSACTION_DOES_NOT_EXIST if not, but takes no further action. In particular, any existing call is unaffected.

The ByeMessage cannot be used to cancel branches of a parallel search, since several branches may, through intermediate proxies, find the same user agent server and then terminate the call. To terminate a call instead of just pending searches, the UAC must use ByeMessage instead of or in addition to CancelMessage. While CancelMessage can terminate any pending RequestMessage other than AckMessage or CancelMessage, it is typically useful only for InviteMessages. OK ResponseMessages to InviteMessages and OK ResponseMessages to CancelMessage are distinguished by the method in the CseqHeader, so there is no ambiguity.

CancelMessages must be supported by proxy servers and should be supported by all other SIP server types.

Version:

0.6

See Also:

RequestMessage, ResponseMessage, InviteMessage, AckMessage, ByeMessage, FromHeader, ToHeader, CallIdHeader, CSeqHeader, Serialized Form

Field Summary

static java.lang.String

method CancelMessage's method

Constructor Summary

CancelMessage(java.lang.Object source, RequestMessage request)
Constructor of CancelMessage based on sent RequestMessage

CancelMessage(java.lang.Object source, URI requestURI, CallIdHeader callIdHeader, CSeqHeader cSeqHeader, FromHeader fromHeader, ToHeader toHeader, ViaHeader[] viaHeaders)
Constructor of CancelMessage

Methods inherited from class jain.protocol.ip.sip.message.RequestMessage

addViaHeader, getAuthorizationHeader, getHideHeader, getMaxForwardsHeader, getMethod, getProxyAuthorizationHeader, getProxyRequireHeaders, getRequestURI, getRequireHeaders, getResponseKeyHeader, getRouteHeaders, getStartLine, hasAuthorizationHeader, hasHideHeader, hasMaxForwardsHeader, hasProxyAuthorizationHeader, hasProxyRequireHeaders, hasRequireHeaders, hasResponseKeyHeader, hasRouteHeaders, removeAuthorizationHeader, removeHideHeader, removeMaxForwardsHeader, removeProxyAuthorizationHeader, removeProxyRequireHeaders, removeRequireHeaders, removeResponseKeyHeader, removeRouteHeaders, setAuthorizationHeader, setHideHeader, setMaxForwardsHeader, setProxyAuthorizationHeader, setProxyRequireHeaders, setRequestURI, setRequireHeaders, setResponseKeyHeader, setRouteHeaders

Methods inherited from class jain.protocol.ip.sip.message.Message

addHeader, addHeaders, clone, equals, getAcceptEncodingHeaders, getAcceptHeaders, getAcceptLanguageHeaders, getAllHeaders, getBody, getCallIdHeader, getContactHeaders, getContentEncodingHeaders, getContentLengthHeader, getContentTypeHeader, getCSeqHeader, getDateHeader, getEncryptionHeader, getExpiresHeader, getFromHeader, getHeader, getHeaders, getOrganizationHeader, getRecordRouteHeaders, getRetryAfterHeader, getTimestampHeader, getToHeader, getUserAgentHeaders, getVersionMajor, getVersionMinor, getViaHeaders, hasAcceptEncodingHeaders, hasAcceptHeaders, hasAcceptLanguageHeaders, hasBody, hasContactHeaders, hasContentEncodingHeaders, hasContentLengthHeader, hasContentTypeHeader, hasDateHeader, hasEncryptionHeader, hasExpiresHeader, hasHeaders, hasOrganizationHeader, hasRecordRouteHeaders, hasRetryAfterHeader, hasTimestampHeader, hasUserAgentHeaders, isRequest, removeAcceptEncodingHeaders, removeAcceptHeaders, removeAcceptLanguageHeaders, removeBody, removeContactHeaders, removeContentEncodingHeaders, removeContentLengthHeader, removeDateHeader, removeEncryptionHeader, removeExpiresHeader, removeHeader, removeHeaders, removeOrganizationHeader, removeRecordRouteHeaders, removeRetryAfterHeader, removeTimestampHeader, removeUserAgentHeaders, setAcceptEncodingHeaders, setAcceptHeaders, setAcceptLanguageHeaders, setBody, setCallIdHeader, setContactHeaders, setContentEncodingHeaders, setContentLengthHeader, setContentTypeHeader, setCSeqHeader, setDateHeader, setEncryptionHeader, setExpiresHeader, setFromHeader, setHeader, setHeaders, setOrganizationHeader, setRecordRouteHeaders, setRetryAfterHeader, setTimestampHeader, setToHeader, setUserAgentHeaders, setVersion, setViaHeaders, toString

Methods inherited from class java.util.EventObject

getSource

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

method

public static final java.lang.String method

CancelMessage's method

Constructor Detail

CancelMessage

public CancelMessage(java.lang.Object source,
                     RequestMessage request)
              throws java.lang.IllegalArgumentException,
                     HeaderNotSetException

Constructor of CancelMessage based on sent RequestMessage

Parameters:

source - source of the CancelMessage

request - sent RequestMessage

Throws:

java.lang.IllegalArgumentException - if request is null

HeaderNotSetException - if request is missing any mandatory Headers

CancelMessage

public CancelMessage(java.lang.Object source,
                     URI requestURI,
                     CallIdHeader callIdHeader,
                     CSeqHeader cSeqHeader,
                     FromHeader fromHeader,
                     ToHeader toHeader,
                     ViaHeader[] viaHeaders)
              throws java.lang.IllegalArgumentException

Constructor of CancelMessage

Parameters:

source - source of the CancelMessage

requestURI - Request URI

callIdHeader - CallIdHeader

cSeqHeader - CSeqHeader

fromHeader - FromHeader

toHeader - ToHeader

viaHeaders - ViaHeaders

Throws:

java.lang.IllegalArgumentException - if any arguments are invalid