javax.microedition.sip
Class SipHeader

java.lang.Object
  javax.microedition.sip.SipHeader

public class SipHeader
extends java.lang.Object

SipHeader provides generic SIP header parser helper. This class can be used to parse bare String header values that are read from SIP message using e.g. SipConnection.getHeader() method. It should be noticed that SipHeader is separate helper class and not mandatory to use for creating SIP connections. Correspondingly, SIP headers can be constructed with this class.SipHeader uses generic format to parse the header value and parameters following the syntax given in RFC 3261[1] p.31

• field-name: field-value *(;parameter-name=parameter-value)

SipHeader also supports parsing for the following authorization and authentication headers:WWW-Authenticate, Proxy-Authenticate, Proxy-Authorization, Authorization.For those a slightly different syntax is applied, where comma is used as the parameter separator instead of semicolon. Authentication parameters are accessible through get/set/removeParameter() methods in the same way as generic header parameters.

• auth-header-name: auth-scheme LWS auth-param *(COMMA auth-param)

The ABNF for the SipHeader parser is derived from SIP ABNF as follows:

    header         =  header-name HCOLON header-value *(";" generic-param) /
                      WWW-Authenticate / Proxy-Authenticate /
                      Proxy-Authorization / Authorization
    header-name    =  token
    generic-param  =  token [ EQUAL gen-value ]
    gen-value      =  token / host / quoted-string
    header-value   =  1*(chars) / name-addr
    chars          =  %x20-3A / "=" / %x3F-7E
                      ; any visible character except ";" "<" ">"
 

In addition the parser accepts headers that use the comment and quoted-string constructs, see 25.1 in [1].

Reference, SIP 3261 [1] p.159 Header Fields and p.219 SIP BNF for terminals not defined in this BNF.

Example headers:

Header	Explanation
Call-ID: a84b4c76e66710	Call-ID header with no parameters
From: Bob <sip:bob@biloxi.com>;tag=a6c85cf	From header with parameter 'tag'
Contact: <sip:alice@pc33.atlanta.com>	Contact header with no parameters
Via: SIP/2.0/UDP pc33.atlanta.com;branch=z9hG4bKhjhs8ass877	Via header with parameter 'branch'
Contact: "Mr. Watson" <sip:watson@worcester.bell-telephone.com>;q=0.7;expires=3600	Contact header with parameters 'q' and 'expires'
WWW-Authenticate: Digest realm="atlanta.com", domain="sip:boxesbybob.com", qop="auth", nonce="f84f1cec41e6cbe5aea9c8e88d359", opaque="", stale=FALSE, algorithm=MD5	WWW-Authenticate header with digest authentication scheme.

See Also:

SipAddress

Constructor Summary

SipHeader(java.lang.String name, java.lang.String headerValue)
Constructs a SipHeader from name value pair.

Method Summary

java.lang.String	getHeaderValue() Returns the full header value including parameters.
java.lang.String	getName() Returns the name of this header
java.lang.String	getParameter(java.lang.String name) Returns the value of one header parameter.
java.lang.String[]	getParameterNames() Returns the names of header parameters.
java.lang.String	getValue() Returns the header value without header parameters.
void	removeParameter(java.lang.String name) Removes the header parameter, if it is found in this header.
void	setName(java.lang.String name) Sets the header name, for example Contact
void	setParameter(java.lang.String name, java.lang.String value) Sets value of header parameter.
void	setValue(java.lang.String value) Sets the header value as String without parameters.
java.lang.String	toString() Returns the String representation of the header according to header type.

Methods inherited from class java.lang.Object

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

Constructor Detail

SipHeader

public SipHeader(java.lang.String name,
                 java.lang.String headerValue)

Constructs a SipHeader from name value pair. For example:

name = Contact

value = <sip:UserB@192.168.200.201>;expires=3600

It is allowed to give an empty String or null as the value parameter. This can be convenient when the user wants to fill the value and/or parameters later.

Parameters:

name - name of the header (Contact, Call-ID, ...). Leading and trailing spaces are ignored.

headerValue - full header value as String. It can be null or empty String. Leading and trailing spaces are ignored.

Throws:

java.lang.IllegalArgumentException - if the header value or name are invalid

java.lang.NullPointerException - if name is null

Method Detail

setName

public void setName(java.lang.String name)

Sets the header name, for example Contact

Parameters:

name - name of the header. Leading and trailing spaces are ignored.

Throws:

java.lang.NullPointerException - if name is null

java.lang.IllegalArgumentException - if the name is invalid

getName

public java.lang.String getName()

Returns the name of this header

Returns:

the name of this header as String

getValue

public java.lang.String getValue()

Returns the header value without header parameters. For example for header

<sip:UserB@192.168.200.201>;expires=3600 the method returns

<sip:UserB@192.168.200.201>

In the case of an authorization or authentication header getValue() returns only the authentication scheme e.g. "Digest".

Returns:

header value without header parameters. It is an empty String if the value was set to be null or empty.

getHeaderValue

public java.lang.String getHeaderValue()

Returns the full header value including parameters. For example "Alice <sip:alice@atlanta.com>;tag=1928301774"

Returns:

full header value including parameters

setValue

public void setValue(java.lang.String value)

Sets the header value as String without parameters. For example "<sip:UserB@192.168.200.201>". The existing (if any) header parameter values are not modified. Empty string or null means a header with no value.

For the authorization and authentication header this method sets the authentication scheme e.g. "Digest".

Parameters:

value - the value of the header. Leading and trailing spaces are ignored.

Throws:

java.lang.IllegalArgumentException - if the value is invalid or there are parameters included.

getParameter

public java.lang.String getParameter(java.lang.String name)

Returns the value of one header parameter. For example, from value "<sip:UserB@192.168.200.201>;expires=3600" the method call getParameter("expires") will return 3600.

Note that for some header parameters the returned value includes quotation marks while for other parameters it does not. As an example, the expires parameter contains its value without quotation marks while the realm parameter value contains quotation marks. The applications must be prepared to handle this difference.

Parameters:

name - name of the header parameter

Returns:

value of header parameter. Returns empty string for a parameter without value and null if the parameter does not exist.

Throws:

java.lang.NullPointerException - if name is null

getParameterNames

public java.lang.String[] getParameterNames()

Returns the names of header parameters. Returns null if there are no header parameters.

Returns:

names of the header parameters. Returns null if there are no parameters.

setParameter

public void setParameter(java.lang.String name,
                         java.lang.String value)

Sets value of header parameter. If parameter does not exist it will be added. For example, for header value "<sip:UserB@192.168.200.201>" calling setParameter("expires", "3600") will construct header value "<sip:UserB@192.168.200.201>;expires=3600". If the value is null or empty String, the parameter is interpreted as a parameter without value.

Note that some header parameters require the presence of quotation marks around the parameter value while other parameters do not. As an example, the expires parameter contains its value without quotation marks while the realm parameter value contains quotation marks. The applications must be prepared to handle this difference.

Parameters:

name - name of the header parameter. Leading and trailing spaces are ignored.

value - value of the parameter. Leading and trailing spaces are ignored.

Throws:

java.lang.NullPointerException - if name is null

java.lang.IllegalArgumentException - if the parameter name or value are invalid

removeParameter

public void removeParameter(java.lang.String name)

Removes the header parameter, if it is found in this header.

Parameters:

name - name of the header parameter

Throws:

java.lang.NullPointerException - if name is null

toString

public java.lang.String toString()

Returns the String representation of the header according to header type.

For example:

• From: Alice <sip:alice@atlanta.com>;tag=1928301774
• WWW-Authenticate: Digest realm="atlanta.com", domain="sip:boxesbybob.com", qop="auth", nonce="f84f1cec41e6cbe5aea9c8e88d359", opaque="", stale=FALSE, algorithm=MD5

The value part of the header may be missing if the header was created with empty string or null as value and has not been set using setValue.

Overrides:

toString in class java.lang.Object