Introduction to SIP

This document describes the Session Initiation Protocol (SIP), "an application-layer control (signaling) protocol for creating, modifying, and terminating sessions with one or more participants. These sessions include Internet telephone calls, multimedia
distribution, and multimedia conferences." [RFC3261]

Mule and SIP

The SIP connector for Mule uses the JAIN SIP specification and the NIST implementation of the same specification.

Details of the JAIN specification can be found at https://jain-sip.dev.java.net/

The SIP Connector

SIP Connector Properties

The table below lists all the properties which can be set on a SIP Connector.

Property	Description	Default Value	Required
transport	The transport (tcp/udp) to use when sending and receiving SIP messages.	udp	No
proxyPort	The listening port number of the proxy server.		Only if a message is to be sent through a proxy.
proxyHost	The proxy hostname or IP address.		Yes, if a message is to be sent through a proxy.
fromName	The 'From' SIP user name to use when dispatching.		Only if it is not set on the endpoint.
fromSipAddress	The 'From' SIP address to use when dispatching (if not set on the endpoint).		Only if it is not set on the endpoint.
clientPort	The SIP client port to use when dispatching.	5060	Only if it is not set on the endpoint.
clientHost	The SIP client hostname to use when dispatching.	127.0.0.1	Only if it is not set on the endpoint.
serverPort	The port to use when receiving.	5060	No
serverHost	The hostname to use when receiving.	127.0.0.1	No

Using the SIP Connector

To use the SIP connector, it must first be configured in the Mule XML configuration file. The following example contains a SIP Mule connector configuration.

<connector name="SipConnector" className="org.mule.providers.sip.SipConnector">
    <properties>
        <property name="proxyHost" value="127.0.0.1"/>
        <property name="proxyPort" value="4000"/>
    </properties>
</connector>

The SIP Endpoint

Anatomy

sip://<username>#40<address>@[<serverHost:serverPort>][?from=<username>#40<address>@[<clientHost:clientPort>]]

Example

sip://owl%40forest.com@192.168.0.1:5060?from=sip://pengiun%40alaska.com@192.168.0.19:5060

The Destination Host & Port

The destination host and port, specifying the actual location of to User Agent Server (UAS), may be omitted. If these are omitted, SIP messages are dispatched to a proxy server, whose location is specified on the connector. If the proxy location is not specified on the connector, SIP messages are dispatched to the default UAS host specified on the connector (default values are used if not specified otherwise).

The From Property

The 'from' property specifies the username, address and current location of the message sender. If this property is omitted, the default sender credentials are obtained from the connector's properties.

Dispatching SIP messages

The JAIN SIP specification offers a SipListener interface which must be implemented by all objects wanting to receive messages from the SIP Stack.

The SipProvider interface enables SipListeners to:

Register for incoming SIP events
Deregister as listeners for SIP events
Send SIP requests statelessly
Send SIP responses statelessly.

The JAIN specification defines:

A many-to-one relationship between a SipProvider and a SipStack
A many-to-one relationship between a SipProvider and a SipListener.
A one-to-many relationship between a SipProvider and a ListeningPoint (Each SipProvider can manage only one TCP and one UDP listening points simultaneously.)

The following diagram illustrates the hierarchy of JAIN SIP interfaces.

The SipMessageDispatcher implements the SipListener interface so as to be able to send SIP requests and listen for responses. It is then registered with a SipProvider to receive SIP responses on an endpoint. Since a SipProvider can only have one associated SipListener, a separate listening point must be set up for each SipMessageDispatcher.

This is achieved by specifying a different 'from' property for each SIP endpoint.
The following diagram illustrates two separate SIP endpoints using different listening endpoints as defined in their 'from' property. This allows each dispatcher to listen for responses from the destination SIP peer without interfering with other SIP dispatchers (and receivers). Such a solution is illustrated in the diagram below.