org.mjsip.sip.provider

Class SipProvider

java.lang.Object

org.mjsip.sip.provider.SipProvider

All Implemented Interfaces:

SipTransportListener, Configurable

Direct Known Subclasses:

ConnectedSipProvider, ExtendedSipProvider

public class SipProvider
extends java.lang.Object
implements Configurable, SipTransportListener

SipProvider implements the SIP transport layer, that is the layer responsable for sending and receiving SIP messages.

Any SipProvider user can send SIP messages through method sendMessage() and receive incoming SIP messages by setting itself as message listener through the method addSelectiveListener() (specifing also the type of messages it wants to listen to) and by implementing the callback method onReceivedMessage() defined by the interface SipProviderListener.

If a SipProvider user wants to capture ALL incoming messages regardless of any other concurrent listening users, it may use the addPromiscuousListener() method.

SipProvider implements also multiplexing/demultiplexing service allowing a listener to be bound to a specific type of SIP messages through the addSelectiveListener(identifier,listener) method, where:
- identifier is a message identifier specifying the kind of messages the listener has to be associated to,
- listener is the listener that received messages will be passed to.

The identifier, together with the SIP provider transport protocols, port numbers and IP addresses, may be viewed as SIP Service Access Point (SAP) identifier at receiving side.

The message identifier can be of one of the three following types: transaction_id, dialog_id, or method_id. These types of identifiers characterize respectively:
- messages within a specific transaction,
- messages within a specific dialog,
- messages related to a specific SIP method. It is also possible to use the message identifier MethodId.ANY to select
- all messages that are out of any transactions, dialogs, or method types already specified.

When receiving a message, the SipProvider passes the message to any active listeners added in promiscuous mode thorugh method addPromiscuousListener(). Then the message is passed to the eventual selective listeners added thorugh method addSelectiveListener() and matching the given message. For this purpose the SipProvider first tries to look for a matching transaction-id, then looks for a matching dialog-id, then for a matching method-id, and finally for a default listener (i.e. that with id "ANY"). For the matched SipProviderListener, the method onReceivedMessage() is fired.

Note: no 482 (Loop Detected) nor 501 (Not Implemented) responses are generated for requests that does not properly match any active transactions, dialogs, nor method types.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ALL_INTERFACES String value "auto-configuration" used for auto configuration of the host address
static java.lang.String	AUTO_CONFIGURATION String value "auto-configuration" used for auto configuration of the host address
protected Logger	event_logger Event logger
protected Logger	message_logger Message logger
static java.lang.String	PROTO_DTLS DTLS protocol type
static java.lang.String	PROTO_SCTP SCTP protocol type
static java.lang.String	PROTO_TCP TCP protocol type
static java.lang.String	PROTO_TLS TLS protocol type
static java.lang.String	PROTO_UDP UDP protocol type
protected java.util.Hashtable	sip_transports Table of supported transport layers for SIP (Hashtable of protocol (String), transport (SipTransport))

Constructor Summary

Constructors

Constructor and Description
SipProvider(java.lang.String file) Creates a new SipProvider.
SipProvider(java.lang.String via_addr, int host_port) Creates a new SipProvider.
SipProvider(java.lang.String via_addr, int host_port, SipTransport[] sip_transports) Creates a new SipProvider.
SipProvider(java.lang.String via_addr, int host_port, java.lang.String[] transport_protocols) Creates a new SipProvider.
SipProvider(java.lang.String via_addr, int host_port, java.lang.String[] transport_protocols, int[] transport_ports) Creates a new SipProvider.
SipProvider(java.lang.String via_addr, int host_port, java.lang.String[] transport_protocols, int[] transport_ports, java.lang.String binding_addr) Creates a new SipProvider.
SipProvider(java.lang.String via_addr, int host_port, java.lang.String[] transport_protocols, java.lang.String binding_addr) Creates a new SipProvider.

Method Summary

Modifier and Type	Method and Description
void	addExceptionListener(SipProviderExceptionListener listener) Adds a SipProviderExceptionListener.
void	addPromiscuousListener(SipProviderListener listener) Adds a SipProvider listener for caputering any message in promiscuous mode.
void	addSelectiveListener(SipId id, SipProviderListener listener) Sets a SipProvider listener for a target type of method, transaction, or dialog messages.
IpAddress	getBindingIpAddress() Gets the binding IP address.
NameAddress	getContactAddress() Gets a valid SIP or SIPS contact address.
NameAddress	getContactAddress(boolean secure) Gets a valid SIP or SIPS contact address.
NameAddress	getContactAddress(java.lang.String user) Gets a valid SIP or SIPS contact address.
NameAddress	getContactAddress(java.lang.String user, boolean secure) Gets a valid SIP or SIPS contact address.
java.lang.String	getDefaultTransport() Gets the default transport protocol.
java.util.Hashtable	getListeners() Returns the table of active listeners as Hastable:(SipId)IDs-->(SipListener)listener.
Logger	getLogger() Gets event logger.
int	getNMaxConnections() Gets the max number of (contemporary) open connections.
SipURI	getOutboundProxy() Gets the outbound proxy.
int	getPort() Gets host port.
SipURI	getTelGateway() Gets the tel gateway.
int	getTlsPort() Gets tls port.
java.lang.String[]	getTransportProtocols() Gets array of transport protocols.
java.lang.String	getViaAddress() Gets via address.
void	halt() Stops the SipProviders.
boolean	hasOutboundProxy() Whether has outbound proxy.
boolean	hasSecureTransport() Whether it has TLS or DTLS transport protocol.
boolean	hasTelGateway() Whether has tel gateway.
boolean	hasTransport(java.lang.String proto) Whether it has the given transport protocol.
boolean	isAllInterfaces() Whether binding the sip provider to all interfaces or only on the specified host address.
boolean	isForceRportSet() Whether using 'force-rport' mode.
boolean	isForceSentBySet() Whether "force-sent-by" mode is set.
boolean	isReliableTransport(java.lang.String proto) Whether the given transport protocol is supported and reliable.
boolean	isRportSet() Whether using rport.
static boolean	isSecureTransport(java.lang.String proto) Whether the given transport protocol is secure (TLS or DTLS) or not (UDP, TCP, SCTP, etc.).
boolean	isSupportedTransport(java.lang.String proto) Whether the given transport protocol is supported.
void	onIncomingTransportConnection(SipTransport transport, SocketAddress remote_soaddr) When a new incoming transport connection is established.
void	onReceivedMessage(SipTransport transport, SipMessage msg) From SipTransportListener.
void	onTransportConnectionTerminated(SipTransport transport, SocketAddress remote_soaddr, java.lang.Exception error) When a transport connection terminates.
void	onTransportTerminated(SipTransport transport, java.lang.Exception error) From SipTransportListener.
void	parseLine(java.lang.String line) From Configurable.
static java.lang.String	pickBranch() Picks a fresh branch value.
java.lang.String	pickBranch(SipMessage msg) Picks an unique branch value based on a SIP message.
java.lang.String	pickCallId() Picks a new call-id.
static java.lang.String	pickCallId(java.lang.String hostaddr) Picks a new call-id.
static int	pickInitialCSeq() picks an initial CSeq
static java.lang.String	pickTag() Picks a new tag.
static java.lang.String	pickTag(SipMessage req) Picks a new tag.
void	removeExceptionListener(SipProviderExceptionListener listener) Removes a SipProviderExceptionListener.
void	removePromiscuousListener(SipProviderListener listener) Removes a SipProviderListener in promiscuous mode.
void	removeSelectiveListener(SipId id) Removes a SipProviderListener.
void	removeSipTransport(java.lang.String proto) Removes a specific transport protocol.
ConnectionId	sendMessage(SipMessage msg) Sends the msg message.
ConnectionId	sendMessage(SipMessage msg, java.lang.String proto, java.lang.String dest_addr, int dest_port, int ttl) Sends the msg message, specifing the transport portocol, nexthop address and port.
ConnectionId	sendRawMessage(SipMessage msg, java.lang.String proto, java.lang.String dest_addr, int dest_port, int ttl) Sends the msg message, specifing the transport portocol, nexthop address and port.
void	setDefaultTransport(java.lang.String proto) Gets the default transport protocol.
void	setForceRport(boolean flag) Sets 'force-rport' mode.
void	setForceSentBy(boolean force_sent_by) Whether setting the Via protocol, sent-by, and port values according to the transport connection.
void	setNMaxConnections(int n) Sets the max number of (contemporary) open connections.
void	setOutboundProxy(SipURI uri) Sets the outbound proxy.
void	setRport(boolean flag) Sets rport support.
void	setTelGateway(SipURI uri) Sets the tel gateway.
void	setTransport(SipTransport transport) Sets a specific transport protocol.
protected java.lang.String	toLines() Converts the entire object into lines (to be saved into the config file)
java.lang.String	toString() Gets a String value for this object.
static void	updateViaHeader(SipMessage msg, java.lang.String proto, java.lang.String via_addr, int host_port) Updates the top Via header field of a SIP message, according to the given transport information.
static void	updateViaHeader(SipMessage msg, java.lang.String proto, java.lang.String via_addr, int host_port, java.lang.String maddr, int ttl) Updates the top Via header field of a SIP message, according to the given transport information.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PROTO_UDP

public static final java.lang.String PROTO_UDP

UDP protocol type

See Also:

Constant Field Values

PROTO_TCP

public static final java.lang.String PROTO_TCP

TCP protocol type

See Also:

Constant Field Values

PROTO_TLS

public static final java.lang.String PROTO_TLS

TLS protocol type

See Also:

Constant Field Values

PROTO_DTLS

public static final java.lang.String PROTO_DTLS

DTLS protocol type

See Also:

Constant Field Values

PROTO_SCTP

public static final java.lang.String PROTO_SCTP

SCTP protocol type

See Also:

Constant Field Values

AUTO_CONFIGURATION

public static final java.lang.String AUTO_CONFIGURATION

String value "auto-configuration" used for auto configuration of the host address

See Also:

Constant Field Values

ALL_INTERFACES

public static final java.lang.String ALL_INTERFACES

String value "auto-configuration" used for auto configuration of the host address

See Also:

Constant Field Values

event_logger

protected Logger event_logger

Event logger

message_logger

protected Logger message_logger

Message logger

sip_transports

protected java.util.Hashtable sip_transports

Table of supported transport layers for SIP (Hashtable of protocol (String), transport (SipTransport))

Constructor Detail

SipProvider

public SipProvider(java.lang.String via_addr,
                   int host_port)

Creates a new SipProvider.

Parameters:

via_addr - SIP local via address

host_port - SIP local port

SipProvider

public SipProvider(java.lang.String via_addr,
                   int host_port,
                   java.lang.String[] transport_protocols)

Creates a new SipProvider.

Parameters:

via_addr - SIP local via address

host_port - SIP local port

transport_protocols - array of active transport protocols

SipProvider

public SipProvider(java.lang.String via_addr,
                   int host_port,
                   java.lang.String[] transport_protocols,
                   java.lang.String binding_addr)

Creates a new SipProvider.

Parameters:

via_addr - SIP local via address

host_port - SIP local port

transport_protocols - array of active transport protocols

binding_addr - local IP address to which the SIP provider has to be bound to

SipProvider

public SipProvider(java.lang.String via_addr,
                   int host_port,
                   java.lang.String[] transport_protocols,
                   int[] transport_ports)

Creates a new SipProvider.

Parameters:

via_addr - SIP local via address

transport_protocols - array of active transport protocols

transport_ports - array of transport port used for the corresponding transport protocols

SipProvider

public SipProvider(java.lang.String via_addr,
                   int host_port,
                   java.lang.String[] transport_protocols,
                   int[] transport_ports,
                   java.lang.String binding_addr)

Creates a new SipProvider.

Parameters:

via_addr - SIP local via address

transport_protocols - array of active transport protocols

transport_ports - array of transport port used for the corresponding transport protocols

binding_addr - local IP address to which the SIP provider has to be bound to

SipProvider

public SipProvider(java.lang.String via_addr,
                   int host_port,
                   SipTransport[] sip_transports)

Creates a new SipProvider.

Parameters:

via_addr - SIP local via address

host_port - SIP local port

sip_transports - array of active transport services (SipTransport)

SipProvider

public SipProvider(java.lang.String file)

Creates a new SipProvider.

Parameters:

file - file where all configuration parameters are read from.

Method Detail

isSecureTransport

public static boolean isSecureTransport(java.lang.String proto)

Whether the given transport protocol is secure (TLS or DTLS) or not (UDP, TCP, SCTP, etc.).

Returns:

true for TLS or DTLS, false otherwise

setTransport

public void setTransport(SipTransport transport)

Sets a specific transport protocol.

removeSipTransport

public void removeSipTransport(java.lang.String proto)

Removes a specific transport protocol.

halt

public void halt()

Stops the SipProviders.

parseLine

public void parseLine(java.lang.String line)

From Configurable. Parses a single line (loaded from the config file).

Specified by:

parseLine in interface Configurable

toLines

protected java.lang.String toLines()

Converts the entire object into lines (to be saved into the config file)

hasTransport

public boolean hasTransport(java.lang.String proto)

Whether it has the given transport protocol.

hasSecureTransport

public boolean hasSecureTransport()

Whether it has TLS or DTLS transport protocol.

getViaAddress

public java.lang.String getViaAddress()

Gets via address.

getPort

public int getPort()

Gets host port.

getTlsPort

public int getTlsPort()

Gets tls port.

getContactAddress

public NameAddress getContactAddress()

Gets a valid SIP or SIPS contact address.

Returns:

a SIP or SIPS contact URI for this SIP provider. A SIPS URI is returned if TLS (or DTLS) transport is supported

getContactAddress

public NameAddress getContactAddress(java.lang.String user)

Gets a valid SIP or SIPS contact address.

Returns:

a SIP or SIPS contact URI for this SIP provider. A SIPS URI is returned if TLS (or DTLS) transport is supported

getContactAddress

public NameAddress getContactAddress(boolean secure)

Gets a valid SIP or SIPS contact address.

Parameters:

secure - whether returning a SIPS or SIP URI (true=SIPS, false=SIP)

Returns:

a SIP or SIPS contact URI for this SIP provider

getContactAddress

public NameAddress getContactAddress(java.lang.String user,
                                     boolean secure)

Gets a valid SIP or SIPS contact address.

Parameters:

user - local user's name

secure - whether returning a SIPS or SIP URI (true=SIPS, false=SIP)

Returns:

a SIP or SIPS contact URI for this SIP provider

isAllInterfaces

public boolean isAllInterfaces()

Whether binding the sip provider to all interfaces or only on the specified host address.

getBindingIpAddress

public IpAddress getBindingIpAddress()

Gets the binding IP address.

getTransportProtocols

public java.lang.String[] getTransportProtocols()

Gets array of transport protocols.

isSupportedTransport

public boolean isSupportedTransport(java.lang.String proto)

Whether the given transport protocol is supported.

isReliableTransport

public boolean isReliableTransport(java.lang.String proto)

Whether the given transport protocol is supported and reliable.

getDefaultTransport

public java.lang.String getDefaultTransport()

Gets the default transport protocol.

setDefaultTransport

public void setDefaultTransport(java.lang.String proto)

Gets the default transport protocol.

setRport

public void setRport(boolean flag)

Sets rport support.

isRportSet

public boolean isRportSet()

Whether using rport.

setForceRport

public void setForceRport(boolean flag)

Sets 'force-rport' mode.

isForceRportSet

public boolean isForceRportSet()

Whether using 'force-rport' mode.

setForceSentBy

public void setForceSentBy(boolean force_sent_by)

Whether setting the Via protocol, sent-by, and port values according to the transport connection.

Parameters:

force_sent_by - whether setting Via protocol, sent-by, and port values according to the transport connection

isForceSentBySet

public boolean isForceSentBySet()

Whether "force-sent-by" mode is set.

hasOutboundProxy

public boolean hasOutboundProxy()

Whether has outbound proxy.

getOutboundProxy

public SipURI getOutboundProxy()

Gets the outbound proxy.

setOutboundProxy

public void setOutboundProxy(SipURI uri)

Sets the outbound proxy. Use 'null' for not using any outbound proxy.

hasTelGateway

public boolean hasTelGateway()

Whether has tel gateway.

getTelGateway

public SipURI getTelGateway()

Gets the tel gateway.

setTelGateway

public void setTelGateway(SipURI uri)

Sets the tel gateway. Use 'null' for not using any tel gateway.

getNMaxConnections

public int getNMaxConnections()

Gets the max number of (contemporary) open connections.

setNMaxConnections

public void setNMaxConnections(int n)

Sets the max number of (contemporary) open connections.

getLogger

public Logger getLogger()

Gets event logger.

getListeners

public java.util.Hashtable getListeners()

Returns the table of active listeners as Hastable:(SipId)IDs-->(SipListener)listener.

addSelectiveListener

public void addSelectiveListener(SipId id,
                                 SipProviderListener listener)

Sets a SipProvider listener for a target type of method, transaction, or dialog messages.

Parameters:

id - specifies the kind of messages that the listener as to be associated to. It may identify a method, a transaction, or a dialog, or all messages. Use MethodId.ANY to capture all messages.

listener - is the SipProviderListener that the specified type of messages has to be passed to.

removeSelectiveListener

public void removeSelectiveListener(SipId id)

Removes a SipProviderListener.

Parameters:

id - specifies the messages that the listener was associated to.

addPromiscuousListener

public void addPromiscuousListener(SipProviderListener listener)

Adds a SipProvider listener for caputering any message in promiscuous mode.

When a SipProviderListener captures messages in promiscuous mode messages are passed to this listener before passing them to other specific listener.
More that one SipProviderListener can be active in promiscuous mode at the same time; in that case the same message is passed to all promiscuous SipProviderListeners.

Parameters:

listener - is the SipProviderListener.

removePromiscuousListener

public void removePromiscuousListener(SipProviderListener listener)

Removes a SipProviderListener in promiscuous mode.

Parameters:

listener - is the SipProviderListener to be removed.

addExceptionListener

public void addExceptionListener(SipProviderExceptionListener listener)

Adds a SipProviderExceptionListener. The SipProviderExceptionListener is a listener for all exceptions thrown by the SipProviders.

Parameters:

listener - is the SipProviderExceptionListener.

removeExceptionListener

public void removeExceptionListener(SipProviderExceptionListener listener)

Removes a SipProviderExceptionListener.

Parameters:

listener - is the SipProviderExceptionListener to be removed.

sendMessage

public ConnectionId sendMessage(SipMessage msg)

Sends the msg message. For request messages, if no Via header field is preset, a new Via is added; if protocol or sent-by fields of the Via header field do not match the current SipProvider configuration (e.g. via address or port) or the request-uri (required transport protocol), they are properly updated.

The destination for the request is computed as follows:
- if outbound_addr is set, outbound_addr and outbound_port are used, otherwise
- if message has Route header with lr option parameter (i.e. RFC3261 compliant), the first Route address is used, otherwise
- the request's Request-URI is considered.

The destination for the response is computed based on the sent-by parameter in the Via header field (RFC3261 compliant).

If a Via header field is already present, the specified transport protocol is used. Otherwise the default transport protocol is used.

In case of connection-oriented transport:
- if an already established connection is found matching the destination end point (socket), such connection is used, otherwise;
- a new connection is established.

Returns:

Returns a ConnectionId in case of connection-oriented delivery (e.g. TCP) or null in case of connection-less delivery (e.g. UDP)

updateViaHeader

public static void updateViaHeader(SipMessage msg,
                                   java.lang.String proto,
                                   java.lang.String via_addr,
                                   int host_port)

Updates the top Via header field of a SIP message, according to the given transport information.

Parameters:

msg - the message to be updated

proto - the transport protocol

via_addr - the sent-by address of the via

host_port - the host port

updateViaHeader

public static void updateViaHeader(SipMessage msg,
                                   java.lang.String proto,
                                   java.lang.String via_addr,
                                   int host_port,
                                   java.lang.String maddr,
                                   int ttl)

Updates the top Via header field of a SIP message, according to the given transport information.

Parameters:

msg - the message to be updated

proto - the transport protocol

via_addr - the sent-by address of the via

host_port - the host port

maddr - the IP multicast address (if applicable) or null

ttl - the TTL for multicast (used only when parameter maddr is set)

sendMessage

public ConnectionId sendMessage(SipMessage msg,
                                java.lang.String proto,
                                java.lang.String dest_addr,
                                int dest_port,
                                int ttl)

Sends the msg message, specifing the transport portocol, nexthop address and port. For request messages, if no Via header field is preset, a new Via is added.

This is a low level method and forces the message to be routed to a specific nexthop address, port and transport, regardless whatever the Via, Route, or request-uri, address to.

In case of connection-oriented transport, the connection is selected as follows:
- if an existing connection is found matching the destination end point (destination socket), such connection is used, otherwise
- a new connection is established.

Returns:

It returns a ConnectionId in case of connection-oriented tranport protocol (e.g. TCP) or null in case of connection-less tranport protocol (e.g. UDP)

sendRawMessage

public ConnectionId sendRawMessage(SipMessage msg,
                                   java.lang.String proto,
                                   java.lang.String dest_addr,
                                   int dest_port,
                                   int ttl)

Sends the msg message, specifing the transport portocol, nexthop address and port. It does the same as method sendMessage(SipMessage,String,String,int,int), but no via address is added (if not already present) in request messages.

onReceivedMessage

public void onReceivedMessage(SipTransport transport,
                              SipMessage msg)

From SipTransportListener. When a new SIP message is received.

Specified by:

onReceivedMessage in interface SipTransportListener

onTransportTerminated

public void onTransportTerminated(SipTransport transport,
                                  java.lang.Exception error)

From SipTransportListener. When SipTransport terminates.

Specified by:

onTransportTerminated in interface SipTransportListener

onIncomingTransportConnection

public void onIncomingTransportConnection(SipTransport transport,
                                          SocketAddress remote_soaddr)

When a new incoming transport connection is established. It is called only for CO transport portocols.

Specified by:

onIncomingTransportConnection in interface SipTransportListener

onTransportConnectionTerminated

public void onTransportConnectionTerminated(SipTransport transport,
                                            SocketAddress remote_soaddr,
                                            java.lang.Exception error)

When a transport connection terminates.

Specified by:

onTransportConnectionTerminated in interface SipTransportListener

pickBranch

public static java.lang.String pickBranch()

Picks a fresh branch value. The branch ID MUST be unique across space and time for all requests sent by the UA. The branch ID always begin with the characters "z9hG4bK". These 7 characters are used by RFC 3261 as a magic cookie.

pickBranch

public java.lang.String pickBranch(SipMessage msg)

Picks an unique branch value based on a SIP message. This value could also be used as transaction ID

pickTag

public static java.lang.String pickTag()

Picks a new tag. A tag MUST be globally unique and cryptographically random with at least 32 bits of randomness. A property of this selection requirement is that a UA will place a different tag into the From header of an INVITE than it would place into the To header of the response to the same INVITE. This is needed in order for a UA to invite itself to a session.

pickTag

public static java.lang.String pickTag(SipMessage req)

Picks a new tag. The tag is generated uniquely based on message req. This tag can be generated for responses in a stateless manner - in a manner that will generate the same tag for the same request consistently.

pickCallId

public java.lang.String pickCallId()

Picks a new call-id. The call-id is a globally unique identifier over space and time. It is implemented in the form "localid@host". Call-id must be considered case-sensitive and is compared byte-by-byte.

pickCallId

public static java.lang.String pickCallId(java.lang.String hostaddr)

Picks a new call-id. The call-id is a globally unique identifier over space and time. It is implemented in the form "localid@host". Call-id must be considered case-sensitive and is compared byte-by-byte.

pickInitialCSeq

public static int pickInitialCSeq()

picks an initial CSeq

toString

public java.lang.String toString()

Gets a String value for this object.

Overrides:

toString in class java.lang.Object