jain.protocol.ip.sip.header
Class ContactHeader

java.lang.Object
  |
  +--jain.protocol.ip.sip.header.Header
        |
        +--jain.protocol.ip.sip.header.GeneralHeader
              |
              +--jain.protocol.ip.sip.header.ContactHeader

public final class ContactHeader

extends GeneralHeader

This class represents the Contact general-header. A ContactHeader field can appear in InviteMessage, AckMessage and RegisterMessages, and in ResponseMessages with any INFORMATIONAL, SUCCESS, REDIRECT, or CLIENT_ERROR_AMBIGUOUS status codes. In general, it provides a URL where the user can be reached for further communications.

InviteMessages and AckMessages: InviteMessages and AckMessages may contain ContactHeaders indicating from which location the request is originating.

This allows the callee to send future requests, such as ByeMessages, directly to the caller instead of through a series of proxies. The ViaHeader is not sufficient since the desired address may be that of a proxy.

SUCCESS ResponseMessages for InviteMessages: A user agent server sending a definitive, positive response (SUCCESS) may insert a ContactHeader in the ResponseMessage indicating the SIP address under which it is reachable most directly for future SIP requests, such as AckMessage, within the same Call-ID. The ContactHeader contains the address of the server itself or that of a proxy, e.g., if the host is behind a firewall. The value of this Contact header is copied into the Request-URI of subsequent requests for this call if the response did not also contain a RecordRouteHeader. If the response also contains a RecordRouteHeader, the address in the ContactHeader is added as the last item in the RouteHeader. See RecordRouteHeader for details.

The ContactHeader should not be cached across calls, as it may not represent the most desirable location for a particular destination address.

INFORMATIONAL ResponseMessages for InviteMessages: A server sending an INFORMATIONAL ResponseMessage may insert a ContactHeader. It has the same semantics in an INFORMATIONAL ResponseMessage as a SUCCESS ResponseMessage. Note that CancelMessages must not be sent to that address, but rather follow the same path as the original request.

RegisterMessages: RegisterMessages may contain ContactHeaders indicating at which locations the user is reachable. The RegisterMessage defines a wildcard ContactHeader which must only be used with Expires set to 0 to remove all registrations for a particular user. An optional "expires" parameter indicates the desired expiration time of the registration. If a ContactHeader does not have an "expires" parameter, the ExpiresHeader field is used as the default value. If neither of these mechanisms is used, SIP URIs are assumed to expire after one hour. Other URI schemes have no expiration times.

SUCCESS ResponseMessages for RegisterMessages: A ResponseMessage for a RegisterMessage may return all locations at which the user is currently reachable. An optional "expires" parameter indicates the expiration time of the registration. If a ContactHeader does not have an "expires" parameter, the value of the ExpiresHeader indicates the expiration time. If neither mechanism is used, the expiration time specified in the request, explicitly or by default, is used.

REDIRECTION and CLIENT_ERROR_AMBIGUOUS ResponseMessages: The ContactHeader can be used with a REDIRECTION or CLIENT_ERROR_AMBIGUOUS ResponseMessage to indicate one or more alternate addresses to try. It can appear in ResponseMessages for ByeMessages, InviteMessages and OptionsMessage. ContactHeaders contain URIs giving the new locations or user names to try, or may simply specify additional transport parameters. A REDIRECTION_MULTIPLE_CHOICES, REDIRECTION_MOVED_PERMANENTLY, REDIRECTION_MOVED_TEMPORARILY, CLIENT_ERROR_AMBIGUOUS ResponseMessage should contain one or more ContactHeaders containing URIs of new addresses to be tried. A REDIRECTION_MOVED_PERMANENTLY or REDIRECTION_MOVED_TEMPORARILY ResponseMessage may also give the same location and username that was being tried but specify additional transport parameters such as a different server or multicast address to try or a change of SIP transport from UDP to TCP or vice versa. The client copies the "user", "password", "host", "port" and "user-param" elements of the Contact URI into the Request-URI of the redirected request and directs the request to the address specified by the "maddr" and "port" parameters, using the transport protocol given in the "transport" parameter. If "maddr" is a multicast address, the value of "ttl" is used as the time-to-live value.

Note that the ContactHeader field may also refer to a different entity than the one originally called. For example, a SIP call connected to GSTN gateway may need to deliver a special information announcement such as "The number you have dialed has been changed."

A ContactHeader in a ResponseMessage can contain any suitable URI indicating where the called party can be reached, not limited to SIP URLs. For example, it could contain URL's for phones, fax, or irc (if they were defined) or a mailto: URL.

The following parameters are defined.

q: The "qvalue" indicates the relative preference among the locations given. "qvalue" values are decimal numbers from 0 to 1, with higher values indicating higher preference.

action: The "action" parameter is used only when registering with the RegisterMessage. It indicates whether the client wishes that the server proxy or redirect future requests intended for the client. If this parameter is not specified the action taken depends on server configuration. In its response, the registrar should indicate the mode used. This parameter is ignored for other requests.

expires: The "expires" parameter indicates how long the URI is valid. The parameter is either a number indicating seconds or a quoted string containing a SIP-date. If this parameter is not provided, the value of the ExpiresHeader determines how long the URI is valid. Implementations may treat values larger than 2**32-1 (4294967295 seconds or 136 years) as equivalent to 2**32-1.

Version:

0.6

See Also:

RecordRouteHeader

Field Summary

static int	ACTION_PROXY
static int	ACTION_REDIRECT
static java.lang.String	token Token of ContactHeader

Fields inherited from class jain.protocol.ip.sip.header.Header

ENTITY_HEADER, GENERAL_HEADER, REQUEST_HEADER, RESPONSE_HEADER

Constructor Summary

ContactHeader()
Creates a wildcard ContactHeader.

ContactHeader(NameAddress nameAddress)
Creates a ContactHeader based on given NameAddress

Method Summary

java.lang.Object	clone() Creates and returns copy of ContactHeader
boolean	equals(ContactHeader contactHeader) Indicates whether some other ContactHeader is "equal to" this one
int	getAction() Gets action of ContactHeader
java.lang.String	getComment() Gets comment of ContactHeader
java.util.Date	getExpiryDate() Gets expiry date of ContactHeader
long	getExpiryDeltaSeconds() Gets expiry delta-seconds of ContactHeader
java.lang.String	getExtension(java.lang.String extension) Gets the value of specified extension parameter in ContactHeader
java.lang.String[]	getExtensions() Gets an array of the names of ContactHeader's extension parameters
NameAddress	getNameAddress() Gets NameAddress of ContactHeader
float	getQValue() Gets q-value of ContactHeader
java.lang.String	getValue() Gets value of ContactHeader
boolean	hasAction() Gets boolean value to indicate if ContactHeader has action
boolean	hasComment() Gets boolean value to indicate if ContactHeader has comment
boolean	hasExpires() Gets boolean value to indicate if ContactHeader has expires value
boolean	hasExpiryDate() Gets boolean value to indicate if ContactHeader has expiry value that is a date
boolean	hasExtension(java.lang.String extension) Gets boolean value to indicate if ContactHeader has specified extension parameter
boolean	hasExtensions() Gets boolean value to indicate if ContactHeader has extension parameters
boolean	hasQValue() Gets boolean value to indicate if ContactHeader has q-value
boolean	isWildCard() Returns boolean value indicating whether ContactHeader is a wild card
void	removeAction() Removes action from ContactHeader
void	removeExpires() Removes expires value from ContactHeader
void	removeExtension(java.lang.String extension) Removes specified extension parameter from ContactHeader
void	removeExtensions() Removes all extension parameters from ContactHeader
void	removeQValue() Removes q-value from ContactHeader
void	setAction(int action) Sets action of ContactHeader
void	setComment(java.lang.String comment) Sets comment of ContactHeader
void	setExpiryDate(java.util.Date expiryDate) Sets expiry value of ContactHeader to a date
void	setExpiryDeltaSeconds(long expiryDeltaSeconds) Sets expiry value of ContactHeader to a number of delta-seconds
void	setExtension(java.lang.String extension, java.lang.String value) Sets value of extension parameter to value in ContactHeader
void	setNameAddress(NameAddress nameAddress) Sets NameAddress of ContactHeader
void	setQvalue(float qValue) Sets q-value of ContactHeader

Methods inherited from class jain.protocol.ip.sip.header.Header

equals, getHeaderType, getToken, setValue, toString

Methods inherited from class java.lang.Object

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

Field Detail

token

public static final java.lang.String token

Token of ContactHeader

ACTION_PROXY

public static final int ACTION_PROXY

ACTION_REDIRECT

public static final int ACTION_REDIRECT

Constructor Detail

ContactHeader

public ContactHeader(NameAddress nameAddress)
              throws java.lang.IllegalArgumentException

Creates a ContactHeader based on given NameAddress

Parameters:

nameAddress - NameAddress

Throws:

java.lang.IllegalArgumentException - if nameAddress is null

ContactHeader

public ContactHeader()

Creates a wildcard ContactHeader. This is used in RegisterMessages to indicate to the server that it should remove all locations the at which the user is currently available

Method Detail

isWildCard

public boolean isWildCard()

Returns boolean value indicating whether ContactHeader is a wild card

Returns:

boolean value indicating whether ContactHeader is a wild card

getComment

public java.lang.String getComment()
                            throws ParameterNotSetException

Gets comment of ContactHeader

Returns:

comment of ContactHeader

Throws:

ParameterNotSetException - if comment does not exist

setComment

public void setComment(java.lang.String comment)
                throws java.lang.IllegalArgumentException

Sets comment of ContactHeader

Parameters:

comment - comment

Throws:

java.lang.IllegalArgumentException - if comment is null or zero-length

hasExtension

public boolean hasExtension(java.lang.String extension)

Gets boolean value to indicate if ContactHeader has specified extension parameter

Returns:

boolean value to indicate if the ContactHeader has specified extension parameter

getNameAddress

public NameAddress getNameAddress()
                           throws ParameterNotSetException

Gets NameAddress of ContactHeader

Returns:

NameAddress of ContactHeader

Throws:

ParameterNotSetException - if NameAddress does not exist i.e. ContactHeader is a wildcard

setExtension

public void setExtension(java.lang.String extension,
                         java.lang.String value)
                  throws java.lang.IllegalArgumentException

Sets value of extension parameter to value in ContactHeader

Parameters:

extension - name of extension parameter

value - value of extension parameter

Throws:

java.lang.IllegalArgumentException - if extension or value are null or zero-length

removeExtension

public void removeExtension(java.lang.String extension)

Removes specified extension parameter from ContactHeader

Parameters:

extension - extension parameter to remove from AcceptHeader

removeExtensions

public void removeExtensions()

Removes all extension parameters from ContactHeader

getExtensions

public java.lang.String[] getExtensions()
                                 throws ParameterNotSetException

Gets an array of the names of ContactHeader's extension parameters

Returns:

an array of the names of ContactHeader's extension parameters

Throws:

ParameterNotSetException - if ContactHeader has no extension parameters

getExtension

public java.lang.String getExtension(java.lang.String extension)
                              throws ParameterNotSetException

Gets the value of specified extension parameter in ContactHeader

Parameters:

extension - extension parameter to retrieve

Returns:

the value of specified extension parameter in ContactHeader

Throws:

ParameterNotSetException - if the extension parameter does not exist

setNameAddress

public void setNameAddress(NameAddress nameAddress)
                    throws java.lang.IllegalArgumentException

Sets NameAddress of ContactHeader

Parameters:

nameAddress - NameAddress

Throws:

java.lang.IllegalArgumentException - if nameAddress is null

getQValue

public float getQValue()
                throws ParameterNotSetException

Gets q-value of ContactHeader

Returns:

q-value of ContactHeader

Throws:

ParameterNotSetException - if q-value does not exist

hasAction

public boolean hasAction()

Gets boolean value to indicate if ContactHeader has action

Returns:

boolean value to indicate if ContactHeader has action

hasExtensions

public boolean hasExtensions()

Gets boolean value to indicate if ContactHeader has extension parameters

Returns:

boolean value to indicate if ContactHeader has extension parameters

hasQValue

public boolean hasQValue()

Gets boolean value to indicate if ContactHeader has q-value

Returns:

boolean value to indicate if ContactHeader has q-value

hasExpires

public boolean hasExpires()

Gets boolean value to indicate if ContactHeader has expires value

Returns:

boolean value to indicate if ContactHeader has expires value

hasComment

public boolean hasComment()

Gets boolean value to indicate if ContactHeader has comment

Returns:

boolean value to indicate if ContactHeader has comment

hasExpiryDate

public boolean hasExpiryDate()

Gets boolean value to indicate if ContactHeader has expiry value that is a date

Returns:

boolean value to indicate if ContactHeader has expiry value that is a date

removeQValue

public void removeQValue()

Removes q-value from ContactHeader

setQvalue

public void setQvalue(float qValue)
               throws java.lang.IllegalArgumentException

Sets q-value of ContactHeader

Parameters:

qValue - q-value

Throws:

java.lang.IllegalArgumentException - if q-value is not between 0 and 1 inclusive

setAction

public void setAction(int action)
               throws java.lang.IllegalArgumentException

Sets action of ContactHeader

Parameters:

action - action (either ACTION_PROXY or ACTION_REDIRECT)

Throws:

java.lang.IllegalArgumentException - if action is neither ACTION_PROXY nor ACTION_REDIRECT

removeAction

public void removeAction()

Removes action from ContactHeader

getAction

public int getAction()
              throws ParameterNotSetException

Gets action of ContactHeader

Returns:

action of ContactHeader

Throws:

ParameterNotSetException - if action does not exist

setExpiryDeltaSeconds

public void setExpiryDeltaSeconds(long expiryDeltaSeconds)
                           throws java.lang.IllegalArgumentException

Sets expiry value of ContactHeader to a number of delta-seconds

Parameters:

expiryDeltaSeconds - number of delta-seconds until expiry

Throws:

java.lang.IllegalArgumentException - if expiryDeltaSeconds is negative

setExpiryDate

public void setExpiryDate(java.util.Date expiryDate)
                   throws java.lang.IllegalArgumentException

Sets expiry value of ContactHeader to a date

Parameters:

expiryDate - date of expiry

Throws:

java.lang.IllegalArgumentException - if expiryDate is null

removeExpires

public void removeExpires()

Removes expires value from ContactHeader

getExpiryDeltaSeconds

public long getExpiryDeltaSeconds()
                           throws ParameterNotSetException

Gets expiry delta-seconds of ContactHeader

Returns:

expiry delta-seconds of ContactHeader

Throws:

ParameterNotSetException - if expiry value does not exist, or is not in delta-seconds format

getExpiryDate

public java.util.Date getExpiryDate()
                             throws ParameterNotSetException

Gets expiry date of ContactHeader

Returns:

expiry date of ContactHeader

Throws:

ParameterNotSetException - if expiry value does not exist or if it is not in date format

getValue

public java.lang.String getValue()

Gets value of ContactHeader

Overrides:

getValue in class Header

Returns:

value of ContactHeader

clone

public java.lang.Object clone()

Creates and returns copy of ContactHeader

Overrides:

clone in class Header

Returns:

copy of ContactHeader

equals

public boolean equals(ContactHeader contactHeader)

Indicates whether some other ContactHeader is "equal to" this one

Parameters:

contactHeader - the ContactHeader with which to compare