|
NIST SIP Parser and Stack (v1.2) API | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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:
Request
's either statefully via
client transactions or statelessly.
Response
's to a recently received
Requests either statefully via server transactions or statelessly.
SipListener
to the SipProvider. Once
the SipListener is registered with the SipProvider it will get notified
of Events representing either Request, Responce or Timeout messages.
SipListener
from the SipProvider.
Once a SipListener is de-registered, it will no longer receive any Events
from that SipProvider.
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:
null
in the RequestEvent and
the RequestEvent also containing the Request is passed to the application.
It is then responsibility of the application to decide to handle the INVITE
Request statefully or statelessly, using the appropriate send methods on the
SipProvider. If a retransmission of the initial INVITE request is recieved
by the SipProvider the following procedures should be adhered to:
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.
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 |
public void addSipListener(SipListener sipListener) throws TooManyListenersException
sipListener
- the SipListener to be registered with the SipProvider.
TooManyListenersException
- when a new SipListener attempts to
register with the SipProvider when another SipListener is already
registered with this SipProvider.public void removeSipListener(SipListener sipListener)
public SipStack getSipStack()
SipStack
public ListeningPoint getListeningPoint()
ListeningPoint
public void setListeningPoint(ListeningPoint listeningPoint) throws ObjectInUseException
listeningPoint
- the ListeningPoint of this SipProvider.
ObjectInUseException
- when an application invokes this method
with a ListeningPoint that is being used by another SipProvider in the
system.ListeningPoint
public CallIdHeader getNewCallId()
public ClientTransaction getNewClientTransaction(Request request) throws TransactionUnavailableException
request
- the new Request message that is to handled statefully by
the SipProvider.
TransactionUnavailableException
- if a new transaction can not be created, for example
the next hop of the request can not be determined.ClientTransaction
public ServerTransaction getNewServerTransaction(Request request) throws TransactionAlreadyExistsException, TransactionUnavailableException
request
- the Request message that the doesn't match an existing
transaction that the application decides to handle statefully.
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.ServerTransaction
public void sendRequest(ClientTransaction clientTransaction, Request request) throws TransactionDoesNotExistException, SipException
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.
clientTransaction
- the new ClientTransaction object identifying
this transaction.request
- the new Request message to send.
TransactionDoesNotExistException
- if the clientTransaction does
not correspond to any existing client transaction.
SipException
- if the SipProvider cannot send the Request for any
reason.Request
,
ClientTransaction
public void sendResponse(ServerTransaction serverTransaction, Response response) throws TransactionDoesNotExistException, SipException
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.
serverTransaction
- the ServerTransaction of the Request upon which
this Response is sent.response
- the Response to send to the Request.
TransactionDoesNotExistException
- if the serverTransaction does
not correspond to any existing server transaction.
SipException
- if the SipProvider cannot send the Response for any
other reason.Response
,
ServerTransaction
public void sendStatelessRequest(Request request) throws SipException
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.
request
- the Request message to send statelessly
SipException
- if the SipProvider cannot send the Request for any
reason.Request
public void sendStatelessResponse(Response response) throws SipException
response
- the Response to send statelessly.
SipException
- if the SipProvider cannot send the Response for any
reason.Response
,
Response
|
NIST SIP Parser and Stack (v1.2) API | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |