jain.protocol.ip.sip
Interface JainSipProvider

public interface JainSipProvider

This interface must be implemented by any Object representing a JAIN SIP Provider that interacts directly with a proprietary (stack vendor specific) implementation of a SIP stack. This interface defines the methods that will be used by any registered SIP User application implementing the JainSipListener interface to send SIP messages. It must be noted that any object that implements the:

• JainSipListener Interface is referred to as JainSipListenerImpl.
• JainSipProvider Interface is referred to as JainSipProviderImpl.
• JainSipStack Interface is referred to as JainSipStackImpl.

Version:

0.6

See Also:

JainSipListener

Method Summary

void	addJainSipListener(JainSipListener listener) Adds a JainSipListener to the list of registered Event Listeners of this JainSipProvider.
Message	decryptMessage(Message encryptedMessage, java.lang.String key) Returns decrypted version of encrypted message using specified key with scheme specified in EncryptionHeader
Message	encryptMessage(Message unencryptedMessage, java.lang.String key) Returns encrypted version of unencrypted message using specified key with scheme specified in EncryptionHeader
RequestMessage	getClientTransactionRequest(int clientTransactionId) Returns the RequestMessage associated with client transaction specified by the transaction id
ResponseMessage	getClientTransactionResponse(int clientTransactionId) Returns the last ResponseMessage associated with client transaction specified by the transaction id
ListeningPoint	getListeningPoint() Returns the ListeningPoint of this JainSipProvider
CallIdHeader	getNewCallIdHeader() Returns a new CallIdHeader for the Provider's ListeningPoint
int	getNewCSeqNumber(CallIdHeader callIdHeader) Returns a new CSeq for the call represented by the specified CallIdHeader
RequestMessage	getServerTransactionRequest(int serverTransactionId) Returns the RequestMessage associated with server transaction specified by the transaction id
ResponseMessage	getServerTransactionResponse(int serverTransactionId) Returns the last ResponseMessage associated with server transaction specified by the transaction id
JainSipStack	getStack() Returns the JainSipStack that this JainSipProvider is attached to.
void	removeJainSipListener(JainSipListener listener) Removes JainSipListener from the list of registered JainSipListeners for all ListeningPoints of this JainSipProvider.
int	sendAck(int clientTransactionId, AckMessage ack) Sends an AckMessage to the recepient of the invite associated with transaction specified by client transaction id (using specified ack message)
int	sendAck(JainSipListener source, int clientTransactionId) Sends an AckMessage to the recepient of the invite associated with transaction specified by client transaction id (ack message with empty body is automatically generated by provider)
int	sendAck(JainSipListener source, int clientTransactionId, java.lang.Object body, java.lang.String bodyType, java.lang.String bodySubType) Sends an AckMessage to the recepient of the invite associated with transaction specified by client transaction id (ack message with specified body is automatically generated by provider)
int	sendBye(ByeMessage bye) Terminate call leg (using specified bye message)
int	sendBye(JainSipListener source, InviteMessage invite) Terminate call leg associated with specified InviteMessage (bye message is automatically generated by provider) Note - the ByeMessage will have a CSeq number equal to the CSeq number of the InviteMessage plus one i.e.
int	sendBye(JainSipListener source, ResponseMessage response) Terminate call leg associated with specified ResponseMessage (bye message is automatically generated by provider) Note - the ByeMessage will have a CSeq number equal to the CSeq number of the ResponseMessage plus one i.e.
int	sendCancel(int clientTansactionId, CancelMessage cancel) Cancel the pending request associated with transaction specified by proprietary transaction id (using specified cancel message)
int	sendCancel(JainSipListener source, int clientTransactionId) Cancel the pending request associated with transaction specified by client transaction id (cancel message is automatically generated by provider)
int	sendInvite(InviteMessage invite) Sends a specified InviteMessage and returns the ID of the implicitly created transaction.
int	sendInvite(JainSipListener source, URI requestURI, NameAddress from, NameAddress to, java.lang.Object body, java.lang.String bodyType, java.lang.String bodySubType) Sends an automatically generated InviteMessage and returns the ID of the implicitly created transaction.
int	sendOptions(JainSipListener source, URI requestURI, NameAddress from, NameAddress to) Sends an automatically generated OptionsMessage and returns the ID of the implicitly created transaction.
int	sendOptions(JainSipListener source, URI requestURI, NameAddress from, NameAddress to, java.lang.Object body, java.lang.String bodyType, java.lang.String bodySubType) Sends an automatically generated OptionsMessage and returns the ID of the implicitly created transaction.
int	sendOptions(OptionsMessage options) Sends a specified OptionsMessage and returns the ID of the implicitly created transaction.
int	sendRegister(JainSipListener source, URI requestURI, NameAddress from, NameAddress to, NameAddress[] contacts) Sends an automatically generated RegisterMessage and returns the ID of the implicitly created transaction.
int	sendRegister(JainSipListener source, URI requestURI, NameAddress from, NameAddress to, NameAddress[] contacts, java.lang.Object body, java.lang.String bodyType, java.lang.String bodySubType) Sends an automatically generated RegisterMessage and returns the ID of the implicitly created transaction.
int	sendRegister(RegisterMessage register) Sends a specified RegisterMessage and returns the ID of the implicitly created transaction.
int	sendRequest(RequestMessage request) Sends a specified RequestMessage and returns the ID of the implicitly created transaction.
void	sendResponse(int serverTransactionId, ResponseMessage response) Sends a response to the request associated with server transaction specified by server transaction id (using specified response message)
void	sendResponse(JainSipListener source, int serverTransactionId, int statusCode) Sends a response to the request associated with server transaction specified by server transaction id (response message is automatically generated by provider)
void	sendResponse(JainSipListener source, int serverTransactionId, int statusCode, java.lang.Object body, java.lang.String bodyType, java.lang.String bodySubType) Sends a response to the request associated with server transaction specified by server transaction id (response message is automatically generated by provider)

Method Detail

addJainSipListener

public void addJainSipListener(JainSipListener listener)
                        throws java.util.TooManyListenersException,
                               IPListenerAlreadyRegisteredException,
                               java.lang.IllegalArgumentException

Adds a JainSipListener to the list of registered Event Listeners of this JainSipProvider.

Parameters:

jainSipListener - the JainSipListener to be added.

Throws:

java.util.TooManyListenersException - if a limit is placed on the allowable number of registered JainSipListeners for this ListeningPoint, and this limit is exceeded

java.lang.IllegalArgumentException - if listener is null

removeJainSipListener

public void removeJainSipListener(JainSipListener listener)
                           throws IPListenerNotRegisteredException,
                                  java.lang.IllegalArgumentException

Removes JainSipListener from the list of registered JainSipListeners for all ListeningPoints of this JainSipProvider.

Parameters:

jainSipListener - the JainSipListener to be removed from this JainSipProvider.

Throws:

IPListenerNotRegisteredException - if the JainSipListener to be removed is not registered as an Event Listener of this JainSipProvider for any ListeningPoints.

java.lang.IllegalArgumentException - if listener is null

getStack

public JainSipStack getStack()

Returns the JainSipStack that this JainSipProvider is attached to.

Returns:

the attached JainSipStack.

getListeningPoint

public ListeningPoint getListeningPoint()

Returns the ListeningPoint of this JainSipProvider

Returns:

the ListeningPoint of this JainSipProvider

sendRequest

public int sendRequest(RequestMessage request)
                throws SipException,
                       java.lang.IllegalArgumentException

Sends a specified RequestMessage and returns the ID of the implicitly created transaction.

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if provider does not allow listener to create client transaction

java.lang.IllegalArgumentException - if request is null

sendInvite

public int sendInvite(InviteMessage invite)
               throws SipException,
                      java.lang.IllegalArgumentException

Sends a specified InviteMessage and returns the ID of the implicitly created transaction.

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if provider does not allow listener to create client transaction

java.lang.IllegalArgumentException - if invite is null

sendInvite

public int sendInvite(JainSipListener source,
                      URI requestURI,
                      NameAddress from,
                      NameAddress to,
                      java.lang.Object body,
                      java.lang.String bodyType,
                      java.lang.String bodySubType)
               throws SipException,
                      java.lang.IllegalArgumentException

Sends an automatically generated InviteMessage and returns the ID of the implicitly created transaction.

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

java.lang.IllegalArgumentException - if any parameter is null or if bodyType is zero-length

sendRegister

public int sendRegister(RegisterMessage register)
                 throws SipException,
                        java.lang.IllegalArgumentException

Sends a specified RegisterMessage and returns the ID of the implicitly created transaction.

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if provider does not allow listener to create client transaction

java.lang.IllegalArgumentException - if register is null

sendRegister

public int sendRegister(JainSipListener source,
                        URI requestURI,
                        NameAddress from,
                        NameAddress to,
                        NameAddress[] contacts)
                 throws SipException,
                        java.lang.IllegalArgumentException

Sends an automatically generated RegisterMessage and returns the ID of the implicitly created transaction.

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if provider does not allow listener to create client transaction

java.lang.IllegalArgumentException - if any parameter is null, or if contacts is empty or contains any null entries

sendRegister

public int sendRegister(JainSipListener source,
                        URI requestURI,
                        NameAddress from,
                        NameAddress to,
                        NameAddress[] contacts,
                        java.lang.Object body,
                        java.lang.String bodyType,
                        java.lang.String bodySubType)
                 throws SipException,
                        java.lang.IllegalArgumentException

Sends an automatically generated RegisterMessage and returns the ID of the implicitly created transaction.

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if provider does not allow listener to create client transaction

java.lang.IllegalArgumentException - if any parameter is null, or if bodyType is zero-length, or if contacts is empty or contains any null entries

sendOptions

public int sendOptions(OptionsMessage options)
                throws SipException,
                       java.lang.IllegalArgumentException

Sends a specified OptionsMessage and returns the ID of the implicitly created transaction.

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if provider does not allow listener to create client transaction

java.lang.IllegalArgumentException - if options is null

sendOptions

public int sendOptions(JainSipListener source,
                       URI requestURI,
                       NameAddress from,
                       NameAddress to)
                throws SipException,
                       java.lang.IllegalArgumentException

Sends an automatically generated OptionsMessage and returns the ID of the implicitly created transaction.

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

java.lang.IllegalArgumentException - if any parameter is null

sendOptions

public int sendOptions(JainSipListener source,
                       URI requestURI,
                       NameAddress from,
                       NameAddress to,
                       java.lang.Object body,
                       java.lang.String bodyType,
                       java.lang.String bodySubType)
                throws SipException,
                       java.lang.IllegalArgumentException

Sends an automatically generated OptionsMessage and returns the ID of the implicitly created transaction.

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

java.lang.IllegalArgumentException - if any parameter is null or if bodyType is zero-length

getServerTransactionRequest

public RequestMessage getServerTransactionRequest(int serverTransactionId)
                                           throws TransactionDoesNotExistException

Returns the RequestMessage associated with server transaction specified by the transaction id

Parameters:

serverTransactionId - the server transaction id

Returns:

the RequestMessage associated with server transaction

Throws:

TransactionDoesNotExistException - if transactionId does not correspond to an existing server transaction

getClientTransactionRequest

public RequestMessage getClientTransactionRequest(int clientTransactionId)
                                           throws TransactionDoesNotExistException

Returns the RequestMessage associated with client transaction specified by the transaction id

Parameters:

clientTransactionId - the client transaction id

Returns:

the RequestMessage associated with client transaction

Throws:

TransactionDoesNotExistException - if transactionId does not correspond to an existing client transaction

getServerTransactionResponse

public ResponseMessage getServerTransactionResponse(int serverTransactionId)
                                             throws TransactionDoesNotExistException,
                                                    ResponseDoesNotExistException

Returns the last ResponseMessage associated with server transaction specified by the transaction id

Parameters:

serverTransactionId - the server transaction id

Returns:

the RequestMessage associated with server transaction

Throws:

TransactionDoesNotExistException - if transactionId does not correspond to an existing server transaction

ResponseDoesNotExistException - if no ResponseMessage exists for server transaction

getClientTransactionResponse

public ResponseMessage getClientTransactionResponse(int clientTransactionId)
                                             throws TransactionDoesNotExistException,
                                                    ResponseDoesNotExistException

Returns the last ResponseMessage associated with client transaction specified by the transaction id

Parameters:

clientTransactionId - the client transaction id

Returns:

the RequestMessage associated with client transaction

Throws:

TransactionDoesNotExistException - if transactionId does not correspond to an existing client transaction

ResponseDoesNotExistException - if no ResponseMessage exists for client transaction

sendAck

public int sendAck(int clientTransactionId,
                   AckMessage ack)
            throws SipException,
                   java.lang.IllegalArgumentException,
                   TransactionDoesNotExistException

Sends an AckMessage to the recepient of the invite associated with transaction specified by client transaction id (using specified ack message)

Parameters:

clientTransactionId - the client transaction id

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if an invite request is not associated with client transaction, or if invite response has not been received yet, or if ack is not a valid ack message for client transaction

java.lang.IllegalArgumentException - if ack is null

TransactionDoesNotExistException - if clientTransactionId does not correspond to an existing client transaction

sendAck

public int sendAck(JainSipListener source,
                   int clientTransactionId)
            throws SipException,
                   TransactionDoesNotExistException

Sends an AckMessage to the recepient of the invite associated with transaction specified by client transaction id (ack message with empty body is automatically generated by provider)

Parameters:

source - the JainSipListener invoking this method

clientTransactionId - the client transaction id

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if an invite request is not associated with client transaction, or if invite response has not been received yet

TransactionDoesNotExistException - if clientTransactionId does not correspond to an existing client transaction

sendAck

public int sendAck(JainSipListener source,
                   int clientTransactionId,
                   java.lang.Object body,
                   java.lang.String bodyType,
                   java.lang.String bodySubType)
            throws SipException,
                   TransactionDoesNotExistException

Sends an AckMessage to the recepient of the invite associated with transaction specified by client transaction id (ack message with specified body is automatically generated by provider)

Parameters:

source - the JainSipListener invoking this method

clientTransactionId - the client transaction id

body - body

bodyType - type of body

bodySubType - sub-type of body

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if an invite request is not associated with client transaction, or if invite response has not been received yet

TransactionDoesNotExistException - if clientTransactionId does not correspond to an existing client transaction

sendCancel

public int sendCancel(int clientTansactionId,
                      CancelMessage cancel)
               throws SipException,
                      java.lang.IllegalArgumentException,
                      TransactionDoesNotExistException

Cancel the pending request associated with transaction specified by proprietary transaction id (using specified cancel message)

Parameters:

clientTransactionId - the transaction id

cancel - the CancelMessage to be sent

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if cancel is not a valid cancel message for the transaction or if a final response has already been received for the client transaction

java.lang.IllegalArgumentException - if cancel is null

TransactionDoesNotExistException - if clientTransactionId does not correspond to an existing client transaction

sendCancel

public int sendCancel(JainSipListener source,
                      int clientTransactionId)
               throws TransactionDoesNotExistException,
                      SipException

Cancel the pending request associated with transaction specified by client transaction id (cancel message is automatically generated by provider)

Parameters:

source - the JainSipListener invoking this method

clientTransactionId - the client transaction id

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

TransactionDoesNotExistException - if clientTransactionId does not correspond to an existing client transaction

SipException - if a final response has already been received for the client transaction

sendBye

public int sendBye(ByeMessage bye)
            throws SipException,
                   java.lang.IllegalArgumentException

Terminate call leg (using specified bye message)

Parameters:

bye - the ByeMessage to be sent

Returns:

the transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if bye does not correspond to an existing call leg

java.lang.IllegalArgumentException - if bye is null

sendBye

public int sendBye(JainSipListener source,
                   InviteMessage invite)
            throws SipException

Terminate call leg associated with specified InviteMessage (bye message is automatically generated by provider) Note - the ByeMessage will have a CSeq number equal to the CSeq number of the InviteMessage plus one i.e. it is assumed that there have been no requests sent after the intial InviteMessage and AckMessage

Parameters:

source - the JainSipListener invoking this method

invite - the InviteMessage used to establish call leg

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if no call leg corresponding to invite exists

sendBye

public int sendBye(JainSipListener source,
                   ResponseMessage response)
            throws SipException

Terminate call leg associated with specified ResponseMessage (bye message is automatically generated by provider) Note - the ByeMessage will have a CSeq number equal to the CSeq number of the ResponseMessage plus one i.e. it is assumed that there has been no requests sent after the RequestMessage associated with the ResponseMessage

Parameters:

source - the JainSipListener invoking this method

response - a ResponseMessage associated with call leg

Returns:

the client transaction id (unique to the underlying JainSipStack)

Throws:

SipException - if no call leg corresponding to response exists

sendResponse

public void sendResponse(int serverTransactionId,
                         ResponseMessage response)
                  throws java.lang.IllegalArgumentException,
                         SipException,
                         TransactionDoesNotExistException

Sends a response to the request associated with server transaction specified by server transaction id (using specified response message)

Parameters:

serverTransactionId - the server transaction id

response - the ResponseMessage to be sent

Throws:

SipException - if response is not a valid response to the request received

java.lang.IllegalArgumentException - if response is null

TransactionDoesNotExistException - if clientTransactionId does not correspond to an existing server transaction

sendResponse

public void sendResponse(JainSipListener source,
                         int serverTransactionId,
                         int statusCode)
                  throws java.lang.IllegalArgumentException,
                         TransactionDoesNotExistException

Sends a response to the request associated with server transaction specified by server transaction id (response message is automatically generated by provider)

Parameters:

source - the JainSipListener invoking this method

serverTransactionId - the server transaction id

statusCode - the response code of the response to be sent

Throws:

java.lang.IllegalArgumentException - if statusCode is not a 3-digit number

TransactionDoesNotExistException - if serverTransactionId does not correspond to an existing server transaction

sendResponse

public void sendResponse(JainSipListener source,
                         int serverTransactionId,
                         int statusCode,
                         java.lang.Object body,
                         java.lang.String bodyType,
                         java.lang.String bodySubType)
                  throws java.lang.IllegalArgumentException,
                         TransactionDoesNotExistException

Sends a response to the request associated with server transaction specified by server transaction id (response message is automatically generated by provider)

Parameters:

source - the JainSipListener invoking this method

serverTransactionId - the server transaction id

statusCode - the response code of the response to be sent

body - body

bodyType - type of body

bodySubType - sub-type of body

Throws:

java.lang.IllegalArgumentException - if statusCode is not a 3-digit number

TransactionDoesNotExistException - if serverTransactionId does not correspond to an existing server transaction

getNewCallIdHeader

public CallIdHeader getNewCallIdHeader()
                                throws SipException

Returns a new CallIdHeader for the Provider's ListeningPoint

Returns:

a new CallIdHeader for the Provider's ListeningPoint

Throws:

SipException - if Provider cannot generate a new CallIdHeader

getNewCSeqNumber

public int getNewCSeqNumber(CallIdHeader callIdHeader)
                     throws SipException,
                            java.lang.IllegalArgumentException

Returns a new CSeq for the call represented by the specified CallIdHeader

Parameters:

callIdHeader - the CallIdHeader

Returns:

a new int Seq for the call represented by the specified CallIdHeader

Throws:

SipException - if callIdHeader has not been created by Provider

java.lang.IllegalArgumentException - if callIdHeader is null

decryptMessage

public Message decryptMessage(Message encryptedMessage,
                              java.lang.String key)
                       throws SipException,
                              java.lang.IllegalArgumentException

Returns decrypted version of encrypted message using specified key with scheme specified in EncryptionHeader

Parameters:

encryptedMessage - message to be decrypted

key - key to use for decryption

Returns:

decrypted version of encrypted message

Throws:

SipException - if decryption could not be performed successfully

java.lang.IllegalArgumentException - if encryptedMessage is null, or if key is null or zero-length

encryptMessage

public Message encryptMessage(Message unencryptedMessage,
                              java.lang.String key)
                       throws SipException,
                              java.lang.IllegalArgumentException

Returns encrypted version of unencrypted message using specified key with scheme specified in EncryptionHeader

Parameters:

unencryptedMessage - message to be encrypted

key - key to use for encryption

Returns:

encrypted version of unencrypted message

Throws:

SipException - if encryption could not be performed successfully

java.lang.IllegalArgumentException - if unencryptedMessage is null, or if key is null or zero-length