|
||||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||
See:
Description
| Packages | |
| jain.protocol.ip | This package contains the JAIN IP Factory, which is the central creation point for all high level proprietary JAIN IP objects, for example JainSipStack Objects. |
| jain.protocol.ip.sip | This package contains the main interfaces required to represent JAIN SIP protocol stacks, JAIN SIP applications, as well as the classes and exceptions needed to send and receive JAIN SIP messages. |
| jain.protocol.ip.sip.header | This package contains the classes representing SIP headers. |
| jain.protocol.ip.sip.message | This package contains the Event classes representing SIP Messages. |
Copyrights
Copyright - 2000 Sun Microsystems, Inc. All rights reserved.
901 San Antonio Road, Palo Alto, California 94043, U.S.A.
This product and related documentation are protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any.
RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19.
The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications.
TRADEMARKS
Sun, the Sun logo, Sun Microsystems, Java, Java Compatible, JavaBeans, Solaris,Write Once, Run Anywhere, JDK, Java Development Kit, and JavaStation are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. All other product names mentioned herein are the trademarks of their respective owners.
THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.
This document provides an overview of the JAIN SIP API, which is part of the JAIN SIP 1.0 Specification. It is not a tutorial, readers should have a good understanding of SIP and be comfortable reading the JAIN SIP API. This document, combined with the JAIN SIP API Requirements Specification, the JAIN SIP Reference Implementation (RI) Specification and the JAIN SIP Compatability Test Suite (CTS) Specification (described below) comprise the JAIN SIP 1.0 Specification.
The JainSipProvider interface defines the methods required to send SIP messages. This interface also defines the methods required to maintain a list of Event Listeners. An implementation of this interface would listen for SIP messages from the stack and forward these messages as Events to its registered Event Listeners. The SIP messages would be sent as Message Events.
Diagram 1 - Jain SIP message passing
An object implementing the JainSipProvider interface (a Provider) could
be vendor specific and would act as a proxy for a ListeningPoint of a SIP
Stack. Zero or more Event Listeners could register with a Provider, however
the JAIN SIP API provides the ability to limit the number of Event Listeners
that may register at any one time.
Diagram 2 - Listener registration with multiple Providers
The JainSipProvider interface defines the methods required to process any of the Events sent from a Provider. An object implementing the JainSipListener interface (a Listener) would register as an Event Listener of a Provider and would subsequently be able to receive Events from that Provider.
When a received SIP message arrives at the SIP Stack, the Provider forwards the SIP message as Message Events to its registered Listeners. Diagram 4.0 illustrates how an Event is distributed to Listeners.
Diagram 3 - Event Distribution
public class Listener implements JainSipListener {
// Obtain an instance of the Factory and set the path
JainIPFactory singleton = JainIPFactory.getInstance();singleton.setPath("com.dynamicsoft");
JainSipStack myStack = null;
try {
myStack = (JainSipStack)singleton.createIPObject("jain.protocol.ip.sip.JainSipStackImpl");myStack.setName("dynamicsoft.com SIP stack");
} catch (IPPeerUnavailableException e) {
// Couldn't find the class com.dynamicsoft.jain.protocol.ip.sip.JainSipStackImplSystem.err.println("The specified class could not be found in the CLASSPATH");
}ListeningPoint[] listeningPoints = null;
try {
listeningPoints = myStack.getListeningPoints();
} catch (ListeningPointUnavailableException e) {
// Stack has no ListeningPoints
System.err.println("The underlying stack currently has no ListeningPoints");
}
JainSipProvider myProvider = myStack.createProvider(listeningPoints[0]);
// Note: this Provider is attached (bound) to the underlying stack
// and will now receive all Message Events for the specified ListeningPoint
The JainSipProvider class will be used to send SIP messages into
the SIP stack, and will be used to listen for SIP messages from the SIP
stack. The User Application should register as a listener of the JainSipProviders
with the ListeningPoints it is interested in (each JainSipProvider has
its own ListeningPoint). Once a SIP message arrives, the underlying stack
should inspect the Request URI of the message and pass the message as a
Message Event to the JainSipProvider with that ListeningPoint. That JainSipProvider
will then send the Message Event to all its registered JainSipListeners.
// Register this User Application as an event Listener of the Provider
try {
myProvider.addJainSipListener(this);
} catch(TooManyListenersException e) {
/* A limit has
been reached on the number */
/* of Listeners
allowed per provider */
}
This class will use the processRequest()
method to process incoming new request messages, processAck()
method to process incoming Ack messages, processCancel()
to process incoming Cancel messages, processResponse()
to process incoming response messages, and processTimeout()
to process transaction timeouts.
Request message Events are created and sent to the Provider. First a request message is created as an Event, setting the Listener (this) as the Event source.
// create a From Address
SipURL fromAddress = new SipURL("caller", provider.getListeningPoint().getHost());
fromAddress.setPort(provider.getListeningPoint().getPort());
NameAddress from = new NameAddress("Caller", fromAddress);
// create a To Address
SipURL toAddress = new SipURL("callee", provider.getListeningPoint().getHost());
toAddress.setPort(provider.getListeningPoint().getPort());
NameAddress to = new NameAddress("Callee", toAddress);
// create SDP body for use within InviteMessage - could just use a String instead
ProtocolVersionField protocolVersionField = new ProtocolVersionField(0);
OriginField originField = new OriginField("charris", 1, 0, OriginField.NETWORK_TYPE_IN,
OriginField.ADDRESS_TYPE_IP4,
provider.getListeningPoint().getHost());
SessionNameField sessionNameField = new SessionNameField("Session name");
TimeField timeField = new TimeField(2000, 3000);
TimeDescription timeDescription = new TimeDescription(timeField);
TimeDescription[] timeDescriptions = new TimeDescription[]{timeDescription};
Object body = new SessionDescription(protocolVersionField, originField,
sessionNameField, timeDescriptions);
// create RequestURI for use within InviteMessage
URI requestURI = (URI)toAddress.clone();
((SipURL)requestURI).setTransport(provider.getListeningPoint().getTransport());
// Send Message
int clientTransactionId = -1;
try
{
// Send INVITE
clientTransactionId = provider.sendInvite(this, requestURI, fromAddress, toAddress, body, "application", "sdp");
...
// Send BYE
clientTransactionId = provider.sendBye(this,
(InviteMessage)provider.getClientTransactionRequest(clientTransactionId));
}
catch(SipException e)
{
e.printStackTrace();
}
SIP messages will be processed by the User Application's processXXX() methods.
public class JainSipListenerImpl implements JainSipListener {
Constructs a new JainSipListenerImpl, creates and registers with
a Provider.
public JainSipListenerImpl(JainSipProvider myProvider) {try {
myProvider.addJainSipListener(this);
} catch (TooManyListenersException tooManyListeners) {
System.err.println(tooManyListeners.getMessage());
}
}
// Processing of RequestMessage received.
public void processRequest(RequestMessage request, int transactionId){
JainSipProvider eventSource = (JainSipProvider)request.getSource();
// At this stage we only that the event is a RequestMessage
// therefore we find out the request method.String method = request.getMethod();
if (method.equals(InviteMessage.method)) {
try {
eventSource.sendResponse(transactionId, ResponseMessage.OK);
} catch (TransactionDoesNotExistException e) {
System.err.println(e.getMessage());
} catch (SipException e) {
System.err.println(e.getMessage());
}
} else if (method.equals(ByeMessage.method)) {
try {
eventSource.sendResponse(transactionId, ResponseMessage.OK);
} catch (TransactionDoesNotExistException e) {
System.err.println(e.getMessage());
} catch (SipException e) {
System.err.println(e.getMessage());
}
} else if (method.equals(AckMessage.method)) {
processAck(((AckMessage)request), transactionId);
} else if (method.equals(CancelMessage.method)) {
processCancel(((CancelMessage)request)), transactionId);
} else {
try {
eventSource.sendResponse(transactionId, ResponseMessage.METHOD_NOT_ALLOWED);
} catch (TransactionDoesNotExistException e) {
System.err.println(e.getMessage());
} catch (SipException e) {
System.err.println(e.getMessage());
}
}
}
// Processing of AckMessage received.
public void processAck(AckMessage ack, int transactionId){
JainSipProvider eventSource = (JainSipProvider)ack.getSource();
System.out.println("Received AckMessage on " + eventSource.getListeningPoint());
}
// Processing of CancelMessage received.
public void processCancel(CancelMessage cancel, int transactionId){
JainSipProvider eventSource = (JainSipProvider)cancel.getSource();
System.out.println("Received CancelMessage on " + eventSource.getListeningPoint());
}
// Processing of ResponseMessage received.
public void processResponse(ResponseMessage response, int transactionId){
JainSipProvider eventSource = (JainSipProvider)response.getSource();
String reasonPhrase = ResponseMessage.getStandardReasonPhrase(response.getStatusCode());
System.out.println("Received ResponseMessage with a status \" + reasonPhrase + "\"");
}
// Processing of transaction timeout.
public void processTimeout(int transactionId, boolean isServerTransaction){
System.out.println("Transaction " + transactionId + " timed out");
}
}
|
||||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||
Copyright - 2000 Sun Microsystems