Micah Sherr
Columbia University
COMS6901
Dr. Schulzrinne, Xiaotao Wu



Hidden PingTel API Functionality


Listening for a SIP message.

To listen to a SIP message, one must create a SIP message listener.  First, extend the class SipAgent.  The constructor of this class should call the constructor of the parent class (via super) with the name of the SIP call that is to be captured, e.g., super("MESSAGE");)  The class should also contain the method

public void handleMessage( SipMessage message )

which is executed whenever an incoming message of the appropriate type arrives (following our example, whenever a SIP "MESSAGE" arrives).  The program can then rely on the following methods for the SipMessage object:

Method
 Description
String SipMessage.getHeaderFieldValue("header");
 Returns the value of a given header.  If the header does not exist in the message, NULL is returned.
Byte[] SipMessage.getBody();
 Returns the body or payload of the SIP message, if one exists.

To send a SIP response message, the user should execute the following code:
SipRequest request = (SipRequest)message;
SipResponse response = request.buildResponse( 200, "OK" );
SipUserAgent.getInstance().postMessage( response );
The above example shows the case of sending a 200 response code back to the original sender.  Any valid SIP response and response string may be sent.

Once the listener is coded, the application must start the listener.  Outside the listener, perhaps in the main() method of the application, the listener must be explicitly started.  E.g.,

        objMsgListener = new MESSAGEListener();
        objMsgListener.start();

The corresponding call,

        objMsgListener.stop();

will stop the listener.

When creating a listener, be sure to import the following packages:

    com.pingtel.sip.*;
    com.pingtel.sip.event.*;



Sending a SIP message.

Equally important as capturing incoming messages is the ability to send outgoing SIP calls.  

First, instantiate a new SipRequest

        sipRequest = new SipRequest();

Next, set the SIP message's fields:

        sipRequest.setRequestHeader( "DO", sForeignSipAddress );
        sipRequest.setHeaderFieldValue( "To", sForeignSipAddress );
        sipRequest.setHeaderFieldValue( "From", sRegisteredName );
        sipRequest.setHeaderFieldValue( "Call-Id", sCallID );
        sipRequest.setHeaderFieldValue( "CSeq", "1 DO" );
        sipRequest.setHeaderFieldValue( "Contact", sRegisteredName );
        sipRequest.setHeaderFieldValue( "Priority", "normal" );
        sipRequest.setHeaderFieldValue( "Expires", "3600" );       
        sipRequest.setHeaderFieldValue( "Date", new Date().toString() );
        sipRequest.setHeaderFieldValue( "Content-Type", "application/dmp" );

Note that both arguments to setHeaderFieldValue are Strings.  The same is true for setRequestHeader.

To set the body or payload of the SIP message, use:

        sipRequest.setBody( bytes );

Note that bytes is a Java array of type byte, not String.

Once the request has been created, there are two methods of sending it off.  The first and the simplest is to send the message without waiting for a response code.

                    SipUserAgent.getInstance().postMessage( sipRequest );

The second is the send the request and block until either a response is received or a timeout occurs.

        SipResponse response = SipUserAgent.getInstance().sendRequest( sipRequest );

Once a response is received, the methods mentioned in the listener section, e.g., getHeaderFieldValue and getBody may be used to retrieve information about the response.