jain.protocol.ip.sip.header
Class ToHeader

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

public final class ToHeader

extends GeneralHeader

This class represents the To general-header. The ToHeader specifies the recipient of the RequestMessage, with the same NameAddress rules as the FromHeader.

RequestMessages and ResponseMessages must contain a ToHeader, indicating the desired recipient of the request using the NameAddress. The optional display-name of the NameAddress is meant to be rendered by a human-user interface. The UAS or redirect server copies the ToHeader into its ResponseMessage, and must add a tag if the RequestMessage contained more than one ViaHeader.

If there was more than one ViaHeader, the RequestMessage was handled by at least one proxy server. Since the receiver cannot know whether any of the proxy servers forked the request, it is safest to assume that they might have.

The SipURL of the NameAddress must not contain the transport, maddr, ttl, or headers elements. A server that receives a SipURL with these elements removes them before further processing.

The tag serves as a general mechanism to distinguish multiple instances of a user identified by a single SipURL. As proxies can fork RequestMessages, the same RequestMessage can reach multiple instances of a user (mobile and home phones, for example). As each can respond, there needs to be a means to distinguish the ResponseMessages from each other at the caller. The situation also arises with multicast RequestMessages. The tag in the ToHeader serves to distinguish ResponseMessages at the UAC. It must be placed in the ToHeader of the ResponseMessage by each instance when there is a possibility that the RequestMessage was forked at an intermediate proxy. The tag must be added by UAS, registrars and redirect servers, but must not be inserted into ResponseMessages forwarded upstream by proxies. The tag is added for all definitive ResponseMessages for all RequestMessages, and may be added for informational ResponseMessages from a UAS or redirect server. All subsequent transactions between two entities must include the tag.

The tag in ToHeaders is ignored when matching ResponseMessages to RequestMessages that did not contain a tag in their ToHeader.

A SIP server returns a BAD_REQUEST ResponseMessage if it receives a RequestMessage with a ToHeader containing a URI with a scheme it does not recognize.

CallIdHeader, ToHeader and FromHeader are needed to identify a call leg. The distinction between call and call leg matters in calls with multiple ResponseMessages from a forked RequestMessage. The tag is added to the ToHeader in the ResponseMessage to allow forking of future RequestMessages for the same call by proxies, while addressing only one of the possibly several responding user agent servers. It also allows several instances of the callee to send RequestMessages that can be distinguished.

Version:

0.6

Field Summary

static java.lang.String

token Token of ToHeader

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

ENTITY_HEADER, GENERAL_HEADER, REQUEST_HEADER, RESPONSE_HEADER

Constructor Summary

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

Method Summary

java.lang.Object	clone() Creates and returns a copy of ToHeader
boolean	equals(ToHeader toHeader) Indicates whether some other ToHeader is "equal to" this one
NameAddress	getNameAddress() Gets NameAddress of ToHeader
java.lang.String	getTag() Gets tag of ToHeader
java.lang.String	getValue() Gets value of ToHeader
boolean	hasTag() Returns boolean value indicating if ToHeader has tag
void	removeTag() Removes tag from ToHeader
void	setNameAddress(NameAddress nameAddress) Sets NameAddress of ToHeader
void	setTag(java.lang.String tag) Sets tag of ToHeader

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 ToHeader

Constructor Detail

ToHeader

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

Creates a ToHeader based on given NameAddress

Parameters:

nameAddress - NameAddress

Throws:

java.lang.IllegalArgumentException - if nameAddress is null

Method Detail

getNameAddress

public NameAddress getNameAddress()

Gets NameAddress of ToHeader

Returns:

NameAddress of ToHeader

getTag

public java.lang.String getTag()
                        throws ParameterNotSetException

Gets tag of ToHeader

Returns:

tag of ToHeader

Throws:

ParameterNotSetException - if tag does not exist

removeTag

public void removeTag()

Removes tag from ToHeader

setNameAddress

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

Sets NameAddress of ToHeader

Parameters:

nameAddress - NameAddress

Throws:

java.lang.IllegalArgumentException - if nameAddress is null

setTag

public void setTag(java.lang.String tag)

Sets tag of ToHeader

Parameters:

tag - tag

Throws:

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

hasTag

public boolean hasTag()

Returns boolean value indicating if ToHeader has tag

Returns:

boolean value indicating if ToHeader has tag

getValue

public java.lang.String getValue()

Gets value of ToHeader

Overrides:

getValue in class Header

Returns:

value of ToHeader

clone

public java.lang.Object clone()

Creates and returns a copy of ToHeader

Overrides:

clone in class Header

equals

public boolean equals(ToHeader toHeader)

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

Parameters:

toHeader - the ToHeader with which to compare