javax.sip.header
Interface WarningHeader

All Superinterfaces:

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

public interface WarningHeader
extends Header

The Warning header field is used to carry additional information about the status of a response. Warning header field values are sent with responses and contain a three-digit warning code, agent name, and warning text.

• Warning Text: The "warn-text" should be in a natural language that is most likely to be intelligible to the human user receiving the response. This decision can be based on any available knowledge, such as the location of the user, the Accept-Language field in a request, or the Content-Language field in a response.
• Warning Code: The currently-defined "warn-code"s have a recommended warn-text in English and a description of their meaning. These warnings describe failures induced by the session description. The first digit of warning codes beginning with "3" indicates warnings specific to SIP. Warnings 300 through 329 are reserved for indicating problems with keywords in the session description, 330 through 339 are warnings related to basic network services requested in the session description, 370 through 379 are warnings related to quantitative QoS parameters requested in the session description, and 390 through 399 are miscellaneous warnings that do not fall into one of the above categories. Additional "warn-code"s can be defined.

Any server may add WarningHeaders to a Response. Proxy servers must place additional WarningHeaders before any AuthorizationHeaders. Within that constraint, WarningHeaders must be added after any existing WarningHeaders not covered by a signature. A proxy server must not delete any WarningHeader that it received with a Response.

When multiple WarningHeaders are attached to a Response, the user agent should display as many of them as possible, in the order that they appear in the Response. If it is not possible to display all of the warnings, the user agent first displays warnings that appear early in the Response.

Examples of using Warning Headers are as follows:

• A UAS rejecting an offer contained in an INVITE SHOULD return a 488 (Not Acceptable Here) response. Such a response SHOULD include a Warning header field value explaining why the offer was rejected.
• If the new session description is not acceptable, the UAS can reject it by returning a 488 (Not Acceptable Here) response for the re-INVITE. This response SHOULD include a Warning header field.
• A 606 (Not Acceptable) response means that the user wishes to communicate, but cannot adequately support the session described. The 606 (Not Acceptable) response MAY contain a list of reasons in a Warning header field describing why the session described cannot be supported.
• Contact header fields MAY be present in a 200 (OK) response and have the same semantics as in a 3xx response. That is, they may list a set of alternative names and methods of reaching the user. A Warning header field MAY be present.

For Example:
Warning: 307 isi.edu "Session parameter 'foo' not understood"

Author:

BEA Systems, NIST

Field Summary

static int	ATTRIBUTE_NOT_UNDERSTOOD One or more of the media attributes in the session description are not supported.
static int	INCOMPATIBLE_BANDWIDTH_UNITS One or more bandwidth measurement units contained in the session description were not understood.
static int	INCOMPATIBLE_MEDIA_FORMAT One or more media formats contained in the session description are not available.
static int	INCOMPATIBLE_NETWORK_ADDRESS_FORMATS One or more network address formats contained in the session description are not available.
static int	INCOMPATIBLE_NETWORK_PROTOCOL One or more network protocols contained in the session description are not available.
static int	INCOMPATIBLE_TRANSPORT_PROTOCOL One or more transport protocols described in the session description are not available.
static int	INSUFFICIENT_BANDWIDTH The bandwidth specified in the session description or defined by the media exceeds that known to be available.
static int	MEDIA_TYPE_NOT_AVAILABLE One or more media types contained in the session description are not available.
static int	MISCELLANEOUS_WARNING The warning text can include arbitrary information to be presented to a human user, or logged.
static int	MULTICAST_NOT_AVAILABLE The site where the user is located does not support multicast.
static java.lang.String	NAME Name of WarningHeader
static int	SESSION_DESCRIPTION_PARAMETER_NOT_UNDERSTOOD A parameter other than those listed above was not understood.
static int	UNICAST_NOT_AVAILABLE The site where the user is located does not support unicast communication (usually due to the presence of a firewall).

Method Summary

java.lang.String	getAgent() Gets the agent of the server that created this WarningHeader.
int	getCode() Gets the code of the WarningHeader.
java.lang.String	getText() Gets text of WarningHeader.
void	setAgent(java.lang.String agent) Sets the agent value of the WarningHeader to the new value passed to the method.
void	setCode(int code) Sets the code of the WarningHeader.
void	setText(java.lang.String text) Sets the text of WarningHeader to the newly supplied text value.

Methods inherited from interface javax.sip.header.Header

clone, equals, getName, hashCode, toString

Field Detail

NAME

static final java.lang.String NAME

Name of WarningHeader

See Also:

Constant Field Values

INCOMPATIBLE_NETWORK_PROTOCOL

static final int INCOMPATIBLE_NETWORK_PROTOCOL

One or more network protocols contained in the session description are not available.

See Also:

Constant Field Values

INCOMPATIBLE_NETWORK_ADDRESS_FORMATS

static final int INCOMPATIBLE_NETWORK_ADDRESS_FORMATS

One or more network address formats contained in the session description are not available.

See Also:

Constant Field Values

INCOMPATIBLE_TRANSPORT_PROTOCOL

static final int INCOMPATIBLE_TRANSPORT_PROTOCOL

One or more transport protocols described in the session description are not available.

See Also:

Constant Field Values

INCOMPATIBLE_BANDWIDTH_UNITS

static final int INCOMPATIBLE_BANDWIDTH_UNITS

One or more bandwidth measurement units contained in the session description were not understood.

See Also:

Constant Field Values

MEDIA_TYPE_NOT_AVAILABLE

static final int MEDIA_TYPE_NOT_AVAILABLE

One or more media types contained in the session description are not available.

See Also:

Constant Field Values

INCOMPATIBLE_MEDIA_FORMAT

static final int INCOMPATIBLE_MEDIA_FORMAT

One or more media formats contained in the session description are not available.

See Also:

Constant Field Values

ATTRIBUTE_NOT_UNDERSTOOD

static final int ATTRIBUTE_NOT_UNDERSTOOD

One or more of the media attributes in the session description are not supported.

See Also:

Constant Field Values

SESSION_DESCRIPTION_PARAMETER_NOT_UNDERSTOOD

static final int SESSION_DESCRIPTION_PARAMETER_NOT_UNDERSTOOD

A parameter other than those listed above was not understood.

See Also:

Constant Field Values

MULTICAST_NOT_AVAILABLE

static final int MULTICAST_NOT_AVAILABLE

The site where the user is located does not support multicast.

See Also:

Constant Field Values

UNICAST_NOT_AVAILABLE

static final int UNICAST_NOT_AVAILABLE

The site where the user is located does not support unicast communication (usually due to the presence of a firewall).

See Also:

Constant Field Values

INSUFFICIENT_BANDWIDTH

static final int INSUFFICIENT_BANDWIDTH

The bandwidth specified in the session description or defined by the media exceeds that known to be available.

See Also:

Constant Field Values

MISCELLANEOUS_WARNING

static final int MISCELLANEOUS_WARNING

The warning text can include arbitrary information to be presented to a human user, or logged. A system receiving this warning MUST NOT take any automated action.

See Also:

Constant Field Values

Method Detail

getAgent

java.lang.String getAgent()

Gets the agent of the server that created this WarningHeader.

Returns:

the agent of the WarningHeader

setAgent

void setAgent(java.lang.String agent)
              throws java.text.ParseException

Sets the agent value of the WarningHeader to the new value passed to the method.

Parameters:

agent - - the new agent value of WarningHeader

Throws:

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

getText

java.lang.String getText()

Gets text of WarningHeader.

Returns:

the string text value of the WarningHeader.

setText

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

Sets the text of WarningHeader to the newly supplied text value.

Parameters:

text - - the new text value of the Warning Header.

Throws:

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

setCode

void setCode(int code)
             throws InvalidArgumentException

Sets the code of the WarningHeader. The standard RFC3261 codes are defined as constants in this class.

Parameters:

code - - the new code that defines the warning code.

Throws:

InvalidArgumentException - if an invalid integer code is given for the WarningHeader.

getCode

int getCode()

Gets the code of the WarningHeader.

Returns:

the integer code value of the WarningHeader