NIST SIP Parser and Stack (v1.2) API

javax.sip
Interface SipProvider

All Known Implementing Classes:
SipProviderImpl

public interface SipProvider

This interface represents the messaging entity of a SIP stack and as such is the interface that defines the messaging and transational component view of the SIP stack. It must be implemented by any object representing a SIP stack compliant to this specification that interacts directly with a proprietary implementation of a SIP stack. This interface defines the methods that enable any registered application implementing the SipListener interface to:

Architecture:
This specification defines a many-to-one relationship between a SipProvider and a SipStack, a one-to-one relationship between a SipProvider and a ListeningPoint and a many-to-one relationship between a SipProvider and a SipListener.

A SipProvider has the capability to behave both statefully and statelessly. The stateful (transactional) method defined specifically for a UAC and stateful proxy applications is:

The stateful (transactional) convenience method defined specifically for an UAS and stateful proxy applications include:

The stateless methods (non-transactional) defined on the SipProvider that can be used by any application include:

Transaction Model:
This specification supports stateful and stateless applications on a per message basis, hence transactional semantics are not mandated for all messages. This specification defines two types of transactions, server transactions and client transactions. A stateless proxy does not contain a client or server transaction, stateless proxies are effectively transparent with respect to transactions.

Client Transaction:
A client transaction exists between a UAC and a UAS specific to Request messages and a server transaction exists between a UAS and a UAC specific to Response messages. A transaction either server or client identifies messages sent between two SIP entities. The purpose of a client transaction is to identify a Request sent by an application that will reliably deliver the Request from the SipProvider implementation to a server transaction on the responding SIP entity. The purpose of a server transaction is to identify a Response sent by an application that will reliably deliver the Response from the SipProvider implementation to the request initiator.

Server Transaction:
A new server transaction is required for each response that an application decides to respond to statefully, as follows:

Sending Requests:
The client side of the transport layer is responsible for sending the request. The application passes the client transaction and the Request to the SipProvider that will send the Request over the ListeningPoint's port and transport. See section 18.1.1 of RFC3261.

Sending Responses:
The server side of the transport layer is responsible for sending the responses. The application passes the server transaction and the Response to the SipProvider that will send the Response over the ListeningPoint's port and transport. See section 18.2.2 of RFC3261.

Receiving Requests:
A SipProvider should be prepared to receive requests on any IP address, port and transport combination encapsulated in a ListeningPoint that can be the result of a DNS lookup on a SIP or SIPS URI that is handed out for the purposes of communicating with that server. It is also recommended that a SipProvider listen for requests on the default SIP ports on all public interfaces. When the SipProvider receives a request over any transport, it must examine the value of the "sent-by" parameter in the top Via header. If the host portion of the "sent-by" parameter contains a domain name, or if it contains an IP address that differs from the packet source address, the server must add a "received" parameter to that Via header field value. This parameter must contain the source address from which the packet was received. This is to assist the SipProvider in sending the response, since it must be sent to the source IP address from which the request came. Next, the SipProvider attempts to match the request to a server transaction. If there are any server transactions in existence, the server transport uses the matching procedures of Chapter 17 of RFC3261 to attempt to match the response to an existing transaction. If a matching server transaction is found, the request is passed to that transaction, encapsulated into a RequestEvent and fired to the application for processing. If no match is found, the request is passed to the application, which may decide to construct a new server transaction for that request.

Receiving Responses
Responses are first processed by the transport layer and then passed up to the transaction layer. The transaction layer performs its processing and then passes the response up to the application. When a response is received, the SipProvider examines the top Via header. If the value of the "sent-by" parameter in that header field value does not correspond to a value that the client transport is configured to insert into requests, the response MUST be silently discarded. If there are any client transactions in existence, the client transport uses the matching procedures of Chapter 17 of RFC3261 to attempt to match the response to an existing transaction. If there is a match, the response must be passed to that transaction, encapsulated into a ResponseEvent and fired to the application. Otherwise, the response is stray and must be passed to the application to determine its outcome i.e. a proxy will forward them, while a User Agent will discard.

Version:
1.1
Author:
Sun Microsystems
See Also:
SipListener, SipStack

Method Summary
 void addSipListener(SipListener sipListener)
          This method registers the SipListener object to this SipProvider, once registered the SIP Listener recieve events emitted from the SipProvider.
 ListeningPoint getListeningPoint()
          Returns the ListeningPoint of this SipProvider.
 CallIdHeader getNewCallId()
          Returns a unique CallIdHeader for identifying dialogues between two SIP applications.
 ClientTransaction getNewClientTransaction(Request request)
          Before an application can send a new request it must first request a new client transaction to handle that Request.
 ServerTransaction getNewServerTransaction(Request request)
          An application has the responsibility of deciding to respond to a Request that does not match an existing server transaction.
 SipStack getSipStack()
          Returns the SipStack that created this SipProvider.
 void removeSipListener(SipListener sipListener)
          Removes the specified SipListener from this SipProvider.
 void sendRequest(ClientTransaction clientTransaction, Request request)
          Sends the Request which is identified by the ClientTransaction.
 void sendResponse(ServerTransaction serverTransaction, Response response)
          Sends the Response to a Request which is identified by the ServerTransaction.
 void sendStatelessRequest(Request request)
          Sends the Request statelessly, that is no transaction record is associated with this action.
 void sendStatelessResponse(Response response)
          Sends the Response statelessly, that is no transaction record is associated with this action.
 void setListeningPoint(ListeningPoint listeningPoint)
          This method sets the ListeningPoint of the SipProvider.
 

Method Detail

addSipListener

public void addSipListener(SipListener sipListener)
                    throws TooManyListenersException
This method registers the SipListener object to this SipProvider, once registered the SIP Listener recieve events emitted from the SipProvider. This specification restricts a unicast Listener model, that is only one Listener may be registered on the SipProvider concurrently. If an attempt is made to re-register the existing registered SipListener this method returns silently, however a SipListener must be removed from the SipProvider before a different SipListener can be registered to the SipProvider.

Parameters:
sipListener - the SipListener to be registered with the SipProvider.
Throws:
TooManyListenersException - when a new SipListener attempts to register with the SipProvider when another SipListener is already registered with this SipProvider.

removeSipListener

public void removeSipListener(SipListener sipListener)
Removes the specified SipListener from this SipProvider. This method returns silently if the SipListener is not registered with the SipProvider.


getSipStack

public SipStack getSipStack()
Returns the SipStack that created this SipProvider. A SipProvider can only be attached to a single SipStack object that belongs to the same implementation as this SipProvider.

Returns:
the SipStack that created this SipProvider.
See Also:
SipStack

getListeningPoint

public ListeningPoint getListeningPoint()
Returns the ListeningPoint of this SipProvider. A SipProvider has a single Listening Point at any specific point in time.

Returns:
the ListeningPoint of this SipProvider.
See Also:
ListeningPoint

setListeningPoint

public void setListeningPoint(ListeningPoint listeningPoint)
                       throws ObjectInUseException
This method sets the ListeningPoint of the SipProvider. A SipProvider can only have a single ListeningPoint at any specific time, i.e. multiple SipProviders are prohibited to listen on the same ListeningPoint. This method returns silently if the same ListeningPoint argument is re-set on the SipProvider.

Parameters:
listeningPoint - the ListeningPoint of this SipProvider.
Throws:
ObjectInUseException - when an application invokes this method with a ListeningPoint that is being used by another SipProvider in the system.
Since:
v1.1
See Also:
ListeningPoint

getNewCallId

public CallIdHeader getNewCallId()
Returns a unique CallIdHeader for identifying dialogues between two SIP applications.

Returns:
the new CallIdHeader unique within the SipProvider.

getNewClientTransaction

public ClientTransaction getNewClientTransaction(Request request)
                                          throws TransactionUnavailableException
Before an application can send a new request it must first request a new client transaction to handle that Request. This method is called by the application to create the new client transaction befores it sends the Request via the SipProvider on that transaction. This methods returns a new unique client transaction that can be passed to the stateful sendRequest method on the SipProvider and the sendBye method on the Dialog.

Parameters:
request - the new Request message that is to handled statefully by the SipProvider.
Returns:
a new unique client transaction.
Throws:
TransactionUnavailableException - if a new transaction can not be created, for example the next hop of the request can not be determined.
Since:
v1.1
See Also:
ClientTransaction

getNewServerTransaction

public ServerTransaction getNewServerTransaction(Request request)
                                          throws TransactionAlreadyExistsException,
                                                 TransactionUnavailableException
An application has the responsibility of deciding to respond to a Request that does not match an existing server transaction. This method is called by an application that decides to respond to an unmatched Request statefully. This methods return a new unique server transaction that can be passed to the stateful sendResponse methods in order to respond to the request.

Parameters:
request - the Request message that the doesn't match an existing transaction that the application decides to handle statefully.
Returns:
a new unique server transaction.
Throws:
TransactionAlreadyExistsException - if a transaction already exists that is already handling this Request. This may happen if the application gets retransmits of the same request before the initial transaction is allocated.
TransactionUnavailableException - if a new transaction can not be created, for example the next hop of the request can not be determined.
Since:
v1.1
See Also:
ServerTransaction

sendRequest

public void sendRequest(ClientTransaction clientTransaction,
                        Request request)
                 throws TransactionDoesNotExistException,
                        SipException
Sends the Request which is identified by the ClientTransaction. When an application wishes to send a Request message, it creates a Request from the MessageFactory and then passes that Request to this method along with the new ClientTransaction requested from this SipProvider. The Request message gets sent out on the network via the ListeningPoint information that is associated to this SipProvider.

This method implies that the application is functioning as either a UAC or a stateful proxy, hence the underlying SipProvider acts statefully.

Parameters:
clientTransaction - the new ClientTransaction object identifying this transaction.
request - the new Request message to send.
Throws:
TransactionDoesNotExistException - if the clientTransaction does not correspond to any existing client transaction.
SipException - if the SipProvider cannot send the Request for any reason.
See Also:
Request, ClientTransaction

sendResponse

public void sendResponse(ServerTransaction serverTransaction,
                         Response response)
                  throws TransactionDoesNotExistException,
                         SipException
Sends the Response to a Request which is identified by the ServerTransaction. When an application wishes to send a Response, it creates a Response from the MessageFactory and then passes that Response to this method along with the ServerTransaction supplied in the RequestEvent or if a new Request requested from this SipProvider. The Response message gets sent out on the network via the ListeningPoint information that is associated to this SipProvider.

This method implies that the application is functioning as either a UAS or a stateful proxy, hence the underlying SipProvider acts statefully. When a UAS sends a 2xx response to an INVITE, the server transaction is destroyed, by the underlying SipProvider implementation. This means that when the ACK sent by the corresponding UAC arrives at the UAS, there will be no matching server transaction for the ACK, and based on this rule, the ACK is passed to the UAS application, where it is processed. This ensures that the three way handsake of an INVITE is managed by the UAS application and not SipProvider. However when the SipStack.getRetransmissionFilter() is turned ON for User Agent's the SipProvider will take care of this behaviour for the application and notify the application of an error with a Timeout.TRANSACTION Event.

Parameters:
serverTransaction - the ServerTransaction of the Request upon which this Response is sent.
response - the Response to send to the Request.
Throws:
TransactionDoesNotExistException - if the serverTransaction does not correspond to any existing server transaction.
SipException - if the SipProvider cannot send the Response for any other reason.
See Also:
Response, ServerTransaction

sendStatelessRequest

public void sendStatelessRequest(Request request)
                          throws SipException
Sends the Request statelessly, that is no transaction record is associated with this action. This method implies that the application is functioning as a stateless proxy, hence the underlying SipProvider acts statelessly. A stateless proxy simply forwards every request it receives downstream and discards information about the Request message once the message has been forwarded. A stateless proxy does not have any notion of a transaction.

Once the Request message has been passed to this method, the SipProvider will forget about this Request. No transaction semantics will be associated with the Request and the SipProvider will not handle retranmissions for the Request. If these semantics are required it is the responsibility of the application not the SipProvider.

Parameters:
request - the Request message to send statelessly
Throws:
SipException - if the SipProvider cannot send the Request for any reason.
Since:
v1.1
See Also:
Request

sendStatelessResponse

public void sendStatelessResponse(Response response)
                           throws SipException
Sends the Response statelessly, that is no transaction record is associated with this action. This method implies that the application is functioning as either a stateless proxy or a stateless UAS.

Parameters:
response - the Response to send statelessly.
Throws:
SipException - if the SipProvider cannot send the Response for any reason.
Since:
v1.1
See Also:
Response, Response

NIST SIP Parser and Stack (v1.2) API

A product of the NIST/ITL Advanced Networking Technologies Division.
See conditions of use.
Get the latest distribution.
Submit a bug report or feature request.