Rhino Sample SIP Applications

Other documentation for the Rhino TAS can be found on the Rhino TAS product page.

The example SIP components included with the Rhino SLEE are:

The base directory for the SIP examples is $RHINO_HOME/rhino-connectivity/sip-2.3.0.0. It contains:

Before deploying the examples, you must first change the default configuration of the Proxy service to suit your environment. It is configured in the sip.properties file. Edit this file, changing the PROXY_DOMAINS property as follows:

The default domains opencloud.com and opencloud.co.nz are just examples — change this property to use the correct domains for your environment.

The PROXY_DOMAINS property contains the domains that the proxy SBB considers to be local. This means that if the proxy SBB receives a request addressed to a user in one of these domains (such as sip:bob@opencloud.com), it will use the location service to find the registered contact address of that user. If the user cannot be found, the Proxy service will return an error response.

If the Proxy service receives a request addressed to a user in an unknown domain, it will forward the request according to normal SIP routing rules.

By default, the Ant build script build.xml builds and deploys the Registrar, Proxy and Presence sample services with the components they need (including the SIP resource adaptor and location service), into Rhino.

To deploy the examples, run Ant with the deployexamples target:

If you don’t have Ant installed, you can use a copy that is bundled with Rhino: run the deployexamples.sh script (or deployexamples.bat on Windows).

Once you have deployed the sample Registrar, Proxy and Presence services, see Using the Services for instructions on how to test them with your SIP user agents.

The Ant build script build.xml creates the SIP resource adaptor entity with the following properties (defined in the build.properties file):

To change these properties and specify others, edit the sip.ra.properties property. For example, to enable the SIP RA’s replicated-dialog support, you would add that property as follows (and then deploy the SIP RA):

The Ant build.xml script will pass these properties to the createRAEntity management command.

The complete set of configuration properties supported by the SIP RA are as follows.

To deploy the SIP RA, first ensure the SLEE is running, and then run build.xml with the target deploysipra. For example:

This script installs the SIP RA deployable unit and required libraries in the SLEE, and creates and activates the resource adaptor entity.

To undeploy the SIP RA, run build.xml with the target undeploysipra. For example:

This script deactivates and removes the resource adaptor entity and uninstalls the SIP RA deployable unit.

Rhino’s SIP examples include three implementations of the location-service interface, which demonstrate different SLEE features:

Many other implementations are possible, such as LDAP.

The build.properties file specifies the type of location service that build.xml deploys. To select one of the three available implementations, edit build.properties, changing the locationservice property:

If you select the JDBC location service, you’ll need to select a database other than the default, which uses Rhino’s embedded database (Apache Derby in the SDK and PostgreSQLin the production versions of Rhino).

To select an external database, you need to:

If necessary you can deploy a location service separately using the Ant target deploylocationservice. For example:

This will automatically deploy the location service that you specified in build.properties.

Before you install the Proxy service, you must change one configuration item to suit your environment. Edit the sip.properties file, to change the PROXY_DOMAINS property as follows:

The PROXY_DOMAINS property contains the domains that the proxy SBB considers to be local. Depending on what domain the user to whom a request is addressed is in, the proxy SBB will do the following:

To install the SIP Registrar, Proxy or Presence service, first ensure the SLEE is running. Then go to the SIP examples directory and execute the Ant targets deployregistrar, deployproxy, or deploypresence. For example:

These scripts:

To deactivate and remove the services, use the Ant target undeployregistrar, undeployproxy, or undeploypresence. For example:

A SIP user agent must listen on a network port, so that it can receive incoming calls or messages. The default port for SIP is 5060. Most user agents will attempt to use this port, and this is almost always the correct configuration.

However, if Rhino and a user agent are running on the same host, then there may be a conflict (because Rhino’s SIP resource adaptor defaults to port 5060 as well). If this is the case, you must change the port that either the SIP RA or the user agent uses. See Manual Installation for instructions on changing the port that the SIP RA uses.

If your user agent is running on a different host to Rhino, then no additional network configuration should be necessary.

Your SIP identity (sometimes called "address of record") is the public SIP address that you share with others so they can contact you. It is like your phone number or email address, and usually looks like sip:username@domain (for example, sip:bob@company.com).

When your user agent starts, it will register your SIP identity with the SIP server. The SIP server binds your SIP identity to the network address of your user agent (its contact address). This lets other users call you without knowing your user agent’s network address.

Unless you are integrating with an existing SIP network, the SIP identity you choose can be anything. However, the domain part of your identity (sip:bob@company.com) should be one of the domains known by the sample Proxy service (see the PROXY_DOMAINS property described in Quickstart). This is so the proxy service forwards requests to your user agent’s contact address.

You need to tell your user agent which SIP servers it will use. Depending on the particular user agent, you may have to configure several SIP server addresses, for different SIP services. (Often a user agent will just require a single server address that it uses for everything.)

The typical types of server that you may need to configure are:

To configure your SIP servers, enter the address of your Rhino server in the appropriate fields. Often this will need to be in the form of a SIP URI. For example if Rhino is running on the machine rhino.company.com and using port 5060, then the SIP address of the server would be sip:rhino.company.com:5060.

The following procedure places a call between two user agents, routed through the Proxy service. We will assume the Rhino server is at the address sip:rhino.company.com:5060 and configured to use company.com as its domain. We will refer to the two user agents as A and B, with the SIP identities sip:alice@company.com and sip:bob@company.com respectively.

Setting up the SIP clients to demonstrate the Presence service is similar to setting up to demonstrate the Registrar service:

The Presence service accepts SIP SUBSCRIBE and PUBLISH requests, and sends NOTIFY requests when appropriate.

The client sending SIP SUBSCRIBE requests lets user agents subscribe to the Presence information of other users (adding them as contacts in the "buddy list"). The client sending PUBLISH requests lets user agents publish changes to their own Presence state.

The Presence service responds by providing Presence information through NOTIFY requests. The Presence service amalgamates the Presence information available to it for any given user, and composes the information into a single Presence state for that user. When this composed Presence state changes (either by the user publishing a change to their status, or by registering or de-registering with the Registrar), the Presence service notifies any users who have subscribed to that information. Thus, if user A registers user B as a contact, an example SIP message flow could resemble the one below:

The Presence service responds to the user A’s initial SUBSCRIBE request with a NOTIFY containing the current Presence information of user B, and informs user A with a further NOTIFY request when user B’s Presence state changes.

At the most basic level, Presence describes whether or not a client is online or offline. The Presence service determines the basic Presence state of users from any PUBLISH requests it has received from the user’s client, and through determining whether the user is registered as online with the Registrar.

Many SIP clients implement basic Presence. You can demonstrate this using two clients on a single host.

To demonstrate the use of basic Presence:

Once the buddy list feature of the clients is working, most clients will also allow instant messages. Note that there are exceptions (for example, Microsoft Messenger uses proprietary extensions to the messaging part of the protocol, and will not exchange instant messages).

The SIP/SIMPLE protocol also lets clients share more detailed Presence information. The Presence service implements the Presence information data format set out in RFC3863, "application/pidf+xml", which lets them communicate an extra layer of information (above the basic states of online and offline — for example publishing states such as "On the phone").

To demonstrate the use of extended Presence information with the Presence service, you can set up two instances of WengoPhone on separate hosts:

Once the client’s buddy lists work, they should be able to exchange instant messages.

To enable tracing output for a particular SBB, use the setTraceLevel command in rhino-console, as follows:

You can also enable tracing for all SBBs, and also the SIP RA, by modifying these settings in build.properties: