Overview  Package   Class  Use  Tree  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.microedition.sip
Class SipHeader

java.lang.Object
  extended by 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

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.

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

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

getName

public java.lang.String getName()

Returns the name of this header

Returns:
the name of this header as String

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.

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.

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

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

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

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.

toString

public java.lang.String toString()

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

For example:

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
Overview  Package   Class  Use  Tree  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2002-2010 Nokia. All Rights Reserved.