Portugal Telecom Inovao

IMS-Communicator
Documentation last update: 2007-04-18

IMS-Communicator berlios project page http://imscommunicator.berlios.de Main Developer: Miguel Freitas <jmfreitas@users.berlios.de>

Introduction....................................................................................................................................................... 1 Requirements..................................................................................................................................................... 2 IMS-Communicator Features............................................................................................................................. 2 Standards support list..................................................................................................................................... 2 Supported features list ................................................................................................................................... 2 IMS-Communicator Roadmap ....................................................................................................................... 2 Repository ......................................................................................................................................................... 3 JMF binaries .................................................................................................................................................. 3 Binary releases ............................................................................................................................................... 3 Configuration..................................................................................................................................................... 4 How to .............................................................................................................................................................. 6 How to compile ............................................................................................................................................. 6 How to run .................................................................................................................................................... 6 How to configure the SIP profile.................................................................................................................... 6 How to configure a webcam........................................................................................................................... 6 How to place a call ........................................................................................................................................ 7 How to make a SIP call transfer ..................................................................................................................... 8 How to enable the contact-list ........................................................................................................................ 8 How to enable the Peer-to-Peer mode ............................................................................................................ 9 FAQ ................................................................................................................................................................ 10 Software Licence ............................................................................................................................................. 10

Introduction
IMS-Communicator is a SIP softphone based on the old version of the sip-communicator java project (http://sipcommunicator.org/), implemented on top of the JAIN-SIP stack (https://jain-sip.dev.java.net/) and the Java Media Framework API (http://java.sun.com/products/java-media/jmf/). Some changes have been made to the JAIN-SIP stack to support IMS, such as new SIP headers and SDP functionalities, contribution that have been submitted to the community and is already shipped within the latest JAIN-SIP stack. Originally, the SIP-Communicator client supported normal SIP registration of one public user identity, voice and video session initiation, and some IM functionality, on Windows and Linux. The main IMS User Equipment (UE) procedures were then implemented, as described in the 3GPP specifications TS 24.229, TS 23.228 and others (check http://www.tech-invite.com/ for IMS call flows examples). Some of the IMS functionalities implemented include IMS Registration (Authorization, Security Agreement and Subscription to the reg event package), IMS session initiation (PRACK, UPDATE and Precondition Mechanism) and Call IMS-Communicator User Manual 1

Transfer. At this point, the IMS-Communicator has several limitations, including the following: provided support for only one public user identity user not able to access the IMS network anonymously When placing a call, resources for the media session are considered as available

Requirements
JRE 1.5 (or J2DK 1.5 to compile the project) Java Media Framework (JMF) API (only required when compiling the project) http://java.sun.com/products/java-media/jmf/2.1.1/download.html

Apache Ant (to compile the project)

IMS-Communicator Features
Standards support list
SIP and SDP support (modified JAIN-SIP stack to support IMS) Procedures at the UE (SIP and SDP) 3GPP TS 24.229 SIP PRACK method (RFC 3262) SIP UPDATE method (RFC 3311) SIP Precondition Mechanism (RFC 3312 + RFC 4032) A SIP Event Package for Registrations (RFC 3680) SIP Security Agreement (RFC 3329 + 3GPP TS 33.203 Annex H) SIP REFER method (RFC 3515) and Session Transfer Procedures (3GPP TS 23.228) SIP Referred-By Mechanism (RFC 3892) 3GPP TS 24.229 IP multimedia call control protocol based on SIP and SDP HTTP AKA (RFC 3310) HTTP Digest Authentication (RFC 2617) MILENAGE 3GPP Authentication Algorithm (TS 35.205, TS 35.206, TS 35.207, TS 35.208)

Supported features list

Setup wizard IMS user Registration and Authentication (AKAv1-MD5) IMS Call Initiation Voice and video calls JMF 2.1.1 - Supported Formats http://java.sun.com/products/java-media/jmf/2.1.1/formats.html SIP Call Transfer (Blind and Consultative Transfer) Dial history Contact list, IM and Presence support

IMS-Communicator Roadmap
Full HTTP AKA support (SQN synchronization) Early Media (RFC 3959, RFC 3960)

IMS-Communicator User Manual

 IPSec

Repository
The IMS-Communicator sources, binary releases and documentation can be obtained from http://imscommunicator.berlios.de. The project can be checked out through anonymous (svnserve) SVN with the following instruction set. svn checkout svn://svn.berlios.de/imscommunicator/trunk/ims-communicator

The project can also be checked out through anonymous HTTP with the following instruction set. svn checkout http://svn.berlios.de/svnroot/repos/imscommunicator/trunk/ims-communicator

The folder svn.berlios.de/imscommunicator/trunk/ims-communicator contains the Java sources which are bundled within an Eclipse project. It also contains the required libraries (including the modified JAIN-SIP stack), exception made for the JMF binaries which are system dependent and increase heavily the project weight.

JMF binaries
For that reason the JMF binaries are distributed as a separated package, available at the folder <lib> in the repository svn.berlios.de/imscommunicator/trunk/. They are also available as compressed *.rar files. Theres support for Linux, Windows and Solaris (Solaris JMF package not included contact us if you are interested). So, download the one you aim and place it in the lib folder inside the IMS-Communicator project.

Binary releases
For your convenience, there are binary releases of the IMS-Communicator available at the folder <releases> in the repository svn.berlios.de/imscommunicator/trunk/. Extract the package, edit the configuration file and execute the shell script (ims-communicator.bat or ims-communicator.sh).

IMS-Communicator User Manual

Configuration
The configuration of the IMS-Communicator is done manually in the ims-communicator.xml file or by the menu Settings > Configure at the UA GUI. Featured next, some explanation of the configuration properties: <net.java.sip.communicator> - general sip-communicator properties FIRST_LAUNCH true for the execution of the configuration wizard in the first launch of the UA ENABLE_SIMPLE true to enable presence with peer contacts <net.java.sip.communicator.media> - media and SDP options PREFERRED_AUDIO_ENCODING number of the preferred audio codec, from the audio codecs supported by JMF PREFERRED_VIDEO_ENCODING number of the preferred video codec, from the video codecs supported by JMF NO_AUDIO_DESCRIPTION_IN_SDP if audio description should or not be included in the SDP NO_VIDEO_DESCRIPTION_IN_SDP if video description should or not be included in the SDP MEDIA_SOURCE path to the media source to be sent AUDIO_PORT port where to receive incoming audio data VIDEO_PORT port where to receive incoming video data <net.java.sip.communicator.sip> - SIP profile configuration PUBLIC_ADDRESS SIP public user identity TRANSPORT transport protocol used by the client. UDP by default if none configured REGISTRAR_ADDRESS domain name of the SIP Registrar USER_NAME user name, used to save the user credentials STACK_PATH SIP stack, NIST-SIP by default (gov.nist) PREFERRED_LOCAL_PORT if none configured or port already in use, other will be generated DISPLAY_NAME SIP display-name, to be included in the headers From, To and Contact REGISTRAR_TRANSPORT transport protocol used by the SIP Registrar REGISTRATIONS_EXPIRATION timeout for the user registration REGISTRAR_PORT SIP Registrars port value DEFAULT_DOMAIN_NAME IMS home network domain name DEFAULT_AUTHENTICATION_REALM realm parameter used in the Authentication header

<net.java.sip.communicator.sip.ims> - IMS configuration IMS_CLIENT true if IMS procedures to be used at registration and session initiation PRIVATE_ADDRESS User private address for authentication PREFERRED_ADDRESS SIP address to be include in the P-Preferred-Identity header PREFERRED_DISPLAY_NAME optional display name to be include in the P-Preferred-Identity header PRIVACY value to be included in the Privacy header OPERATOR_ID operator ID (32 HEX char). Default is all zeros

IMS-Communicator User Manual

 SECURITY_AGREEMENT value of the security mechanism parameter. If empty, Security-Client header is not sent SECURITY_ALGORITHM Algorithm parameter in the Security-Client header if security mechanism equals ipsec-3gpp, the following properties are relevant: SECURITY_ENCRYPT_ALG Encryption Algorithm parameter in the Security-Client header SECURITY_SPI_C SPI-Client parameter in the Security-Client header SECURITY_SPI_S SPI-Server parameter in the Security-Client header SECURITY_PORT_C Client Port parameter in the Security-Client header SECURITY_PORT_S Server Port parameter in the Security-Client header ACCEPT_REFER_WITHOUT_SESSION_ON accept REFER request from a peer even if a session is not established with that peer PCSCF_DYNAMIC_DISCOVERY SIP server address and SIP domain discover by stateless DHCPv6 (still work in progress) REG_EVENT_SUBSCRIPTION_TIMEOUT value to be included in the reg even package SUBSCRIBE Expires header ACCESS_TYPE user access network type, to be included in the P-Access-Network header DEFAULT_LOCAL_PRECONDITION precondition mechanism, e2e or sendrecv VIDEO_BANDWIDTH bandwidth value to be include in the video media description offer/answer (resource reservation) AUDIO_BANDWIDTH bandwidth value to be include in the audio media description offer/answer (resource reservation)

<net.java.sip.communicator.sip.simple> - SIMPLE configuration CONTACT_LIST_FILE name of the file with contact entries LAST_SELECTED_OPEN_STATUS user presence status at next start-up <net.java.sip.communicator.gui> - softphone GUI config PHONE_GUI_MODE true/false flag to show or not the Phone GUI IM_GUI_MODE true/false flag to show or not the IM and Contact-List GUI <net.java.sip.communicator.gui.logo> - Logo and Icon (from directory resource/) MAIN_LOGO File name of the image to be set as the phone GUI main logo PHONE_GUI_ICON true File name of the image to be set as the phone GUI application icon IM_GUI_ICON File name of the image to be set as the IM/Contact-list GUI application icon <net.java.sip.communicator.common> - network interface configuration PREFERRED_NETWORK_INTERFACE name of the network interface. OBS: better run the configuration wizard PREFERRED_NETWORK_ADDRESS network interface address <javax.sip> - JAIN-SIP API configuration IP_ADDRESS network interface address used for route SIP messages. Make it equal to the value configured in <net.java.sip.communicator.common.PREFERRED_NETWORK_ADDRESS>. OBS: better run the configuration wizard OUTBOUND_PROXY SIP outbound proxy address, in the format IPaddress:port/transport

IMS-Communicator User Manual

How to
How to compile
The supplied source code includes an Eclipse project data, so it can be easily imported to the Eclipse workspace. Both the J2DK1.5 and the JMF API must be installed in the system. The Apache Ant is used to build the project. Please make the necessary modifications in the build.xml according to your system configuration. The required libraries for Windows and Linux are also included in the libs/ directory, exception made for the JMF libraries. They are available for each platform at imscommunicator/trunk/lib. Download them to the proper folder in the ims-communicator project (ims-communicator/lib/jmf-win or ims-communicator/lib/jmf-lin).

How to run
Binary releases are available for Windows and Linux. Just configure the ims-communicator.xml file manually (or schedule the execution of the Setup Wizard setting the property in ims-communicator.xml <net.java.sip.communicator.FIRST_LANCH with the value true) and run the shell script.

How to configure the SIP profile

The SIP profile can be configured by manually editing the ims-communicator.xml file, or by running the Setup Wizard. Please check the Configuration properties overview and restart the IMS-Communicator client after making changes in the configuration file. Don't forget to configure the Outbound Proxy javax.sip.OUTBOUND_PROXY property or by the menu Settings > Configure > stack properties > jain > SIP Outbound proxy. The format is <address>:<port>/<transport>.

How to configure a webcam

The support of video capture in IMS-Communicator is achieved by the JMF API. To enable it, Settings > Media Preferences (JMF Registry) which executes the JMF Registry Editor. On the tab Capture Devices click on the button Detect Capture Devices. This will detect the video source and enable it.

IMS-Communicator User Manual

Image 1 JMF Registry Editor

How to place a call

When successful registration, there should be visible a green coloured phrase saying something like Registered as bob <sip:bob@open-ims.test>. From that moment, a UA can place a call with a peer UA. Write the SIP address of the peer UA on the combobox just above the menu and click on the Dial button. Previous called peers are saved in the dialhistory.txt file, and are loaded into the SIP address combo-box, so that you don't have to always write the same SIP address when placing a new call. The UA will then send an INVITE to the peer UA. Both UA will negotiate media requirements and, if the resources are available for the session and media negotiation is successful, the peer UA will start to ring. At this moment, the peer UA can refuse the call by pressing the Hangup button. Before the peer UA accepts the call, the caller can cancel the invitation by pressing the Hangup button. If the peer UA desires to answer the call, it can do so by pressing the Answer button.

Image 2 IMS-Communicator Phone GUI

IMS-Communicator User Manual

How to make a SIP call transfer

< documentation not yet available >

How to enable the contact-list

The IMS-Communicator supports Contact-list, which enables IM and Presence. To show or hide the Contact-list GUI, theres an option available at Settings > Show/Hide Contact-list. There is also the property <net.java.sip.communicator.gui.IM_GUI_MODE> which with the true value enables the Contact-list GUI by default on the IMS-Communicator start-up.

Image 3 Enable Contact-list Contacts and Groups can be added. Those actions are accessible thru the mouses right button over the entries on the Contact-list GUI.

Image 4 IMS-Communicator Contact-list GUI

<?xml version="1.0" encoding="UTF-8"?> <contact-list> <group name="buddies"> <contact alias="nuno silva" presentity="sip:nunosilva@ptinovacao.pt"/> </group> </contact-list>

Example of contact-list.xml file

IMS-Communicator User Manual

How to enable the Peer-to-Peer mode

In order to talk directly to another end-point using its IP address, without registering into a SIP server, you would need to make sure that the following properties are empty: * REGISTRAR_ADDRESS * DEFAULT_DOMAIN_NAME * DEFAULT_AUTHENTICATION_REALM * OUTBOUND_PROXY * STUN_SERVER_ADDRESS * STUN_SERVER_PORT * DEMAND_PASSWORD_PRIOR_TO_FIRST_REGISTER false

How to register with the Open IMS Core

< documentation not yet available >

IMS-Communicator User Manual

FAQ
Q Is there something that I have to do before executing the IMS-Communicator? A Please run the Setup Wizard (Settings > Run Setup Wizard) and restart your IMS-Communicator client. You can also configure manually by setting the property <net.java.sip.communicator.FIRST_LAUNCH> with the value true in the ims-communicator.xml configuration file Q When the client registration fails, how can I try to register again? A Please check your SIP profile and restart your IMS-Communicator client. Q Why don't some modifications seam to make effect when I configure the IMS-Communicator while it is still running. A Some SIP headers are pre-built and changes to the configuration may not be immediate. Please restart your IMS-Communicator client. Q I have configured the SIP profile correctly, according to the profile retrieved to me by the IMS network administrator. Why do I always get 403 Forbidden when I try to register my UA? A If you are getting 403 Forbidden HSS Identities don't match, the problem could be that you haven't configured the correct private user identity in the UA. Please check the ims-communicator.xml property <net.java.sip.communicator.sip.ims.PRIVATE_USER_IDENTITY> manually or modify it by the menu Settings > Configure > custom properties > sip-ims > Private User Identity. After altering the configurations file, please restart the IMS-Communicator client. Q Why do I get 403 Forbidden - You must register first with a S-CSCF when sending the initial SUBSCRIBE to the reg event package after a successful register? A This may be an issue due to incomplete network interface configuration. Please run the Setup Wizard (Settings > Run Setup Wizard) and restart your IMS-Communicator client. It as been detected an issue on OpenIMSCore.org concerning the parsing of the P-Preferred-Identity header when it includes the optional display name parameter, which could be causing this 403 Forbidden message. Consider configuring the <net.java.sip.communicator.sip.ims.PREFERRED_DISPLAY_NAME> property with an empty value until this problem isn't fix.

Software Licence
This product includes software developed by the Apache Software Foundation (http://www.apache.org/), inherited from the original SIP-Communicator. New libraries and APIs added by PT Inovao are licensed according to the GNU Lesser General Public License.

IMS-Communicator User Manual

10