javax.sip.header
Interface ReasonHeader

All Superinterfaces:

java.lang.Cloneable, Header, Parameters, java.io.Serializable

public interface ReasonHeader

extends Parameters, Header

This interface represents the Reason header, as defined by RFC3326, this header is not part of RFC3261.

The ReasonHeader provides information on why a SIP request was issued, often useful when creating services and also used to encapsulate a final status code in a provisional response, which is needed to resolve the "Heterogeneous Error Response Forking Problem".

The Reason header field appears to be most useful for BYE and CANCEL requests, but it can appear in any request within a dialog, in any CANCEL request and in 155 (Update Requested) responses. When used in requests, clients and servers are free to ignore this header field. It has no impact on protocol processing.

Examples of the ReasonHeader usage are:

• A SIP CANCEL request can be issued if the call has completed on another branch or was abandoned before answer. While the protocol and system behavior is the same in both cases, namely, alerting will cease, the user interface may well differ. In the second case, the call may be logged as a missed call, while this would not be appropriate if the call was picked up elsewhere.
• Third party call controllers sometimes generate a SIP request upon reception of a SIP response from another dialog. Gateways generate SIP requests after receiving messages from a different protocol than SIP. In both cases the client may be interested in knowing what triggered the SIP request.
• An INVITE can sometimes be rejected not because the session initiation was declined, but because some aspect of the request was not acceptable. If the INVITE forked and resulted in a rejection, the error response may never be forwarded to the client unless all the other branches also reject the request. This problem is known as the "Heterogeneous Error Response Forking Problem". The header field defined in this draft allows encapsulating the final error response in a 155 (Update Requested) provisional response.

A server must ignore Headers that it does not understand. A proxy must not remove or modify Headers that it does not understand.

Since:

1.1

Field Summary

static java.lang.String

NAME Name of ReasonHeader

Method Summary

int	getCause() Gets the cause value of the ReasonHeader
java.lang.String	getProtocol() Gets the protocol value of the ReasonHeader
java.lang.String	getText() Gets the text value of the ReasonHeader
void	setCause(int cause) Sets the cause value of the ReasonHeader.
void	setProtocol(java.lang.String protocol) Sets the protocol of the ReasonHeader, for example SIP or Q.850.
void	setText(java.lang.String text) Sets the text value of the ReasonHeader.

Methods inherited from interface javax.sip.header.Parameters

getParameter, getParameterNames, removeParameter, setParameter

Methods inherited from interface javax.sip.header.Header

clone, equals, getName, toString

Field Detail

NAME

public static final java.lang.String NAME

Name of ReasonHeader

See Also:

Constant Field Values

Method Detail

getCause

public int getCause()

Gets the cause value of the ReasonHeader

Returns:

the integer value of the cause of the ReasonHeader

setCause

public void setCause(int cause)
              throws InvalidArgumentException

Sets the cause value of the ReasonHeader. Any SIP status code MAY appear in the Reason header field of a request, assuming the protocol field of the ReasonHeader is SIP.

Parameters:

cause - - the new integer value of the cause of the ReasonHeader

Throws:

InvalidArgumentException - if the cause value is less than zero.

setProtocol

public void setProtocol(java.lang.String protocol)
                 throws java.text.ParseException

Sets the protocol of the ReasonHeader, for example SIP or Q.850.

Parameters:

protocol - - the new string value of the protocol of the ReasonHeader

Throws:

java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the protocol value.

getProtocol

public java.lang.String getProtocol()

Gets the protocol value of the ReasonHeader

Returns:

the string value of the protocol of the ReasonHeader

setText

public void setText(java.lang.String text)
             throws java.text.ParseException

Sets the text value of the ReasonHeader.

Parameters:

text - - the new string value of the text of the ReasonHeader

Throws:

java.text.ParseException - which signals that an error has been reached unexpectedly while parsing the text value.

getText

public java.lang.String getText()

Gets the text value of the ReasonHeader

Returns:

the string value of the text of the ReasonHeader