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 ":" 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 ";" "<" ">"
 

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

Example headers:

Call-ID: a84b4c76e66710

Call-ID header with no parameters

From: Bob <sip:[email protected]>;tag=a6c85cf

From header with parameter 'tag'

Contact: <sip:[email protected]>

Contact header with no parameters

Via: SIP/2.0/UDP pc33.atlanta.com;branch=z9hG4bKhjhs8ass877

Via header with parameter 'branch'

Contact: "Mr. Watson" <sip:[email protected]>;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)
          throws java.lang.IllegalArgumentException

Constructs a SipHeader from name value pair. For example:

name = Contact

value = <sip:[email protected]>;expires=3600

Parameters:

name - name of the header (Contact, Call-ID, ...)

headerValue - full header value as String

Throws:

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

Method Detail

setName

public void setName(java.lang.String name)
             throws java.lang.IllegalArgumentException

Sets the header name, for example Contact

Throws:

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:[email protected]>;expires=3600 method returns <sip:[email protected]>
In the case of an authorization or authentication header getValue() returns only the authentication scheme e.g. "Digest".

Returns:

header value without header parameters

getHeaderValue

public java.lang.String getHeaderValue()

Returns the full header value including parameters. For example "Alice <sip:[email protected]>;tag=1928301774"

Returns:

full header value including parameters

setValue

public void setValue(java.lang.String value)
              throws java.lang.IllegalArgumentException

Sets the header value as String without parameters. For example "<sip:[email protected]>". The existing (if any) header parameter values are not modified. For the authorization and authentication header this method sets the authentication scheme e.g. "Digest".

Throws:

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

getParameter

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

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

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.

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)
                  throws java.lang.IllegalArgumentException

Sets value of header parameter. If parameter does not exist it will be added. For example, for header value "<sip:[email protected]>" calling setParameter("expires", "3600") will construct header value "<sip:[email protected]>;expires=3600".
If the value is null, the parameter is interpreted as a parameter without value.

Parameters:

name - name of the header parameter

value - value of the parameter

Throws:

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

toString

public java.lang.String toString()

Returns the String representation of the header according to header type. For example:

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