JVoIP –Java SIP Library

June 14, 2022

 

 

 

Contents

About 2

Requirements. 2

Usage. 2

Using from the console/command line. 2

Using as a standalone application. 3

Using as a library. 3

Socket/HTTP API 5

Using on a website. 6

Features. 8

Licensing. 8

API 10

Functions. 10

Notifications. 26

Parameters. 34

Main Parameters. 35

serveraddress. 35

username. 35

password. 35

register 35

Other Parameters. 36

FAQ.. 77

Resources. 104

 

 

 

 

About                                      

The Mizu Java VoIP SDK (JVoIP) is a SIP client implemented as a platform independent java library. Since it is based on the open standard Session Initiation Protocol, it can inter-operate with any other SIP-based device (servers and clients).

 

The VoIP SDK can be used in many ways:

o    as a library added to your project (use the API to create a SIP app or add VoIP capabilities for your app; this is the main use-case)

o    as a command line Java VoIP client (with stdin input / stdout output)

o    as a standalone desktop application (it has a built-in minimalistic GUI to ease such kind of usage)

o    as an applet embedded to a web page (applets are already deprecated in modern browsers but still supported by JVoIP)

 

With the Java VoIP SDK you have an easy to use full featured SIP/media stack in a single jar file, easy to integrate or embedded in your desktop, server or web application. For example it can be integrated with callcenter software or embedded in VoIP devices such as PBX or gateways so users will have a fully functional VoIP softphone without the need to download any other third-party software. You can also use it to add VoIP call capabilities into any software not directly related to VoIP (such as games or CRM’s) or to perform any kind of VoIP automation (auto dialer, auto answer machine, etc).

 

See all related resources here.

Requirements                      

 

JVoIP hardware/software requirements:

·         Any OS with Java SE support (Linux, Windows, MAC, others)

·         JVM: Works with most JVM’s including Oracle, OpenJDK and others. Download.

·         Minimum Java version: J2SE 5.0+ (Java 1.5+ which means support for all java versions since 2004)

·         Maximum Java version: 18+. No limitations, the library doesn’t use special modules or API’s. Supports Java 18 (the current/latest Java when this documentation was last updated) and will remain compatible with all further Java JVM/JRE/JDK releases.

·         Development: any java compiler, any OS and any IDE can be used (the library is a single jar file which can be easily added to your project regardless of your environment)

·         Programming language (when used as a library): any JVM based language such as Java, Clojure, Kotlin, Scala, Groovy, Python, Jython and others

·         IDE (when used as a library): any IDE or command line can be used such as IntelliJ, Eclipse, NetBeans, JBuilder, JDeveloper, JCreator, BlueJ, Kite and others

·         Audio device: headset or microphone/speaker for audio (will work also without audio device with streaming or voice recording)

·         Video device: optional if you wish to use video calls. Any recorded/webcam device which is recognized by your OS

·         CPU: any architecture with Java SE support such as x86, x64, armv7k, arm64, sparc, etc. with a performance of minimum 350 MHz Pentium 3 or higher (runs well also on ancient devices or with embedded devices such as Raspberry Pi)

·         RAM: minimum 10 MB to run JVoIP (above the JVM basic requirements)

·         Disk space: 3 MB (additional data such as call recording or detailed logs might take more space)

·         A SIP account (At any VoIP service provider or your own IP-PBX/Softswitch/SIP sever. Can be also used without registration for peer to peer SIP calls)

 

Note: If you are looking for a SIP stack for your Android project, then you should use the AJVoIP SDK instead of this library (AJVoIP has the same API as this JVoIP SDK, but targets Android instead of Java SE)

Usage                                      

The SDK can be used in many ways: as a standalone application, embedded into your project or integrated with your website.

The settings can be specified from: API, command line, config file, URL or sent via SIP signaling.

It can be used as a standalone app or integrated into other app with or without using the API.

The API can be accessed from: Java and any other JVM language, JavaScript, UDP, TCP or HTTP (clear text, URL, JSON, XML).

The API can be directly used from Java or other JVM based application such as Kotlin, or you can use the API via UDP/TCP or HTTP wrapper from any development environment and programming language such as C, C++, C# or Delphi.

 

Download: Java SIP SDK (this is the demo version)

 

Note: Optionally you might also copy the mediaench files to your app folder (near your java or jar files). This contains some platform dependent native binaries to optimize audio processing and the sip client will select the correct one to be used automatically if found.

 

Using from the console/command line

This is a simplest way to test as a simple SIP client and it is often used for various automation tasks:

Example:

java –jar JVoIP.jar serveraddress=VOIP_SERVER_IP_OR_DOMAIN username=USERNAME password=PASSWORD callto=DESTINATION autocall=false loglevel=1

Here is a working example: JVoIP.jar serveraddress=voip.mizu-voip.com username=jvoiptest password=jvoiptestpwd callto=testivr3 autocall=false loglevel=1

Replace the values in uppercase accordingly and make sure to have Java installed.

 

To disable the GUI (use as a console application) set the iscommandline JVoIP parameter to true. Otherwise you can launch the GUI also from command line with the API_StartGUI function (use API_StartGUI() instead of API_Start() if you need this functionality).

By default all parameters are set to its optimal/most common values, however if you wish to further customize or you need any specific functionality then you might use any other command line options as documented below in the parameters chapter.

 

Note:

o    The demo version doesn’t work in headless mode like Linux with no X-Window installed. Contact us if you need a headless version!

o    Some systems (Windows) might accept the command line also without the java –jar prefix, other systems (Linux) might require the java –jar JVoIP.jar [parameters] format.

 

Using as a standalone application

This means starting the app with its built-in user interface.

 

Create a configuration file near the JVoIP.jar with the file name: wpcfg.ini. The content should be like this:

serveraddress=VOIP_SERVER_IP_OR_DOMAIN

username=USERNAME

password=PASSWORD

callto=DESTINATION

loglevel=1

…other config options if needed

Replace the values in uppercase accordingly and make sure to have Java installed.

Then just double click on JVoIP.jar to start (or launch it from command line as java –jar JVoIP.jar)

 

JVoIP has a minimalistic built-in softphone user interface for your convenience (which can be modified by the appearance parameters), however you can easily create your own user interface and design when used as a library or embedded in a webpage as discussed below.

 

Using as a library

You can use JVoIP as an SDK if you are a Java developer to add VoIP functionality in any JVM (java) application by including this SIP library into your project.

This is the most powerful use-case to fully exploit JVoIP capabilities.

You just need to add JVoIP to your project and call its public API_XXX functions. (See the “API” chapter below for more details”).

 

In short, the interaction with the library is done by calling it’s API functions, handling the function return values (success-true/failed-false/other answers) and handling the notifications received from the library (for example the STATUS messages about the SIP stack state machine).

 

Example use-cases:

·         Implement your custom Java SIP client

·         Implement a full featured Java Softphone

·         Add VoIP capabilities to any Java application (or any JVM based apps such as Clojure, Scala, Kotlin, Groovy, JRuby or Jython)

·         Add SIP call capabilities to any application running over a Java virtual machine

 

Steps:

1.        Add JVoIP.jar lib to your project

2.        Instantiate a webphone object (webphone wobj = new webphone();)

3.        Call the API_SetParameter() to pass any settings (parameters)

4.        Call the API_Start() to start the SIP stack

5.        Call any other functions (such as API_Call, API_SendChat and others as described in the API)

6.        Poll for the notifications with the API_GetNotifications() or API_GetNotificationsSync() function call, preferably from a separate thread. Parse and process the notifications from the sip stack after your needs as described in the "Notifications" section (optional. For simple applications this might not be needed)

 

Note: all API calls are thread safe and will not throw exceptions (on exception they will send an “ERROR” notifications and/or return false/-1/0 depending on the context). To handle errors, check the functions return values, check the notifications, query the SIP stack state with various API calls and inspect the logs.

 

Example code (exception and error handling removed for simplicity):

 

--------------------------------------

File: YourCodeSipCall.java

--------------------------------------

package yourpackagename; 

import webphone.*;  //add JVoIP.jar to your project for this. both the package and the main class are named “webphone”

  

//create webphone class object instance:

webphone wobj = new webphone();

 

//start your message listener:

SIPNotifications sipnotifications = new SIPNotifications(wobj);

sipnotifications.Start();

 

 

//set parameters (replace uppercase words):

wobj.API_SetParameter("serveraddress", “VOIP_SERVER_IP_OR_DOMAIN");

wobj.API_SetParameter("username", "SIP_USERNAME");

wobj.API_SetParameter("password", "SIP_PASSWORD");

wobj.API_SetParameter("loglevel", "5");  //you might set to 1 for production

//you might set other parameters here. most parameters can be also set or changed later at runtime

//start the sipstack:

wobj.API_Start();                                                                                         

//register to your SIP server (optional):

//wobj.API_Register();

 

//make a call to a user/extension/phone number/SIP URI (note: 1-2 seconds might be needed between API_Start/API_Register and API_Call for the sipstack to initialize)

wobj.API_Call(-1, "DESTINATION");

//the following lines should be used from another function

//during the call you might call call divert functions by your app logic or on user interaction, for example API_Hold()

 

//call hangup to end the call (possibly triggered by a “Hangup” button pressed by the user):

wobj.API_Hangup(-1);

//stop JVoIP when you don’t need it anymore

wobj.API_Unregister();

sipnotifications.Stop();

 

--------------------------------------

File: SIPNotifications.java

--------------------------------------

 

package JVoIPTestPackage; //you might change this after your package name

import webphone.webphone;

 

 

public class SIPNotifications extends Thread

{

   boolean terminated = false;

   webphone webphoneobj = null;

  

   //constructor

   public SIPNotifications(webphone webphoneobj_in)

   {

       webphoneobj = webphoneobj_in;

   }

 

   //start the thread

   public boolean Start()

   {

 

       try{

           this.start();

           System.out.println("sip notifications started");

           return true;

       }catch(Exception e) {System.out.println("Exception at SIPNotifications Start: "+e.getMessage()+"\r\n"+e.getStackTrace()); }

       return false;

   }

 

  //stop the thread

   public void Stop()

   {

           terminated = true;

   }

 

   //blocking read in this thread

   public void run()

   {

        try{

           String sipnotifications = "";

           String[] notarray = null;

          

           while (!terminated)

           {

                  //get the notifications from the SIP stack

                  sipnotifications = webphoneobj.API_GetNotificationsSync();

 

                  if (sipnotifications != null && sipnotifications.length() > 0)

                  {

                      //split by line

                      System.out.println("\tREC FROM JVOIP: " + sipnotifications);

                      notarray = sipnotifications.split("\r\n");

 

                      if (notarray == null || notarray.length < 1)

                      {                               

                         if(!terminated) Thread.sleep(1); //some error occured. sleep a bit just to be sure to avoid busy loop

                      }

                      else

                      {

                        for (int i = 0; i < notarray.length; i++)

                        {

                            if (notarray[i] != null && notarray[i].length() > 0)

                            {                                        

                                ProcessNotifications(notarray[i]);

                            }

                        }

                      }

                  }

                  else

                  {

                      if(!terminated) Thread.sleep(1);  //some error occured. sleep a bit just to be sure to avoid busy loop

                  }                                       

           }

 

        }catch(Exception e)

        {

           if(!terminated) System.out.println("Exception at SIPNotifications run: "+e.getMessage()+"\r\n"+e.getStackTrace());

        }

 

    }

 

 

    //all messages from JVoIP will be routed to this function.

    //parse and process them after your needs regarding to your application logic

 

    public void ProcessNotifications(String msg)

    {

        try{           

            //frame.jTextArea1.append(msg);

           

            //TODO: process notifications here (change your user interface or business logic depending on the sip stack state / call state by parsing the strings receiver here).

          //See the Notifications section in the documentation for the details. Example code can be found here.

        }catch(Exception e) { System.out.println("Exception at SIPNotifications ProcessNotifications: "+e.getMessage()+"\r\n"+e.getStackTrace()); }

    }

}

 

 

You can download a working example from here.

 

Contact us for the headless version if you wish to use it from an operating system without GUI system installed (such as Linux without X-Window installed or used with a headless JRE/JDK).

 

Socket/HTTP API

The Socket interface is useful if you wish to use JVoIP as a library from non-JVM environment such as .NET, PHP, C++, Python, Delphi or any others.

 

While from Java (or other JVM based language) you can call the API functions directly, in case if you are using other development environment then you must call the JVoIP API via a socket. In this case you will have to convert your function calls to a simple string and send it over a socket. You will receive the answers for your API requests and notifications over the same socket. The send/receive string formats are discussed below.

 

All the functions and notifications are the exact same like you would use JVoIP as an embedded library, the only difference is that the library will run in a separate process, you connect to it via UDP, TCP or HTTP and you have to convert/parse everything (API requests, API answers and notifications) as strings.

 

Configuration:

First of all, you will have to launch launch JVoIP as a separate process (for example ShellExecute on Windows, but for first you can just launch it manually from command line), then send commands to the JVoIP listening port by:

·         UDP (configurable by the wpapiudplistenport parameter. 19422 by default)

·         TCP (configurable by the wpapilistenport parameter. 0 by default which means disabled)

·         HTTP (configurable by the same wpapilistenport parameter as it will auto detect raw TCP vs HTTP. 0 by default which means disabled)

 

Note:

·         Only UDP is enabled by default. If you need TCP and/or HTTP set the wpapiudplistenport to 0 and the wpapilistenport to any value, for example 19422.

·         Some very restrictive firewalls might block also localhost connections. If you have installed such a firewall on your PC, make sure to allow JVoIP/Java.

·         If you start to use the API_GetNotifications or API_GetNotificationsSync function (using the API directly from Java) the JVoIP will stop sending out notifications via sockets

                                                                                                                    

The following formats are accepted for requests and answers:

·         clear text (so you can easily test it manually with telnet)

·         HTTP (GET/POST/AJAX)

o    URL parameters (if used from a browser as an applet)

o    JSON

o    form post

o    XML

o    SOAP

 

Requests:

Example from browser (HTTP with URL parameters): http://127.0.0.1:19422/?function=API_Call&line=-1&peer=1234

Example from telnet (clear text TCP): 

                telnet 127.0.0.1 19422

?function=API_Call&line=-1&peer=1234

 

For the function parameters you can use the exact same name as in this documentation or you can use param1, param2 … paramN format.

 

From local applications we recommend UDP with clear text. For faster processing you can also split the commands between EOFCOMMAND/BOFCOMMAND and the parameters between EOFLINE/BOFLINE.

For example: BOFCOMMANDBOFLINEfunction=API_CallEOFLINEBOFLINEparam1=-1EOFLINEBOFLINEparam2=1234EOFLINEEOFCOMMAND

 

Answers:

Answers are sent in the following clear text format:

APIREQUEST:API_CallRPARAM1:1RPARAM2:1234APIRESULT:RESULT

The first part (until “APIRESULT:”) might be useful if you are using the API asynchronously, so you will always know for which request did you received the answer. The important part is the RESULT string (after “APIRESULT:”) and usually begins with OK or ERROR. For example: OK: initiated or ERROR: failed

 

Notifications:

If you are using simple UDP or TCP (not HTTP) then the NOTIFICATIONS are also sent automatically on the same socket. Otherwise you can use API_GetNotifications to receive the notifications.

 

From HTTP clients we recommend AJAX HTTP requests with URL parameters. Also you should set the polling parameter to 3 and use API_GetNotifications to receive the notifications (since in case of HTTP there is no any live socket stream where the notification might be sent, it is recommended to constantly poll the JVoIP for these events using the API_GetNotifications function from a timer in around every 200 milliseconds).

 

Summary by protocol:

·         UDP:

o    You might change the wpapiudplistenport parameter if you wish. Default is 19422.

o    It is recommended to bind your UDP socket to 127.0.0.1:19421 (the socket in your own app, not for the JVoIP) and change your target port to the port from where you receive messages on UDP. This helps if the JVoIP was unable to bind to the specified port and is running on a different port as it will send messages to 19421 by default (and changes the target port to the source address once receives any API command).

o    Send commands as clear text in UDP packets to port 19422 (or to the port from where you received the last udp message from JVoIP)

o    You will receive the notifications events from the same port

 

·         TCP:

o    Set the wpapilistenport parameter to 19422

o    Connect to port 19422 and send commands as strings

o    You will receive the notifications events in the same TCP stream

o    You can easily test with a telnet client by connecting to 127.0.0.1 19422 and sending “?function=API_TestEcho&echo=test”

 

·         HTTP:

o    Set the following JVoIP parameters:

§   wpapiudplistenport: 0

§   wpapilistenport: 19422

§   polling: 3

o    Send commands as HTTP GET requests to http://127.0.0.1:19422

o    You can use various formats such as XML or JSON (default is clear text)

o    You need to poll for notification events using API_GetNotifications (from a timer in every 200 msec)

o    You can easily test with a browser: http://127.0.0.1:19422/?function=API_TestEcho&echo=teeeest

 

               

Using on a website

Although Java Applets have been deprecated by modern browsers we still keep Applet compatibility for those who are interested in this use case.

You might use the VoIP SDK as an applet embedded into your webpage and it will run fine on all Java capable browsers.

Copy JVoIP.jar to your webserver near your html’s and refer to it from anywhere from your html with the “applet” tag. Set at least the “serveraddress” parameter to the IP or domain name of your VoIP server (Softswitch/IP-PBX/SIP proxy)

 

<applet

  archive  = "JVoIP.jar"

  codebase = "."

  code     = "webphone.webphone.class"

  name     = "JVoIP"

  width    = "300"

  height   = "330"

  hspace   = "0"

  vspace   = "0"

  align    = "middle" 

  mayscript = "true"

  scriptable = "true"

  alt="Enable or install java: https://www.java.com/en/download/index.jsp"

<param name = "serveraddress" value = "SERVER_ADDRESS">

<param name = "loglevel" value = "1">

<param name = "MAYSCRIPT" value = "true">

<param name = "scriptable" value = "true">

<param name = "pluginspage" value = "https://java.com/download/">

<param name = "permissions" value = "all-permissions">

 

 

<b>You must enable java or install if not already installed from <a href="https://www.java.com/en/download/index.jsp"> here </a>  </b>

 

</applet>

 

 

Embed to your website as an applet and use it with any java enabled browser.

You can also disable the default java user interface (compact=true, width=1, height=1) and create your own using html/css or any other teqniques.

 

The same API is available also from java script which you can use to implement a VoIP application on your website. You might choose to do some actions in the background, present a single “call” or callback button or to display a phone interface.  The important steps are the followings:

1.        write a function named “webphonetojs” to catch all messages from the VoIP SDK. Regarding the incoming messages you can display the status of the phone (registered,ringing,in-call,etc), the most important events and alert the user about incoming calls or chat messages.

2.        load JVoIP as applet with the webpage using applet tags or with the “toolkit” method with the proper parameters (serveraddress, etc)

(the parameters can be preconfigured, but you can also pass them via the API)

3.        get a handle for JVoIP (document. applets[0] or check the skins in the demo package for a more complex example)

4.        optionally call the API_Register automatically or when the user click on the “Connect” button (by default if you provide a username and a password parameter, the java voip client will register automatically on startup)

5.        call the API_Call function when the user clicks on your “Call” or “Dial” button

6.        popup a window (or enable an “accept” button) when you receive notifications about incoming calls to your “webphonetojs” function. Then call API_Accept or API_Reject according the user action

7.        if you will present a dial pad for the users, then you might call the API_Dtmf function whenever the user presses a button

8.        you might put additional buttons or other controls on your interface for the following functions: audio settings, logout, hold, mute, redial, transfer, conference and others

 

Short example:

<SCRIPT LANGUAGE="javascript">

  function webphonetojs(message)

  {

     //this is an optional function if you would like to be notified about JVoIP events

     //this function will be called by JVoIP

     //you will have to parse the message and act accordingly 

     alert(message);       

  }

 

  function do_something()

  {    

     document.applets[0].functionname();    

  }

</SCRIPT>

 

<input type=button value='JVoIP action' onClick='do_something()'>

 

Example call-flow:

var wp = document.applets[0];

 

wp.API_Register(“11.12.13.14”, “sipusername”, “sippassword”);  //connect to the SIP server

wp.API_Call(-1, “+363012345678”); //make a new call

//wait for connect message by checking the message received on webphonetojs function

//notify the user when the call is ringing or connected

wp.API_MuteEx(-2,true,0);  //can be called when the user press a button

wp.API_MuteEx(-2,false,0);  //reenable audio when the user press a button

wp.API_Hangup(-2); //disconnect all calls

 

...also call the wp.API_HTTPKeepAlive in every 5 minute to avoid session timeout (defined by the httpsessiontimeout parameter)

 

 

Note:
Java applets are deprecated in recent Chrome, Firefox versions and in other modern browsers.
If you wish to use the SIP library as a Java Applet then we recommend one of the followings:

·         IE (Internet Explorer for Windows)

·         The Pale Moon browser (Windows & Linux)

·         Old Firefox/Chrome/Safari versions

 

More details about using the webphone on a webpage can be found here and here.

See the API and the parameters sections below for the details about the usage.

Features

·         Standard SIP client for voice calls (in/out), chat, conference and others

·         SIP and RTP stack compatible with any VoIP server or client (Cisco, Asterisk, gateways, ATA, softphones, IP Phones, X-Lite and many others)

·         Main protocols: SIP/SIPS, RTP/SRTP. IP layer protocols: IPv4/IPv6

·         Transport: auto, UDP, TCP, TLS, TCP tunnel, SOCKS proxy traversal, HTTP proxy traversal, HTTP, VPN tunneling

·         NAT/Firewall support: stable SIP and RTP ports ,keep-alive, UPnP, rport support, fast ICE/fast STUN protocols and auto configuration

·         Encryption: TLS/SRTP, tunneling and peer to peer encrypted media

·         RFC’s: 2543, 3261, 2976, 3892, 2778, 2779, 3428, 3265, 3515, 3311, 3911, 3581, 3842, 1889, 2327, 3550, 3960, 4028, 3824, 3966, 2663, 3022 and many other SIP related standards

·         IMS/3GPP/VoLTE (basic compatibility and features such as USSD or 3GPP SMS)

·         Supported methods: REGISTER, INVITE, reINVITE, ACK, PRACK, BYE, CANCEL, UPDATE, MESSAGE, INFO, OPTIONS, SUBSCRIBE, NOTIFY, REFER

·         Audio codec: G.711 (PCMU, PCMA), G.729, GSM, iLBC, OPUS, SPEEX, G.722.1

·         Video codec: H264, H263, H261, MPEG1, MPEG4, MPEG2, VP8,Theora

·         HD Audio: Wideband, ultra-wideband and full-band codecs (opus, speex, G.722.1)

·         Audio enhancements: Stereo output (will convert mono sources to stereo) , PLC (packet loss concealment), AEC (acoustic echo canceller), Noise suppression, Silence suppression, AGC (automatic gain control) and auto QoS

·         Conference calls (built-in RTP mixer)

·         Voice recording (local, FTP or HTTP upload in wav, mp3, gsm or ogg format), SIPREC, custom audio streaming (locally or to peers)

·         DTMF (INFO method in signaling or RFC2833)

·         IM/Chat (RFC 3428), group chat, SMS (including 3GPP SMS support), BLF and presence capability

·         Offline chat (late delivery if peer is offline)

·         Redial, call hold, mute, forward and transfer (attended and unattended)

·         Call park and pickup, auto-answer, barge-in

·         Balance display, call timer, inbound/outbound calls, Caller-ID display, Voicemail (MWI)

·         Additional features: call parking, early media, 3PCC, ED-137, local ring-back, PRACK and 100rel, replaces

·         High availability: auto server failover, transport failover, DNS SRV based failover, backup server configuration, auto-reconnect, network auto-recover

·         A long list of other minor features (see the parameters, the API and the FAQ for details)

·         Unlimited lines (multiple simultaneous calls), multiple accounts (register with multiple SIP accounts from the same instance)

·         Flexibility (all parameters/behavior can be changed/controlled by parameters and/or the API)

·         Cross-platform (any OS with Java SE support including Windows, MAC, Linux)

·         Works with all JVM versions (backward compatible until JVM v.1.5 / J2SE 5.0 which was released in 2004)

·         Always backward/forward compatible including the settings and the API (no settings or code changes are required when upgrading to new versions)

 

See the software homepage for a general presentation.

Licensing


The Mizu Java VoIP SDK (JVoIP) is sold with life-time unlimited client license (Advanced and Gold) or restricted number of licenses (Basic and Standard). You can use it with any VoIP server(s) which belongs to you or your company. Your VoIP server(s) address (IP or domain name) will be hardcoded into the software to protect the licensing. You can find the licensing possibilities on the Java VoIP SDK page. After successful tests please ask for your final version at webphone@mizu-voip.com. Mizutech will deliver the JVoIP build within one workday after your payment.

Release versions don’t have any of the demo limitations and can be fully customized with your branding with “mizu” and “mizutech” words and links removed. Your final build must be used only for you company needs (including your direct sip endusers).
Most (99.9%) of the code was written by Mizutech developers from scratch, including both the SIP and media stack, except the optional third-party modules listed below, with the goal of creating a compact but full featured, robust and easy to use SIP library for Java. The SDK is free from any patents or legal obligation toward third-parties.

The following freely and legally distributable open-source optional third-party modules might be used in your copy:

·         DNS: dnsjava under BSD license

·         Opus: the open-source opus codec implementation transformed to Java under three-clause BSD license.

·         Speex: the open-source speex codec implementation transformed to Java under revised BSD license.

·         G.729: based on open-source G.729 ITU-T implementation transformed to Java. Patent expired in 2017.

·         G.722.1: royalty-free ITU-T standard G.722.1 (05/2005)

·         GSM: open-source gsm codec from Tritonus under Apache license

·         OGG/Vorbis: open-source implementation transformed to Java under BSD license.

The library doesn’t have any external dependencies (the above libraries are also compiled into the .jar when applicable).

Title, ownership rights, and intellectual property rights in the Software shall remain with MizuTech and/or its suppliers.
The agreement and the license granted hereunder will terminate automatically if you fail to comply with the limitations described herein. Upon termination, you must destroy all copies of the Software. The software is provided "as is" without any warranty of any kind.

You may:

Use JVoIP on any number of computers (Advanced or Gold version)
Use JVoIP as an SDK embedded in your project
Give the access to functionalities provided by JVoIP for your customers or use within your company
Use JVoIP with VoIP servers for which you have license for (after the agreement with Mizutech). All the VoIP servers must be owned by you or your company. Otherwise, please contact our support to check the possibilities

You may not:

Resell JVoIP
Sell JVoIP as a standalone application (you are allowed to use it only coupled with your project which purpose should not be the same as JVoIP’s)
Sell “JVoIP” services for third party VoIP providers and other companies
Use JVoIP with VoIP servers not communicated with Mizutech (except if you have a special agreement with the Gold license)
Reverse engineer, decompile or disassemble JVoIP
Modify the software in any way (except modifying the parameters and using it via the public API)

You shall not use the JVoIP software in any way that competes either directly or indirectly with Mizutech (such as creating a general purpose Java SIP library), including but not limited to creation of derivative works that compete either directly or indirectly with our JVoIP software.
You shall not sell or offer JVoIP or the derivative works as a software or as a service for other companies, organizations or individuals which competes either directly or indirectly with Mizutech JVoIP offering.

Oracle Java licensing:

JVoIP has nothing to do with Oracle licensing.
You can use it with any JVM, including old Oracle Java SE versions, the new free Oracle Java SE versions or any other compatible Java implementations such as OpenJDK, IceTea, AdoptOpenJDK or any JVM bundled with your OS.

Demo version:

We are providing a demo version which you can try and test before any payment. The demo version has all features enabled but with some restrictions to prevent commercial usage. The limitations are the followings:

·         maximum 10 simultaneous JVoIP instances in the same time

·         will expire after several months of usage  (usually 2 or 3 months)

·         maximum ~100 sec call duration restriction

·         maximum 10 calls / session limitation (after 10 calls you will have to restart)

·         will work only maximum 20 minutes and after that you have to restart the JVoIP library or your application

·         verifications against the mizu license service

·         no headless mode (contact us if you need a headless trial)

 

Note: for the first few calls there might be fewer limitations than described above.

On request we can also send a trial version (will expire after some time but doesn’t have the above demo limitations).

To upgrade your demo/trial to an unlocked license, see the details here.

 

 

 

 

 

 

 

 

 

API

You can use JVoIP as an SDK directly embedding into your Java application. Additionally you can access the same API also from JavaScript or via UDP, TCP, HTTP from any application.

Functions

The SIP SDK exposes numerous API functions, however this doesn’t mean that the usage is difficult. You can ignore most of these functions and use only those few relevant for your needs also outlined in the usage example. For example if you just need to make simple calls, then the following three functions will cover all your needs: API_Start, API_Call, API_Hangup.

 

Most of the functions return a boolean value. True when the operation was completed or initiated successfully, otherwise false.

Some of the functions are executed asynchronously (API_Call, API_Register, etc). This means that it might return a true value immediately but it might fail later. For example for API_Call the return value means only that the call was initiated successfully. At this point we don’t know if the call will be successful (connected) or not. You can get the call status by parsing the notification messages or you can periodically poll JVoIP status with the API_GetStatus function or use the other available functions to query the SIP stack state.

Error handling: No exceptions are thrown from the API. For error handling check the returned boolean values and the check the notifications or state query related functions to detect SIP session issues such as failed registrations or call disconnects.

Threading: The API is thread-safe and most of the API functions doesn’t block (except GetNotificationsSync which has to be used from a separate thread if required).

 

The line parameter is part of most of the functions and it means the channel number to be used if you wish to select a specific session.
For simple use cases usually you just have to set it to -1. For the details, see the “
Line parameter” and the “Multiple lines” FAQ points.

 

Function string parameters can be passed in encrypted format. (Read the FAQ for more details regarding the encrypted parameters)

boolean API_SetParameter(String param, String value)

Configure JVoIP: param is the parameter name (key). The value can be string, int and boolean.

Most of the parameters can be set with this function except gui parameters (like the colors).
If you call this function after init/start, then some parameters can take effect only when JVoIP is reinitialized.
See the full list of supported parameters
here.

Example: wobj.API_SetParameter("loglevel", 5);

 

Note: some advanced parameters can be set also by line using the API_SetLineParameter function (for advanced users only; use the other API functions instead to control the individual lines). Parameters can be read with the String API_GetParameter(String param) and String API_GetLineParameter(int line, String param) functions.

 

boolean API_SetParameters(String parameters)

Pass a set of parameters with this function in value=key lines separated by CRLF (\r\n).

It has the same effect like the API_SetParameter function, but uses a list of parameters at once instead of setting them individually.

See the full list of supported parameters here.

Example: wobj.API_SetParameters("loglevel=5\r\ndtmfmode=1\r\n");

 

boolean API_SetCredentials(String server, String username, String password, String authname, String displayname)

Will set the SIP server address (ip:port or domain:port) the SIP username and the password. These values can also be preset by parameters. Parameters with empty strings will be omitted. For example if you would like to change only the username and the password, you can write  API_SetCredentials(“”,”newusername”, “newpassord”)

If authname is empty, then the username will be used for authentications. The displayname is usually empty (no special displayname will be presented for peers). If other parameters are empty, then they can be specified by user input (If the VoIP SDK has a visible user interface).

boolean API_SetCredentialsMD5(String server, String username, String md5, String realm)

Instead of passing the password directly you can use MD5 checksum.

In this case the md5 parameter must be the md5 checksum for username:realm:password

 

The realm parameter is optional (can be set as an empty string) but it is recommended for easy error detection. If present and the server realm don’t match with this one, an error message will be displayed by JVoIP.

boolean API_Start()

This has to be called only if you use JVoIP as and SDK or as a java voip library. Don’t call it from JavaScript. Will start the engine.

The autostart behavior can be altered with the startsipstack setting.

boolean API_StartStack()

This function call is optional to start the sip stack on demand.

If not called, then the sip stack is started anyway if the startsipstack parameter is set, otherwise will start at first registration or outgoing call attempt.

 

boolean API_Register(String server, String username, String password, String authname, String displayname)

Will connect to the SIP server.

Note: Registration can be also performed automatically at startup depending on the startsipstack and register parameters.

Parameters can be empty strings if you already supplied them by parameters or by the API_SetCredentials call.

If you already passed the server, username and password (or md5) parameters with the API_SetCredentials functions, then you can call this function with empty parameters: API_Register(“”,””,””,””,””);

This function have to be called only once at the startup. Further re-registrations are done automatically based on the registerinterval parameter.

If called multiple times than the old registrar endpoint is deleted and a new one will be created with a new call-id and JVoIP will reregister.

Even if you wish to force re-registration, you should not call this more frequently than 40 seconds (because up to 40 seconds might be needed for a slow registration attempt especially if tunneling is used or if JVoIP has to negotiate the transport protocol or the register expires interval).

 

boolean API_RegisterEx(String accounts)

                You can use this function for multiple secondary accounts (up to 99) on the same or other servers.

                Accounts parameters:

o    Server address

o    Username

o    Password

o    Register interval

o    SIP proxy

o    SIP realm

o    Auth user name (if separate extension id and authorization username have to be used)

Most of the parameters are optional.

The parameters have to be separated by comma (,) and the accounts have to be separated by semicolon (;).

All have to be passed in a single line which should look like this: server,usr,pwd,ival;server2,usr2,pwd2,ival2;                

                Example: sip1.mydomain,com,1111,xxx,300;sip2.mydomain.com,2222,xxx;

 

                See the Multiple account registration FAQ for more details.

 

boolean API_Unregister(int waitfor)

Will stop all endpoints (hangup current calls if any and unregister).

The waitfor parameter can be set to -1 (auto), 0 (do not wait) or 1 (wait for unregister to complete before to return).

 

If you wish also the pending calls to be disconnected with unregister, set the disconunregister parameter to 1, otherwise set it to 0.

Other behaviors can be modified with the waitforunregister and clearcredentialsonunreg parameters.

 

boolean API_CheckVoicemail(int line)

Will (re)subscribe for voicemail notifications. No need to call this function if the “voicemail” parameter is set to 2.

The line parameter should be set to -1.

 

boolean API_SetLine(int line)

Will set the current channel. (Use only if you present line selection for the users. Otherwise you don’t have to take care about the lines).

Note: Instead of using each API call with the line parameter, you can just use this function when you wish to change the active line and use all the other API calls with -1 for the line parameter.

int API_GetLine()

Will return the current active line. This should be the line which you have set previously except after incoming and outgoing calls (the SIP client will automatically switch the active line to a new free line for these if the current active line is already occupied by a call)

 

int API_GetLineStatus(int line)  or string API_GetLineStatusText(int line)

Query the status of the line.

Note: this is rarely needed since you receive the status also by event notifications

string API_GetLineDetails(int line)

Get details about a line. The line parameter can be -1 (will return the “best” line status).

Will return the following string:

LINEDETAILS,line,state,callid,remoteusername,localusername,type,localaddress,serveraddress,mute,hold,remotefullname

 

Line line number (might be useful if you pass -1 as line parameter

State same as in STATUS notification

CallID: SIP session id (SIP call-id)

Remoteusername is the other party username (if any)

Localusername is the local user name (or username).

Type is 1 from client endpoints and 2 from server endpoints.

Localaddress: local IP:port

Serveraddress: remote IP:port

Mute: is muted status. 0=no,1=undefined,2=sendonly,3=recvonly,4=both muted (or if you wish to simplify: 0 means no, others means yes)

Hold: is on hold status: 0=no,1= undefined,2=sendonly,3=recvonly,4=both in hold  (or if you wish to simplify: 0 means no, others means yes)

Remotefullname is the other party display name if any

 

boolean API_Call(int line, String peer)

Initiate call to a number or sip username.

If the peer parameter is empty, then will redial the last number.

Example: wobj.API_Call(-1, "DESTINATION");

 

Note: In case if your SIP server (set by the serveraddress parameter) is responsible to handle the call to the target number/extension/user, then you should pass only the peer number, extension or username to this function and not the full SIP URI (the SIP stack will construct the full SIP URI with the serveraddress already set)

 

boolean API_CallEx(int line, String peer, int calltype)

Initiate call to a number or sip username.

If the peer parameter is empty, then will redial the last number.

The calltype can have the following values:

Ø  0: initiate voice call

Ø  1: initiate video call

Ø  2: initiate screensharing session

 

Note: you should pass only the peer number, extension or username to this function and not the full SIP URI (the SIP stack will construct the full SIP URI with the serveraddress already set)

 

boolean API_Hangup(int line, String reasontext)

Disconnect current call(s). If you set -2 for the line parameter, then all calls will be disconnected (in case if there are multiple calls in progress). The “reasontext” parameter is optional.

 

boolean API_Accept(int line, int calltype)

Connect incoming call.

You should call this function when there is an incoming ringing call if you wish to connect the call.

The calltype parameter accepts the following values:

Ø  -1: default

Ø  0: audio only

Ø  1: with video

Ø  2: force video

 

Note: If the call was initiated without video capabilities by the remote peer, then video might not be added even if you call the API_Accept with video. In this case you should call the API_AddVideo for a re-INVITE with video capabilities.

boolean API_Reject(int line)

Disconnect incoming call. (API_Hangup will also work)

boolean API_Forward(int line, String peer)

Forward incoming call to peer (with 302 Moved Temporarily disconnect code).

SIP call forward is actually a call redirect (similar to HTTP redirect).

This function should be called only before call is connected. If you wish to forward a call after call connect, you should use the API_Transfer.

 

boolean API_Transfer(int line, String peer)

Transfer current call to peer which is usually a phone number or a SIP username. (Will use the REFER method after SIP standards).

You can set the mode of the transfer with the transfertype parameter.

If the peer parameter is empty than will interconnect the currently running calls (should be used only if you have 2 simultaneous calls)

This function should be called after call connect as most SIP servers doesn’t support REFER before call connect.

 

More details about call transfers can be found here.

 

boolean API_TransferDialog()

Instead of calling the API_Transfer function and pass a number, with this function you can let JVoIP to ask the C number from the user.

 

boolean API_AddVideo(int line,  int calltype)

Add video media for an existing voice call.

The calltype can have the following values:

Ø  1: add video

Ø  2: add screensharing

boolean API_StopVideo(int line)

Will stop the video stream at the specified line.

 

boolean API_MuteEx(int line, boolean mute, int direction)

Mute current call.

The line parameter is the endpoint. -2 for all or -1 for current line.

Set the mute parameter to true for mute or false to un-mute.

The direction can be set to one of the followings:

Ø  0: mute in and out

Ø  1: mute out (will mute the speakers, so the local user will not hear anything)

Ø  2: mute in (will mute the microphone, so the other party will not hear anything)

Ø  3: mute in and out (same as 0)

Ø  4: mute default (set by the “defmute” parameter, which is “mute microphone only” by default)

 

Note:

o    The mute function should be used only for endpoints in call and it will be ignored if not in call

o    If you wish the audio to be always muted, then you might just set the defsetmuted parameter to 1.

o    If you don’t wish to use audio device at all, then you might set the useaudiodeviceplayback and/or useaudiodevicerecord parameters to false.

o    You can also change the automute parameter to automatically mute other lines on new calls.

o    If you wish to keep sending RTP packets (with silence) while muted, then set the sendrtponmuted parameter to true

o    For more details see here.

 

int API_IsMuted(int line)

Return if the selected line is muted or not.

Return values:

Ø  -1: unknown

Ø  0: not muted

Ø  1: both muted (in/out)

Ø  2: out muted (speaker)

Ø  3: in muted (microphone)

Ø  4: both muted (in/out; same as 1)

int API_IsOnHold(int line)

Query if the selected line is on hold or not

Return values:

Ø  -1: unknown

Ø  0: no

Ø  1: not used

Ø  2: send only (JVoIP will suppress playback)

Ø  3: receive only  (JVoIP will suppress recording)

Ø  4: both in hold

 

     Note: pass -2 for the line to find if any endpoint is in hold

boolean API_Hold(int line, boolean hold)

Hold current call. This will issue an UPDATE or a reINVITE.

Set the second parameter to true for hold and false to reload.

 

Hold means that the media stream is muted in one direction or both directions.

You can modify the holdtypeonhold parameter after your needs (also at runtime, by changing the holdtypeonhold just before calling API_Hold).

This function should be used only after call connect as many SIP servers doesn’t support UPDATE/re-INVITE before call connect.

 

boolean API_HoldChange(int line)

Same as API_Hold, but without the second parameter. This call will always invert the hold status for an endpoint (If the call was active, then it will switch to held status and if the call was in hold, then it will reactivate it).

 

boolean API_Conf(String peer)

Add people to conference.

If peer is empty than will mix the currently running calls (if there is more than one call)

Otherwise it will call the new peer (usually a phone number or a SIP user name) and once connected will join with the current session.

 

JVoIP is capable for both 3 way SIP conferencing and also to create and handle conferences with unlimited number of participants using its own built-in RTP mixer. Conference parties can use various codec’s, including both 8kHz narrowband and 16 kHz wideband.

 

boolean API_ConfEx(int line, String peer, boolean add)

Add/remove people or line to conference.

If peer is empty string than:

                -if add is true:

-if line is -2 then it will mix all the currently running calls (if there is more than one call)

-if line is not -2, then it will add the channel to the conference

                                -if add is false:

                                                -if line is -2 then it will destroy the conference (but will keep the calls on individual lines)

                                                -if line is not -2 then it will remove the selected line from the conference

Otherwise it will call the new peer (usually a phone number or a SIP user name) and once connected will join with the current/old call session.

 

Please note that to be able to make conference calls, you should make one (or two) call first using the API_Call function.
Then use the API_Conf or API_ConfEx to convert the existing call to a conference and to add one or more peers.

 

boolean API_Dtmf(int line, String dtmf)

Send DTMF message by SIP INFO, RFC2833 or In-Band method (depending on the “dtmfmode” parameter). Please note that the dtmf parameter is a string. This means that multiple dtmf characters can be passed at once and the VoIP SDK will streamline them properly. Use the space char to insert delays between the digits.  

Valid dtmf characters in the passed string are the followings: 0,1,2,3,4,5,6,7,8,9,*,#,A,B,C,D,space.

The dtmf messages are sent with the protocol specified with the dtmfmode parameter.

Feedback about the message delivery can be received with the INFO notifications.



Example:  API_Dtmf(-2,” 12 345 #”);

 

Note: dtmf messages can be also sent by adding it to the called number after a comma. For example if you make a call to 123,456 then it will call 123 and then it will send dtmf 456 once the call is connected.

 

For more details see the How to DTMF FAQ point.

 

boolean API_Info(int line, String msg)

Send any SIP INFO message as defined in RFC 2976.

Use this API to send any custom INFO messages to the server or to the connected peer (in case if your server will forward it to other peer and not discard it).

The msg string will be sent in the INFO body.

The Content-Type can be specified with the infocontenttype parameter. For example you might set the infocontenttype to “application/mydata”. If the infocontenttype is not set then it will be auto guessed as application/json, application/xml or application/octet-stream”

Feedback about the message delivery can be received with the INFO notifications.

 

Example:  API_Info(-2,”MyMessage”);

 

For more details see the Custom INFO messages FAQ point.

 

boolean API_SendUSSD(int line, String method, String ussd)

Send an USSD message after the IMS 3GPP TS 24.390 standard.

The method parameter can be set to “INVITE”, “INFO” or “BYE”.

If INVITE, then a new session will be created. Otherwise will use the session suggested by the line parameter.

The ussd parameter have to be set to the USSD string (for example “*135#”) or whole XML (“<?xml version … “).

USSD strings should be up to 182 characters.

 

Will return true if send initialized successfully or false on failure.

Further feedback about the actual delivery or incoming ussd messages can be obtained from the USSD notifications.

More details here.

 

boolean API_SendChat(int line, String peer, String group, String message, int msgid)

Send a chat message. (usually SIP MESSAGE method after RFC 3428 or as configured by the textmessaging parameter)

Parameters:

o    line: channel number. Usually you can just set it to -1.

o    peer: phone number or SIP username/extension number.

o    group: optional group name parameter. Used only for group chat, otherwise it can be an empty string.

o    msgid: optional id. You can pass any (unique or auto incrementing) positive number to match the CHATREPORT notifications.

 

Example:

wobj.API_SendChat(-1, "john", "", "Test Message");

 

Parse the CHATREPORT notification to check if delivery succeeded or failed.

On successful delivery you will also receive a log like:  EVENT, chat sent successfully

On failed delivery you will also receive a log like: WARNING, chat message not delivered

You can also send typing notifications with the SendChatIsComposing API.

Incoming instant messages (IM or SMS) are reported as CHAT notifications.

 

boolean API_SendSMS(int line, String peer, String message, int id)

Send a SMS message if softswitch has SMS delivery capabilities (Otherwise might try to deliver as IM).

The message is delivered as a 3GPP SMS, SMS HTTP API request or a standard SIP MESSAGE with X-Sms: Yes header (in this case the server is responsible to convert it to SMS).

Everything is like API_SendChat, except that this function will try to send SMS instead of chat (also depending on the textmessaging parameter).

boolean API_Chat(String peer)

Instead of calling the API_SendChat function and pass a message, with this function you can let the voip client to open its chat form.

Will open the chat form (the “number” parameter can be empty)

Peer can be a SIP username or extension number.

This function will not work with the headless version (the headless is for library or command line usage and it doesn’t have any built-in GUI).

 

boolean API_VoiceRecord(int startstop, int now, String filename, int line)

Will start/stop a voice recording session.

·         startstop: 0 to stop, 1 to start locally, 2 to start remote ftp or http, 3 start to record both locally and to remote ftp/http, 4 start to record as it is set by the “voicerecording” parameter

·         now: used if the startstop is set to 0. 0 means that the recorded file will be saved and/or uploaded at the end of the conversation only. 2 means that the file will be saved immediately

·         filename: file path and/or name used for storing the recorded voice (if empty string, than will use a default file path and name)

·         line: set to -2 for global, -1 for the current active line or specify channel number

 

Examples:

//start recording any calls to local file (file will be stored as specified by the voicerecfilename and voicerecformat parameters)

wobj.API_VoiceRecord(1, 2, "", -2);

 

//start recording on all lines as specified by the voicerecording, voicerecfilename and voicerecformat parameters.

wobj.API_VoiceRecord(4, 2,"", -2);

 

//stop call recording on all lines

wobj.API_VoiceRecord(0, 2,"", -2);

 

//start recording the current active call and upload to the specified ftp once ready in the specified format (wav) and file name.

wobj.API_VoiceRecord(2, 2,"ftp://ftpuser:ftppassword@myftpserver.com:21/callrecord_DATETIME_USER.wav”, -1);

 

//start recording on the current active call and upload to the specified web-service once ready (also keep the file locally)

wobj.API_VoiceRecord(3, 2," http://www.foo.com/myfilehandler.php/FILENAME", -1);

 

//will stop call recording on line 1 once call is terminated

wobj.API_VoiceRecord(0, 0,"", 1);

 

 

Notes:

This function should be used only if you would like to control the recording duration.

If all conversations have to be recorded, then just set the “voicerecording” parameter after your needs.

The recording starts when you call this function with a positive startstop parameter and will end once the call disconnects or when you call it again with startstop parameter set to 0.

 

This function is capable to overwrite most of the voice recording related parameters: for example if you specify a full URL as the file name, then it will use this URL instead of the URL specified by the http_addr or voicerecftp_addr parameter. If you set a file name terminating with a file extension (such as .wav or .mp3) then it will recording in this format instead of the format preconfigured by the voicerecformat parameter.

 

For more details see the voice record FAQ.

(In case if you wish to receive the audio packets/audio stream in real time, then you can use the local audio streaming capabilities instead)

 

boolean API_PlaySound(int start, String file, int looping, boolean async, boolean islocal, boolean toremotepeer, int line, String audiodevice, boolean isring)

Play any sound file.

This function can be used to play audio locally, but also for remote streaming.

 

The file must be found near JVoIP.jar.

·         start: 1 for start or 0 to stop the playback, -1 to pre-cache

·         file: file name

·         looping: 1 to repeat, 0 to play once (only for local playback)

·         async: false if no, true if playback should be done in a separate thread (false can be used only for local playback, not for streaming)

·         islocal: true if the file have to be read from the client PC file system. False if remote file (for example if the file is on the webserver)

·         toremotepeer: stream the playback to the connected peer

·         line: used with toremotepeer if there are multiple calls in progress to specify the call (usually set to -1 for the current call if any)

·         audiodevice: you can specify an exact device for playback. Otherwise set it to empty string

·         isring: whether this sound is a ringtone/ringback

 

Examples:

-playback a file locally (mysound.wav must exist near the JVoIP.jar file):

API_PlaySound(1, "mysound.wav", 0, false, false, false, -1,””,false)

-playback a file to the connected remote peer (mysound.wav must exist near the JVoIP.jar file):

API_PlaySound(1, “mysound.wav", 0, false, false, true, -1,””,false)

-stop the playback:

API_PlaySound(0, "", 0, false, false, false, -1,””,false)

 

Notes:

·         The singleaudiostream parameter must be set to 0 if you wish to play simultaneous streams to remote (for multiple concurrent calls)

·         You might set the useaudiodevicerecord parameter to false if you need streaming but don’t have an audio recorder device installed.

·         If you plan to use this functionality running JVoIP on a server, then have a look at the Using JVoIP on a server FAQ

·         If the previous sound file haven’t finished the playback yet when you supply a new one then the remaining from the old one will be dropped and the new file will start to be played immediately

 

File format:

At least wave files (raw linear PCM) are supported in the following format:  PCM SIGNED 8000.0 Hz (8 kHz) 16 bit mono (2 bytes/frame) in little-endian (128 kbits). In case if your wave file is narrowband (8 kHz 16 bit mono), then the stream will be automatically converted to wideband if the VoIP audio codec is wideband such as opus or speex. In case if your wave file is wideband (16 kHz 16 bit mono) then you should set the playbacksteamformat parameter to 1 to allow auto conversion to narrowband if the VoIP audio codec is narrowband such as G.711 (PCMU, PCMA), G.729 or GSM.

 

boolean API_StreamSoundBuff(int start, int line, byte[] buff, int len)

Stream from raw wave audio PCM (Linear PCM) buffer or from RTP packets.

This function will stream the supplied audio buffer to the peer endpoint, transcoding if necessary.

 

Parameters:

·         start: 1 for start or 0 to stop the playback

·         line: specify the channel in case if there are multiple calls in progress (usually set to -1 for the current call if any)

·         buff: audio buffer (raw PCM data or RTP packet)

·         len: length of the buff (ideally it should be multiple of 360 if raw pcm or the size of the RTP packets which are to be passed separately)

 

Notes:

·         The buff should not contain any file header if you are using raw PCM (only raw linear PCM audio data) and it should contain a full RTP packet (with the RTP header) if you are passing RTP data.

·          You might set the useaudiodevicerecord parameter to false if you need streaming but don’t have an audio recorder device installed.

·          If previously supplied buffer(s) are not completed yet, then the new one will be queued.

·          If you are streaming in real-time (feeding the API with short RTP/audio packets) then you might set the realtimeplayback parameter to 1.

·          Alternatively you can use the API_StreamSoundStream function to pass an InputStream instead of buff and len.

·          In case if you wish to receive the audio stream from the remote peer endpoint, see this FAQ point instead.

 

 

Buffer/stream format:

At least raw linear PCM is supported in the following format:  PCM SIGNED 8000.0 Hz (8 kHz) 16 bit mono (2 bytes/frame) in little-endian (128 kbits). In case if your buffer is narrowband (8 kHz 16 bit mono), then the stream will be automatically converted to wideband if the VoIP audio codec is wideband such as opus or speex.  In case if your buffer is wideband (16 kHz 16 bit mono) then you should set the playbacksteamformat parameter to 1 to allow auto conversion to narrowband if the VoIP audio codec is narrowband such as G.711 (PCMU, PCMA), G.729 or GSM. With raw PCM the supplied buffer length should be a multiply of 160 or 320, otherwise extra bytes might be dropped.

The function can accept also RTP packets and will transcode them if necessary. Set the streamsoundisrtp parameter to -1 to auto-guess raw PCM vs RTP (this is the default value), set to 0 if you supply raw PCM buffer or set to 1 if you supply RTP packets.

 

                See more details here.

 

boolean API_AudioDevice()

Open audio device selector dialog (built-in user interface).

This function will not work with the headless version (the headless is for library/SDK or command line usage and it doesn’t have any built-in GUI).

 

string API_GetAudioDeviceList(int dev)

Will return the list of available audio devices separated by \r\n.

Set the dev parameter to 0 to list the recording (audio in / microphone) device names. Set to 1 to get the playback/speaker or ringer devices.

Note:

Instead of using this function, you might just call the “API_AudioDevice” to let the users to change their audio settings.

When using the native winapi audio engine, the device names might be truncated to the first 30 character due to the wave audio API limitations.

You can pass the same back to the webphone and it will select the audio device correctly.

string API_GetAudioDevice(int dev)

Will return the currently selected audio device for the dev line (dev values are 0 for recording, 1 for playback, 2 for ringer).

 

boolean API_SetAudioDevice(int dev, string devicename, int immediate)

Select an audio device. The devicename should be a valid audio device name (you can list them with the API_GetAudioDeviceList call)

The “dev” parameter can have the following values:

0: recording device (microphone)

1: playback device (speaker, headset)

2: ringer device (speaker, headset)

The “immediate” parameter can have the following values:

0: default (after the “changeaudiodevimmediate” parameter)

1: next call only

2: immediately for active calls

Note:

For the ringer device you can also pass the “All” string as the devicename to make voip application to ring on all devices for incoming calls.

All devices can also accept the “Default” device name, which will select the system default audio device.

For the device you can also pass a number which is the order of the audio device as returned by API_GetAudioDeviceList staring from 1. Valid values are between 1 and 9 or 0 for the system default device.

Instead of this function you might just call the “API_AudioDevice” function which will present an user interface to let the users to change their audio settings.

 

boolean API_SetVolume(int dev,int volume, int line)

Set volume (0-100%) for the selected device.

The dev parameter can have the following values:

0 for the recording (microphone) audio device

1 for the playback (speaker) audio device

2 for the ringback (speaker) audio device

                The line is an optional parameter to be used only if you need different volume for separate calls.

int API_GetVolume(int dev, int line)

Return the volume (0-100%) for the selected device.

The dev parameter can have the following values:

0 for the recording (microphone) audio device

1 for the playback (speaker) audio device

2 for the ringback (speaker) audio device

                The line is an optional parameter to query the volume of a specific call line in case if you set the volume per call. Otherwise don’t use or set to -2.

 

String API_VAD(int line)

Returns voice activity statistics.

It will return the VAD status string as described at the VAD notification.

If line is 0 or negative then it will report global send/recv statistics.

If line is positive then it will report receiver state for the requested line.

You should set the vad parameter to at least 2 (4 for full report), although calling this function will also set it, but at first call will not have statistics if it was not set.

Note: if you call this function, VAD notifications will not be sent automatically anymore. (So you will need to continue to poll for the details).

More details here

 

String API_RTPStat()

Returns media statistics. See the RTPSTAT notification for more details.

For this to work you should set the vad parameter to at least 2 (4 for full report).

Note:

RTP statistics can be sent also automatically if you set the rtpstat parameter.

if you call this function, RTPSTAT notifications will not be sent automatically anymore

More details here.

 

String API_GetVersion()

Return the program version number.

String API_GetStatus(int line, int strict)

Returns line status or global status if you pass -2 as line parameter. The possible returned texts are the same like for notifications (listed below).

If the strict variable is set to 1, then it will return “Unknown” if no such line is activated. If the strict variable is set to 0, then it will return the default active line if the line doesn’t exists.

 You should use the notifications described below to get the actual status of JVoIP instead of continuously polling it with this function call.

 

String GetNotifications()

Return the notification strings. You should poll for the notifications periodically from a separate thread. It will return accumulated events since the last function call (notifications separated by \r\n  -CRLF).

You might set the “polling” parameter to 3 if you wish to use this function (and not socket or webphonetojs events)

 

More details here.

 

Note:

·          We are using simple polling for this since Java doesn’t have function pointers to be used as a callback and other methods are either deprecated (Observer interface) or too complex (external libraries).

·          Once a notification string have been read then it will be cleared from the internal list, so it is guaranteed that you will never receive duplicates.

·          If you are using the library from javascript then just use a timer instead of a thread

 

String GetNotificationsSync()

                Same as above, but will blocking wait for data (more efficient).

 

 

Contacts

Contacts are normally handled by the caller process (your app) because they have less to do with the VoIP stack (except presence status). This should be done easily from your application and better adopted to your needs. You can use the above JVoIP API to add VoIP functionality to your address book or contact list. The status (Online/Offline/Busy) of the users can be loaded from your softswitch database. Based on the user presence you can display the different buttons with your design. Near each contact you can display a call/chat button which will launch a voip endpoint instance preconfigured with the actual contact (“callto” parameter).

 

However for your convenience, the VoIP SDK also provides a simple contact management API.

 

Contact parameters are stored as comma delimited strings with the following parameters:

imstatus,name,sip,phone,phone2,phone3,othernumbers,sipcontacturi,email,web,address,speeddial,extra,internalextra

 

 

boolean API_SetContacts(String contacts)

Set all contacts (contact parameters separated by new line)

 

String API_GetContacts()

Will return all contacts (in separated lines the parameters described above)

 

boolean API_DelContact(String name)

Delete contact.

 

boolean API_AddContact(String params)

Add a contact. Example: Add_Contact(‘,John Smith,jsmith,’);  //here we set only the name and the SIP fields

 

boolean API_SetContact(String name, String params)

Change contact.

 

String API_GetContact(String name)

Will return a single contact in the format described above.

 

Helper functions to set/get individual fields:

 

boolean API_SetContactName(String name, String param)

Set contact name.

 

boolean API_SetContactSIP(String name, String param)

Set contact sip uri.

 

boolean API_SetContactPhone(String name, String param)

Set contact phone number.

 

boolean API_SetContactSpeedDial(String name, String param)

Set contact speed dial number (short number).

 

String API_GetContactName(String name)

Get contact name.

 

String API_GetContactSIP(String name)

Get contact sip uri.

 

String API_GetContactPhone(String name)

Get contact phone number.

 

String API_GetContactSpeedDial(String name)

Get contact speed dial number (short number).

 

Presence

Presence is based on SIP SIMPLE SUBSCRIBE/NOTIFY mechanism and it is used to detect the online status of the contacts.

There is no need to manage the contacts within SIP endpoint (as described above) to have presence functionality (so you can manage the contacts externally in your application).

The following steps are required:

1.        Related settings:

o    enablepresence: 0/1

o    email = email address sent with contact info

o    presenceexpire = 3600

o    autoacceptpresencrequests = -1;  //-1: not set (1), 0=auto reject all,1=ask for new users,2=yes, autoaccept new unknown users

2.        First you should call API_PushContactlist to pass all the usernames and phonenumbers from your external contact list if any. This is necessary, because for existing contacts JVoIP can accept the requests automatically, while for other it might ask for user permission

3.        On first start you might call API_NumExists. If using the Mizu VoIP server, then it will return all existing contacts with SERVERCONTACTS,userlist notification where userlist are populated with the valid users and their online status.

4.        Call API_CheckPresence(userlist). To save softswitch resources, you should carefully select the contacts. (Send only the contacts which are actually used and called numbers. We recommend up to 50 contacts. If the user select a contact, then you can call this function later with that single contact to request its status). This function will start to send SUBSCRIBE requests.

5.        Use the API_SetPresenceStatus(statustring) function call to change the local user online status with one of the followings strings: Online, Away, DND, Invisible , Offline (case sensitive) . This function will start to send NOTIFY requests to subscribed parties.

Note: presence per user can be also set by upresence_USERNAME parameters.

6.        Once these are done, the following notifications can be received from java sip stack:

NEWUSER,peerusername,displayname,email,URI

PRESENCE,peerusername,status,details,displayname,email

(displayname and email can be empty)

 

On newuser, you should ask the user if wish to accept it. If accepted, call the API_NewUser function. The same function should be called when the user adds a new contact to its contactlist.

For presence the following status strings are defined (be prepared to receive any of these and handle it with case insensitive by displaying red/green/gray/other icons):

o    Open/Online/Reachable/Available/Call Me/Registered  [GREEN]

o    DND (Do not disturb; halt popups and sounds)  [RED]

o    Busy/Speaking (can be auto set) [ORANGE/YELLOW]

o    Pending/Forwarding [ORANGE/YELLOW]

o    Away/Idle [ORANGE/YELLOW]

o    Close/Unreachable/Offline/Unregistered [GREY/WHITE]

o    Unknown/Not Set/NotExists [GREY/WHITE/NOCOLOR]

o    Invisible (no status notifications will be sent) [GREY/WHITE/NOCOLOR]

Other suggestion for colors:

o    red: busy/dnd

o    bright green: online

o    pale green:  away/forwarding/pending

o    white: user exists but unknown status or invisible

o    no color: user doesn’t exists / no presence feature

 

7.        You might use the API_UnSubscribe() API to unsubscribe all endpoints (this includes presence, voicemail and BLF subscribes).

 

Note: presence is initiated automatically with called contacts after call disconnect if it was n

 

BLF

BLF (Busy Lamp Field) can be used to monitor the state of an extension and it is implemented as SUBSCRIBE/NOTIFY with dialog event package as described in RFC 3265 and RFC 4235.

 

The main difference between presence and BLF are the followings:

·          They are implemented differently, based on different RFC’s (both based on SUBSCRIBE/NOTIFY, but different message exchange.

·          Presence is focusing for availability (online/offline), BLF is focusing on call state (ringing/speaking)

·          BLF usually have to be enabled explicitly to work with selected peers, presence might be enabled by default for all “friends”

·          Presence can be used to track friend’s online state, while BLF is used mostly in offices to track another device call-state such as a secretar tracking it’s boss phone to know when it is available/off-hook (for example if it is available to transfer a new call to it).

 

Set the enableblf parameter to enable/disable BLF. The following values are defined:

                0: disable BLF

                1: auto (from here it will auto switch to 0 or 2 regarding the circumstances –whether BLF was initiated and succeed/failed)

                2: enable BLF

                3: force always (if you set to 3 then it can’t be switched off later and will use BLF even after failure)

                Default value is 1.

 

To subscribe to other extensions call state, you can set the blfuserlist parameter or use the API_CheckBLF(userlist) to subscribe to other extension(s) state changes (users separated by comma). To remove an extension, just modify the blfuserlist parameter or call the API_DisableBLF(userlist) API.

 

Make sure that the peer extension(s) also has BLF support (so it can respond with NOTIFY for the BLF SUBSCRIBE).

Once the state of the remote extension(s) are changed, you will receive BLF notifications in this format:

BLF,peerusername,direction,state,callid

Fields:

·         BLF: state header string

·         peersusername: extension username

·         direction 

o    undefined (not for calls or not announced by the peer)

o    initiator (outgoing call)

o    receiver (incoming call)

·         state

o    trying (call connect initiated)

o    proceeding  (call connecting)

o    early (ringing or session progress)

o    confirmed (call connected)

o    terminated (call disconnected)

o    unknown (unrecognized call state received)

o    failed (BLF subscribe or notify failed)

·         callid: optional value if reported from the remote extension (the SIP call-id of the call)

 

Miscellaneous

Some other not so important API calls are listed below:

 

boolean API_Test()

You might use this function to check the API availability. Should return true.

 

int API_TestEx()

You might use this function to check the API availability. Should return 42.

 

boolean API_Test()

You might use this function to check the API availability (should return true).

 

boolean API_HTTPKeepAlive()

This is needed only if used from web via JavaScript.

You should call this function periodically more frequently than the timeout specified by the “httpsessiontimeout” parameter.  (For example call this in every 5 minute). This is to prevent orphaned JVoIP instances (when your html page was closed or crashed but JVoIP is still running in the background).

If you don’t wish to call this function periodically, then you should set the “httpsessiontimeout” parameter to 0.

 

boolean API_ServerInit(String address)  -deprecated

Call this function before to start any communication with this address (usually an IP number). This is required to release the Java security restrictions.  Wait 1-2 second before calling the next function like API_Register or API_Call. This function is deprecated since v.3.8 (no need to call this, just call API_Register or others directly)

 

boolean API_StartGUI()

Launch the built-in simple phone user interface even if the app was launched from command line.

 

boolean API_Stop()

Will stop all endpoints. This function call is optional when you unload JVoIP from external app.

 

boolean API_Exit()

Will stop all endpoints and terminates the java sip application. This function call is optional when you unload the JVoIP java module or wish to issue a forced termination. Its behavior can be controlled by the “exitmethod” parameter.

 

boolean API_CapabilityRequest(String server, String username)

Will send an OPTION request to the server. Usually you should not use this function.

The server parameter can be empty if you already set it with other API calls or by parameter.

The username parameter can be empty (in this case the “From” address will be set to “unknown”)

 

void API_CheckConnection()

You might call this function to quickly recover from connection failures on events not know by JVoIP such as app switched to foreground (otherwise JVoIP should auto-recover from network failures)

 

String API_LineToCallID(int line)

Get the SIP Call-ID for a line number.

 

int API_CallIDToLine(String callid)

Get the line number for a SIP Call-ID.

 

boolean API_SetLineParameter(int line, String param, String value, int permanent)

Set parameter for the current/next/all/specific line. Only some of the parameters are supported by this function (listed below).

These are advanced settings and this function might be used only if you need some specific/different behavior for a specific line only.

Otherwise, the behavior of the different lines are loaded from the global configuration (parameters), from the circumstances
or can be influenced by the other API functions (try to use the other API’s instead of this when possible).

Parameters:

Line: channel number.

If -2, then it will be set as global config like the API_SetParameter.

If -1, then for the active line.
If 0, then it will be applied for all next/new channel(s).

Otherwise it will be applied for the specific line.

                Param: settings key name

Value: value as string (or "NULL" to clear any old preset)

Permanent

If 1 then the setting will be kept for all future lines with the same line number

If 0 then the setting will be applied only for the current or very next channel with the same line

               

The following parameters are supported by this function:

peer (called number),address (will set both the serveraddress and proxyaddress),serveraddress,proxyaddress,

username,authusername,password,displayname,

voicerecording,muted,holded,maxsipmessagesize,codecretry,disccode,registerinterval,maxmsgresend,srtp_suite,strictsrtp,dtmfmode,rtp_timestamp,

rtp_seq,rtp_ssrc,defpayload,setfinalcodec,presenceexpiresec,notifyexpiresec,sipproto,volumein,volumeout,volumering,videocalltype,videodirection,

keepvideosdponhold,defvideopayload,serverdomainandport,serveraddr,serverport,serverip,proxyport,proxyip,realm, customsipheader,customsdpfield,customsdpmediafield,sip_uui,sessionid,discreason,usesdpip,transport,line,callid,state

                                                                                                                                               

All preset settings for all lines can be removed by passing 0 for the line and empty or NULL for both the key and the value.

 

Examples:

wobj.API_SetLineParameter(1,"username", "mia",0); //set the username to mia for the next call on line 1

wobj.API_SetLineParameter(2,"username", "mia",1); //set the username to mia for all upcoming calls on line 2

wobj.API_SetLineParameter(2,"username", "NULL",1); //clear the permanently preset username from line 2

wobj.API_SetLineParameter(-1,"muted", "0",0); //unmute the current call (use the API_Mute instead)

wobj.API_SetLineParameter(0,"muted", "4",0); //set the default muted state both side mute for the next call

wobj.API_SetLineParameter(0,"NULL", "NULL",1); //clear all the permanent settings from all lines

 

Line parameters can be read with the String API_GetLineParameter(int line, String param) function.

 

boolean API_SetSIPHeader(int line, String hdr)

Set a custom SIP header (a line in the SIP signaling) that will be sent with all messages. Can be used for various integration purposes (for example for sending the http session id).

Example: API_SetSIPHeader(-1, "X-MyData: VALUE");

Multiple headers can be separated by CRLF (\r\n). You can also set this with the customsipheader parameter.

Line -2 means all lines, -1 means current active line or use 1+ means for an existing line in call.

You can set a SIP header for the next call by using line number -3 or clear the old header(s) by using line number 0.

 

boolean API_SetSDPField (int line, String field, int type)

Set a custom SDP field (a line in the SDP body) that will be sent with all messages.

Set the type parameter to 0 for global values (before the m= line) or 1 for media values (after the m= line).

Example: API_SetSDPField(-1, "a=3ge2ae:requested",1);

Multiple headers can be separated by CRLF (\r\n). You can also set this with the customsdpfield and customsdpmediafield parameters.

Line -2 means all lines, -1 means current active line or use 1+ means for an existing line in call.

You can set a SIP header for the next call by using line number -3 or clear the old header(s) by using line number 0.

 

boolean API_RTPHeaderExtension (int line, int profile, String extension)

Set RTP header extension for the RTP packets.

The profile will be set as the first two bytes in the extension header (might be used as a custom identifier or parameter).

The extension can be one or multiple numbers separated by semicolon (;). These numbers will be sent as 32 bit words with the RTP header extension payload.

Example: API_RTPHeaderExtension (-1, 1, "987"); //will set the profile number to 1 and the rtp extension word to 987 for the current call

Line -2 means all lines, -1 means current active line or use 1+ means for an existing line in call.

You can set a SIP header for the next call by using line number -3 or clear the old header(s) by using line number 0.

Set the profile to 0 and the extension string to empty to clear it.

See the RTP header extension FAQ point for more details.

 

boolean API_ED137PTT (int line, int ptt, int pttid)

ED-137 Push to talk.

Parameters:

o    line: channel number

o    ptt: 0: off (not speaking), 1: on (Normal PTT ON), 2: Coupling PTT ON, 3: Priority PTT ON, 4: Emergency PTT ON

o    pttid: optional PTT-ID (otherwise loaded from global config)

Will return true if initiated successfully or false on failure.

The ed137 parameter should be set to 1 before using this function. See the ED_137 guide for more details

 

boolean API_SetUUI(int line, String value, int fortarget)

Set a custom UUI (User-to-User Call Control Information as described in RFC 7433).

Value is the UUI data (with or without parameters)

Fortarget specifies if the UUI have to be sent to target party with call transfer or redirect escaped. 0: no (to peer with the User-to-User header), 1: yes (to target in Contact or Refer-To URI), 2: both.

 

You might call this function just before JVoIP have to send a SIP signaling message to transmit an UUI (for example before a call or just before a call transfer).

 

Example:
API_SetURI(-1, "anydata”,-2);

API_SetURI(-1, "anydata;encoding=hex;purpose=foo;content=bar”,-2);

You can also set this with the sip_uui parameter.

 

String API_GetSIPHeader(int line, String hdr)

Return a SIP header value received by JVoIP. If not found it will return a string beginning with “ERROR:” such as “ERROR: no such line”.

 

String API_GetSDPField(int line, String field)

Return a SDP field value received by JVoIP. If not found it will return a string beginning with “ERROR:” such as “ERROR: no such line”.

 

boolean API_SendSIPMessage(int line, String msg, String body, String account)

Send a custom SIP signaling message (for example OPTIONS, NOTIFY, etc).

Parameters:

o    line: endpoint where the message will be sent. -3: new endpoint, -2: all endpoints, -1: current active, 0: register endpoint, 1+: call channel number

o    msg: SIP message to send. It can be just the method name (OPTIONS,MESSAGE,NOTIFY,INVITE,etc), the full message header or the full message including also a body (such as SDP)

o    body: optional SIP message body (such as SDP, xml payload or chat text, etc). Set to "null" if body must not be sent.

o    account: optional SIP account details if you wish to use other parameters then the configured one.
same format like the
extraregisteraccounts parameter

Examples:

o    Send a custom REGISTER request: wobj.API_SendSIPMessage(0, "fullregistermessagehere", "", "");

o    Send UPDATE on line 1: wobj.API_SendSIPMessage(1, "UPDATE", "", "");

o    Send OPTIONS to another server: wobj.API_SendSIPMessage(-3, "OPTIONS", "", "otherserveraddress.com:port,username,password");

o    Send PUBLISH with a custom body: wobj.API_SendSIPMessage(-3, "PUBLISH", "anymessagehere", "");

 

String API_GetSIPMessage(int line, int dir, int type)

Return the last received or sent SIP signaling message as raw text.

Dir:

                0: in (incoming/received message)

                1: out (outgoing/sent message)

Type:

                0: any

                1: SIP request (such as INVITE, REGISTER, BYE)

                2: SIP answer (such as 200 OK, 401 Unauthorized and other response codes)

                3: INVITE (the last INVITE received or sent)

                4: the last 200 OK (call connect, ok for register or other)

 

String API_GetLastRecInvite()

Return the last received INVITE message.

 

String API_GetLastSentInvite()

Return the last sent INVITE message.

 

String API_GetLastRecSIPMessage(String line)

Get the last received SIP message as clear text. Line is the line number or the SIP call id.

 

String API_GetLastRecFileName (String line)

Returns the last recorded file name.

 

String API_SendChatIsComposing (String line, String number)

Send typing notification.

 

boolean API_IsOnline() 

Return true if network is present

 

boolean API_IsRegistered() 

Return true if JVoIP is registered (“connected”) to the SIP server.

 

int API_IsRegisteredEx() 

Returns extended registration state: 0=unknown,1=not needed,2=yes,3=working yes,4=working unknown,5=working no,6=unregistered,7=no (failed)

 

int API_IsInCall() 

Return whether the sip stack is in call: 0=no,1=ringing,2=speaking

 

int API_GetCurrentConnectedCallCount() 

Get number of current connected calls

 

String API_GetRegFailReason(boolean extended)

Will return a text about the reason of the last failed registration. Set the extended parameter to true to get more details

 

String API_GetDiscReasonText()

Return the disconnect reason of the last disconnected call.

 

String API_GetGlobalStatus()

Returns SIP stack state/details.

 

int API_GetAccountRegState(String domain, String proxy, String username, String sipusername, boolean pushnotify, boolean strict)

Query account register state. Useful if you are using multiple accounts.

Returns -1: no such account register ep, 0: working, 1: success, 2: failed, 3: unregistered.

Parameters domain, proxy, username, sipusername will be used to match the account.

Always set the pushnotify to false.

If the strict parameter is false, then will check the best matching account after the passed parameters.

If the strict parameter is true, then will enforce exact parameter match when checking after the endpoints (server domain/username/etc).

 

String API_GetAccountRegStateString(String domain, String proxy, String username, String sipusername, boolean pushnotify, boolean strict)

Query account register state. Useful if you are using multiple accounts.

Return status text (for example "Registered" if the account is registered to the server).

Parameters domain, proxy, username, sipusername will be used to match the account.

Always set the pushnotify to false.

If the strict parameter is false, then will check the best matching account after the passed parameters.

If the strict parameter is true, then will enforce exact parameter match when checking after the endpoints (server domain/username/etc).

               

String API_GetCallerID(int line) 

Will return the remote party name

 

String API_GetIncomingDisplay(int line)

Get incoming caller id (might return two lines: caller id \n caller name)

 

String API_GetLastCallDetails()

Get details about the last finished call.

 

String API_GetProfileStatusText(String username)

Get the profile status text for the user.

Note: our profile status text can be set with the profilestatustext parameter.

This feature might be useful to implement a “My Profile” page in certain softphones.

 

String API_GetAddress() 

Return the local SIP listener address (IP:port)

 

String API_GetMySIPURI(boolean all)

Will return the SIP URI on which the current endpoint can be reached such as username@server.com or username@localip:port.

If all is true, then it will return all possible URI’s separated by comma.

 

boolean API_SetSSLContext(SSLContext sc)

Set the SSLContext java object to be used for new SIPS/TLS connections.

You might use this if you have some special requirements regarding the TLS connections to configure an SSLContext as you wish and pass it to JVoIP.

 

boolean API_ShowLog()

Show a new window with logs.

 

void API_AddLog(String msg)

Add a message to JVoIP log.

 

String API_HTTPGet(String url)

Send a HTTP GET request. Check if return string begins with “ERROR”.

 

boolean API_HTTPPost(String url, String data)

Send a HTTP POST request.

 

String API_HTTPReq(String url, String data)

Send a HTTP POST or GET request. (If data is empty, then GET will be sent).  Can be tunneled. Can block for up to 20 seconds.

 

boolean API_HTTPReqAsync(String url, String data)

Send a HTTP POST or GET request. (If data is empty, then GET will be sent).  Can be tunneled. The result will be returned in notifications with “ANSWER” header.

 

boolean API_SaveFile(String filename, String content)

Will save the text file to local disk JVoIP working directory in encrypted format (use API_SaveFileRaw to save as-is)

 

String API_LoadFile(String filename)

Load file from local disk.

 

boolean API_SaveFileRemote(String filename, String content)

Save file to remote storage (preconfigured ftp or http server )

 

boolean API_LoadFileRemote(String filename)

Load file from remote storage.  The download process is performed asynchronously. You need to call this function only once and then a few seconds later call the API_LoadFile function with the same file name. It will contain “ERROR: reason” text if the download failed.

 

String API_LoadFileRemoteSync(String filename)

Will download the specified file from remote storage synchronously (will block until done or fails).

 

String API_GetBlacklist()

Get blacklist.

 

boolean API_SetBlacklist(String str)

Set whole blacklist (users/numbers separated by comma)

 

boolean API_AddToBlacklist(String str)

Add to blacklist

 

boolean API_ClearCredentials()

Clear existing user account details.

 

boolean API_DelSettings (int level)

Delete settings and data. Levels: 0: nothing, 1: settings, 2: everything

 

int API_IsEncrypted ()

Returns whether the connection is encrypted. -1: unknown, 0=no,1=partially/weak yes,2=yes,3=always strong

 

String API_GetBindir()

Returns the application path (folder with the app binaries or app home folder)

 

String API_GetWorkdir()

Returns the application working directory (data folder, usually the “mwphonedata” subfolder or other location if no write access here).

 

String API_GetAltWorkdir()

Returns the application alternative working directory (such as folder on external SD card).

 

int API_ShouldReset()

Check if the sipstack should be restarted. Usually this is required only on local network change (such as IP change or changing from mobile data to wifi).

Possible return values: 0=no,1=not registered for a while,2=network changed

 

boolean API_ShouldResetBeforeCall()

This function might be called before calls and you should quickly restart the sipstack if returns true (the continue to make the call).

 

boolean API_RecFiles_Del()

Delete local recorded files.

 

boolean API_ReStart()

Restart the SIP stack.

 

boolean API_GetDeviceID()

Returns an unique device ID.

 

 

 

 

Notifications

Notifications means events received from the SIP library.

For maximum flexibility, the JVoIP SIP library implements multiple ways to receive the SIP notifications

·         polling with API_GetNotifications or API_GetNotificationsSync (preferred method when used as a Java library as described here)

·         webhonetojs (useful only if you use the library as an applet from JavaScript as described here)

·         socket (notifications sent via UDP or TCP if you use the library via socket as described here)

 

You will have to parse the received strings from your code by first splitting them by line, since more than one line can be received at once (separated by CRLF or with “,NEOL \r\n “, each line represents a new notification). The most important notification is the STATUS message which can be used to learn the SIP stack state (global state or per line state).

Notifications might be prefixed with the “WPNOTIFICATION,” string (you should remove this before parsing the rest of the line).

The parameters are separated by comma ‘,’. First you have to check the first parameter (until the first comma) to determine the event type. Then you have to check for the other parameters according to the specification below.

A code example can be found here.

The easiest way to get started is to just log out all messages at first and from there the usage should be more obvious.

 

Line parameter:

Most of the messages contains a line parameter which is set to -1 for the global state or 0,1,2,3… for the individual lines. For this reason you might see duplicated notifications: one sent for the global state, another sent for the actual line state.

For you wish to implement something basic, then it is enough of you check the notifications only for the global state and ignore the line states.

If you wish to handle multi-lines explicitly then you should check also the state of the individual lines (you might ignore the notifications about global state in this case).

 

The following notification messages are defined:

 

STATUS,line,statustext,peername,localname,endpointtype

You will receive STATUS notifications when the SIP session state is changed (SIP session state machine changes) or periodically even if there was no any change.

A typical status strings looks like this:

STATUS,line,statustext,peername,localname,endpointtype,peerdisplayname,[callid],online,registered,incall,mute,hold,encrypted,video,group, rtpsent,rtprec,rtploss,rtplosspercet,serverstats

 

The line parameter can be -1 for general status or a positive value for the different lines.

General status means the status for the “best” endpoint.

This means that you will usually see the same status twice (or more). Once for general sip client status and once for line status.

For example you can receive the following two messages consecutively: STATUS,-1,Connected,…

You might decide to parse only general status messages (where the line is -1), messages for specific line (where line is zero or positive) or both.

 

Status notifications are sent on state change but might be sent also at a regular interval (so you can might see the same notification again and again even if there was no state change –except the one-time events for individual endpoints marked with bold below).

If the “jsscripstats” is on (set to a value higher than 0) then you will receive periodic status messages during calls (might be useful if you are interested in RTP statistics during a call).

 

The following statustext values are defined for general status (with line set to -1):

o    Starting...

o    Idle.

o    Ready

o    Connecting…

o    Securing…

o    Register…

o    Registering… (or “Register...”)

o    Register Failed

o    No network

o    Server address unreachable

o    Not Registered

o    Registered (or “Registered.”)

o    Unregistered

o    Accept

o    Starting Call

o    Call

o    Call Initiated

o    Calling…

o    Ringing…

o    Incoming…

o    In Call (xxx sec)

o    Hangup

o    Call Finished           

o    Chat (or Messaging)

 

Note: general status means the “best” status among all lines. For example if one line is speaking, then the general status will be “In Call”.

 

The following statustext values are defined for individual lines (line set to a positive value representing the call channel number starting with 1):

o    Unknown  (you should not receive this)

o    Init  (voip library started)

o    Ready  (sip stack started)

o    Outband  (notify/options/etc. you should skip this)

o    Register  (from register endpoints)  (or “Register…” or “Registering...”)

o    Unregister

o    Subscribe  (presence)

o    Chat  (IM)

o    CallSetup  (one-time event: call begin)

o    Setup  (call init)     

o    InProgress  (call init)

o    Routed  (call init)

o    Ringing  (SIP 180 received or similar)

o    CallConnect (one-time event: call was just connected)

o    InCall (call is connected)

o    Muted  (connected call in muted status)

o    Hold  (connected call in audio hold status)

o    Speaking  (call is connected)

o    Midcall  (might be received for transfer, conference, etc. you should treat it like the Speaking status)

o    CallDisconnect  (one-time event: call was just disconnected)

o    Finishing  (call is about to be finished. Disconnect message sent: BYE, CANCEL or 400-600 code)

o    Finished  (call is finished. ACK or 200 OK was received or timeout)

o    Deletable  (endpoint is about to be destroyed. You should skip this)

o    Error  (you should not receive this)

 

You will usually have to display the call status for the user, and when a call arrives you might have to display an accept/reject button.

For simplified call management, you might check only the global state or you can just check for the one-time events (CallSetup, CallConnect, CallDisconnect). These are sent only for the actual line (1,2,etc) and not as global state (-1).

Not all call statuses might be sent (for example the Finishing state can be often skipped and you will receive only the Finished state after a call disconnect).

               

Peername: the other party username (if any)

Localname: the local user name (or username).

Endpointtype: 1 means out, 2 means in (1 for sessions initiated by JVoIP such as outbound calls where JVoIP acts as a client and 2 for inbound sessions such as incoming calls when JVoIP acts as a server endpoint)

Peerdisplayname: the other party display name if any

CallID: SIP session id (SIP call-id)

Online: network status. 0 if no network or internet connection, 1 if connectivity detected (always the global status)

Registered: registration state.  0=unknown,1=not needed,2=yes,3=working yes,4=working unknown,5=working no,6=unregistered, 7+ =no (failed) (always the global status)

InCall: phone/line is in call. 0=no,1=setup or ringing,2=speaking

Mute: is muted status. 0=no,1=undefined,2=playback muted,3=recording muted,4=both muted (or if you wish to simplify: 0 means no, others means yes)

Hold: is on hold status: 0=no,1= undefined,2=sendonly,3= recvonly,4=both in hold  (or if you wish to simplify: 0 means no, others means yes)

Encrypted: encryption status: -1: unknown, 0=no,1=partially/weak yes,2=yes,3=always strong  (or if you wish to simplify: 0 and -1 means no, others means yes)

Video: 0: no, 1: video call, 2: video offer received from peer, 3: video RTP stream constructed, 4: player/recorder started, 5: streaming

Group: group string for group chat and conference calls (members separated by | )

RTPSent: number of sent RTP packets (only if endpoint is in call)

RTPRec: number of received RTP packets (only if endpoint is in call)

RTPLoss: number of lost RTP packets (only if endpoint is in call)

RTPLossPercent: percent of the lost RTP packets (only if endpoint is in call)

VideoHold: is video on hold status: 0=no,1= undefined,2=sendonly,3=recvonly,4=both in hold  (or if you wish to simplify: 0 means no, others means yes)

RTPVideoSent: number of sent video RTP packets (only if endpoint is in call)

RTPVideoRec: number of received video RTP packets (only if endpoint is in call)

ServerStat: RTP statistics received from the server, if any (only if endpoint is in call)

 

For example the following status means that there is an incoming call ringing from 2222 on the first line:

STATUS,1,Ringing,2222,1111,2,Katie,[callid]

The following status means an outgoing call in progress to 2222 on the second line:

STATUS,2,Speaking,2222,1111,1,,[callid]

The following status means that the call was disconnected:

STATUS,2,Finished,2222,1111,1,,[callid]

To display the “global” phone status, you will have to do the followings:

1.        Parse the received string (parameters separated by comma)

2.        If the first parameter is “STATUS” then continue

3.        Check the second parameter. It “-1” continue otherwise nothing to do

4.        Display the third parameter (Set the caption of a custom control)

5.        Depending on the status, you might need to do some other action. For example display your “Hangup” button if the status is between “Setup” and “Finishing” or popup a new window on “Ringing” status if the endpointtype is “2” (for incoming calls only; not for outgoing)

 

PRESENCE,peername,state,details,displayname,email

This notification is received for presence changes (peers online status).

 

Line: used phone line

Peername: username of the peer

State and details: presence status string; one of the followings:   CallMe,Available,Open,Pending,Other,CallForward,Speaking,Busy,Idle,DoNotDisturb,DND,Unknown,Away,Offline,Closed,Close,Unreacheable, Unregistered,Invisible,Exists,NotExists,Unknown,Not Set

Displayname: peer full name (it can be empty)

Email: peer email address (it can be empty)

 

Notes for the state and details fields:

One of these fields might be empty in some circumstances and might not be a string in the above list (especially the details).

The details field will provide a more exact description (for example “Unreachable”) while the state field will provide a more exact one (for example “Close”). For this reason if you have a presence control to be changed, check the details string first and if you can’t recognize its content, then check the state string. For displaying the state as text, you should display the details field (and display the state field only if the details string is empty).

 

BLF,peerusername,direction,state,callid

This notification is received for incoming BLF messages.

Described in the BLF section above.

 

DTMF,line,msg

Incoming DTMF notification.

Msg is a string parameter representing the incoming DTMF digit. Usually one of the followings:  0123456789*#ABCDF

Supported receive dtmf methods are SIP INFO in SIP signaling and RFC 2833 in RTP.

Example: DTMF,1,7                 (dtmf digit”7” received on first line)

 

INFO,type,line,peername,text

Notifications about incoming/outgoing INFO or DTMF messages.

 

Note: for incoming DTMF you should watch for the above described DTMF notification instead of this! DTMF notification will be triggered even if the message was received with SIP INFO.

 

Parameters:

Type: The possible values for the type parameter is the following:

ERROR: Outgoing DTMF (API_Dtmf) or INFO (API_Info) message failed

WARNING: Outgoing DTMF failover from SIP INFO to RFC 2833 or In-Band on answer timeout or error response

OK: Outgoing DTMF (API_Dtmf) or INFO (API_Info) was sent successfully

REC: Incoming INFO message receive. Note that if the incoming message is a dtmf digit, then a DTMF notification will be triggered instead of INFO

Line:        Phone line

Peername: Other party username

Text:        INFO message body when type is REC or any additional info if type us ERROR, WARNING or OK.

 

Examples:

INFO,ERROR,1,1111,timeout   (on API_Dtmf or API_Info message send failed to 1111 on line 1)

INFO,WARNING,1,1111,failback to rfc2833             (on API_Dtmf failback from INFO to rfc2833 or in-band)

INFO,OK,1,1111        (on API_Dtmf or API_Info message sent successfully to 1111 on line 1)

INFO,REC,1,1111,hello             (on SIP INFO message received from 1111 which is not DTMF)

 

Note:

                When sending DTMF in RTP (inband or rfc2833) then it is not possible to get feedback whether the message was actually delivered. In this case you will receive an INFO,OK when the message send was initiated successfully. Otherwise if SIP INFO is used, then you will receive INFO,OK only on 2xx answer from the server or the other peer.

 

 

 

USSD,line,status,text

This notification is received about incoming USSD messages or report about success/failure about the outgoing USSD messages sent by API_SendUSSD.

Line: the session line

status: 0: send failed, 1: send succeeded, 2: received

text: text is the received USDD string (if status is 2) otherwise it might contain an error (if status is 0)

 

More details here.

 

CHAT,line,peername,text

This notification is received for incoming chat messages.

Line: used phone line

Peername: username of the peer

Text: the chat message body

Note:

·          The chat actually could be an incoming SMS message (for example a 3GPP SMS payload)

·          If the text begins with “_BASE64_” then you must base64 decode the rest of the string before presenting it to the user.

·          If the text begins with “GROUP: “ then it is a group chat. Example: “GROUP: Katie,John: hi”. In this case you might remove the header (until the second colon) and display the message in a separate thread. If the grouop name is „null” then the message doesn’t belong to any group conversation. If group is not set, then it means that the remote peer doesn’t have group chat capabilities and you might lookup the group where the incoming message it belongs.

You can ignore these if you are not using such features.

·          If the text begins with “MULTIPART: “ then it is a multi-part 3gpp concatenated message. Example: “MULTIPART: 1/2: hi”. The first number is the current fragment number, the second number is the total fragments. This is set only if the ims3gpp_sms_multipart parameter is set to 1.

You can ignore these if you are not using such features.

·          If you set the nitifychatid parameter to 1, then there will be also a message id parameter (user supplied msgid, 3gpp message reference or generated id) and the notification will look like: CHAT,line, id, peername, text

 

CHATREPORT,line,peername,status,statustext,group,md5,id

Chat transmission status report so you can process if outgoing message sent with the API_SendChat was delivered successfully or failed.

Line: used phone line

Peername: username of the peer

Status: 0 means chat send initialized, 1 means sending in progress, 2 means successfully sent, 3 means failed, 4 means queued for later send

Statustext: status text if any (such as delivery error reason if status is 3)

Group: optional parameter for group chat (member names separated by | )

MD5: the MD5 checksum of the message text

Id: message ID (user supplied msgid, 3gpp message reference or generated id)

 

Note:

                This notification is sent also for SMS messages.

                If the offline messaging is not disabled (offlinechat parameter is not set to 0) then JVoIP can retry later (on next start and/or when any SIP request is received from the target user) reporting status 4 instead of 3 on failed delivery. The MD5 checksum in this case will be calculated from concatenated pending message text and not for the last message.

               

CHATCOMPOSING,line,peername,status

Chat “is composing” notifications.

Line: used phone line

Peername: username of the peer

Status: 1 means other party is typing, 2 means other party is idle or stopped typing

 

CDR,line, peername,caller, called,peeraddress,connecttime,duration,discparty,reasontext

After each call, you will receive a CDR (call detail record) with the following parameters:

Line: used phone line

Peername: other party username, phone number or SIP URI

Caller: the caller party name (our username in case when we are initiated the call, otherwise the remote username, displayname, phone number or URI)

Called: called party name (our username in case when we are receiving the call, otherwise the remote username, phone number or URI)

Peeraddress: other endpoint address (usually the VoIP server IP or domain name)

Connecttime: milliseconds elapsed between call initiation and call connect

Duration: milliseconds elapsed between call connect and hangup (0 for not connected calls. Divide by 1000 to obtain seconds.)

Discparty: the party which was initiated the disconnect: 0=not set, 1=local JVoIP, 2=peer, 3=undefined/timeout

Disconnect reason: a text about the reason of the call disconnect (SIP disconnect code, CANCEL, BYE or some other error text)

 

START,what

This message is sent immediately after startup (so from here you can also know that the SIP engine was started successfully).

The what parameter can have the following values:

“api”  -api is ready to use

“sip” –sipstack was started

 

STOP,api

This message is sent when the SIP stack is terminated/destroyed.

 

SHOULDRESET,reason text

You should restart JVoIP (or reinit the library) when you receive this notification.

This is usually sent when network was changed (connection type, IP address), thus it might be best to reinitialize the whole SIP stack to recalculate the optimized environment variables and perform the auto network discovery process again (such as STUN lookup, but there are many others).
The message is not sent while in call.

 

LINE,number

This message is sent when the active line is changed.

 

EVENT,TYPE,txt

Important events which should be displayed for the user.

The following TYPE are defined: EVENT, WARNING, ERROR

This means that you might receive messages like this:

WPNOTIFICATION,EVENT,EVENT,any text NEOL \r\n

 

These messages will be received only if you set the “events” parameter to 2 or higher and it also depends on the loglevel.

 

GROUP,line,peers

Sent for conference calls. You might update the displayed peer name with the peers strings received here.

The peers parameter is the list of members separated by |. For example: Kate | John | Linda

 

VREC,line,stage,type,path,reason,source

Voice upload status (for voice recording / call recording).

line: channel number (note: with stage 3 and 4 it will always report -1 or -2 means default/not specified)

stage: 0:disabled, 1:call record begin,2:save begin, 3: save success, 4: save fail (note: stage 0 might not be reported)

type: upload method: 0: unknown, 1: local file, 2: ftp, 3: http, 4: server, 5: siprec

path: upload path/file  (note: if stage is 1 then type and path is not reported yet)

reason: failure reason (if stage is 4)

source: USER, SIPREC or AUTO (who initiated the recording)

 

PLAYREADY,line,callid

Audio streaming finished (initiated by API_PlaySound to remote peer).

Note: this notification is not sent with call disconnect (call disconnect will always terminate the audio streaming).

 

POPUP,txt

Should be displayed for the users in some way (hint/toast).

 

LOG,TYPE,txt

Detailed logs (may include SIP signaling).

The following TYPE are defined: EVENT, WARNING, ERROR, CRITICAL

 

These messages will be received only if you set the “events” parameter to 3 and also depends on the loglevel.

 

VAD,parameters

Voice activity.

This is sent in around every 3000 milliseconds (3 seconds) by default (configurable with the vadstat_ival parameter in milliseconds) if you set the “vadstat” parameter to 3 or 4 it can be requested by API_VAD. Also make sure that the “vad” parameter is set to at least “2”.

This notification can be used to detect speaking/silence or to display a visual voice activity indicator.

 

Format:

VAD,local_vad: ON local_avg: 0 local_max: 0 local_speaking: no remote_vad: ON remote_avg: 0 remote_max: 0 remote_speaking: no

 

Parameters:

local_vad: whether VAD is measured for microphone: ON or OFF

local_avg: average signal level from microphone

local_max: maximum signal level from microphone

local_speaking: local user speak detected: yes or no

 

remote_vad: whether VAD is measured from peer to speaker out: ON or OFF

remote_avg: average signal level from peer to speaker out

remote_max: maximum signal level from peer to speaker out

remote_speaking: peer user speak detected: yes or no

 

If the vadbyline parameter is set to 1 then individual lines will report in the following format:

VAD,line: X remote_vad: ON remote_avg: 0 remote_max: 0 remote_speaking: no

 

More details here.

 

RTPE,line,profile,extension

Reports about RTP extra header changes.

This is sent only if there RTP header extensions are received and the rtpextraheadernotify parameter is set to 1.

Parameters:

line: the session endpoint line number

profile: identifier or parameter extracted from the first two byte of the extension header

extension: 32 bit words as int converted to string. If there are more then one then separated by semicolon (;)

Example: RTPE,1,1,98;76543

See the RTP header extension FAQ point for more details.

 

RTPSTAT,quality,sent,rec,issues,loss

Media quality reports.

Can be enabled by the rtpstat parameter.

The parameters are calculated since the last RTPSTAT notification (for the past x seconds).

 

Parameters:

·         Quality: quality points between 0 and 5. The calculations considers many factors such as RTP issues, RTCP reports, codec problems, packet loss, packet delay, jitter and processing delay.

The following values are defined:

o    0: no audio or non-recognizable voice

o    1: very bad quality

o    2: bad quality

o    3: medium quality

o    4: good quality

o    5: excellent quality

·         Sent: RTP packets sent

·         Rec: RTP packets received and played

·         Issues: number of issues (any issues are counted, such as sequence number mismatch or packet drop)

·         Loss: lost packets

 

More details here.

 

LOG,RTP,txt

RTP details at the end of the call.

Example: RTP: sent 15695 lasts: 0 (p2p: 0 sdp: 0 rrp: 15695 tnl: 15701), rec: 17281 lastr: 0, loss: 201 1%, vsent: 0/0, vrecv: 0/0, cpu: 0.0%, cpurel: 0.0% (0.0),  srvsent: 10326 srvrec: 10302 srvloss: 10 0%

 

Other notifications

 

Format: messageheader, messagetext. The followings are defined:

CREDIT” messages are received with the user balance status if the server is sending such messages.

RATING” messages are received on call setup with the current call cost (tariff) or maximum call duration if the server is sending such messages.

MWI” messages are received on new voicemail notifications if you have enabled voicemail and there are pending new messages

SERVERCONTACTS” contact found at local VoIP server

NEWUSER” new user request

ANSWER” answer for previous request (usually http requests)

 

Example session

 

Here is how the notifications looks like in a typical session (start, register, make a call, hangup, terminate):

 

WPNOTIFICATION,START,api,NEOL

WPNOTIFICATION,START,sip,NEOL

WPNOTIFICATION,STATUS,-1,Initialized,NEOL

WPNOTIFICATION,STATUS,-1,Register...,NEOL

WPNOTIFICATION,EVENT,EVENT,Connecting...,NEOL

WPNOTIFICATION,STATUS,-1,Registering...,NEOL

WPNOTIFICATION,STATUS,0,Registering,istvantest2,istvantest2,1,voip.mizu-voip.com,[2e1123294504249584311k49333rmwp],,1,4,0,0,0,0,0,NEOL

WPNOTIFICATION,CREDIT,Credit: 4.2 USD,NEOL

WPNOTIFICATION,STATUS,-1,Registered.,NEOL

WPNOTIFICATION,EVENT,EVENT,Authenticated successfully. [ep: 0 2e1123294504249584311k49333rmwp Registering 12538],NEOL

WPNOTIFICATION,STATUS,0,Registered,istvantest2,istvantest2,1,voip.mizu-voip.com,[2e1123294504249584311k49333rmwp],,1,2,0,0,0,0,0,NEOL

WPNOTIFICATION,STATUS,-1,Starting call to testivr3,NEOL

WPNOTIFICATION,EVENT,EVENT,call [wpmain],NEOL

WPNOTIFICATION,STATUS,-1,Call,NEOL

WPNOTIFICATION,STATUS,-1,Call Initiated,NEOL

WPNOTIFICATION,STATUS,1,CallSetup,testivr3,istvantest2,1,testivr3,0,0,0,100,,[6e4351661777543861707k49334rmwp],1,2,1,0,0,0,0,NEOL

WPNOTIFICATION,STATUS,1,Routed,testivr3,istvantest2,1,testivr3,[6e4351661777543861707k49334rmwp],,1,2,1,0,0,0,0,NEOL

WPNOTIFICATION,STATUS,1,InProgress,testivr3,istvantest2,1,testivr3,[6e4351661777543861707k49334rmwp],,1,2,1,0,0,0,0,NEOL

WPNOTIFICATION,STATUS,-1,Calling...,NEOL

WPNOTIFICATION,STATUS,1,Ringing,testivr3,istvantest2,1,testivr3,[6e4351661777543861707k49334rmwp],,1,2,1,0,0,0,0,NEOL

WPNOTIFICATION,STATUS,-1,Ringing...,NEOL

WPNOTIFICATION,STATUS,1,CallConnect,testivr3,istvantest2,1,testivr3,0,0,0,100,,[6e4351661777543861707k49334rmwp],1,2,2,0,0,0,0,NEOL

WPNOTIFICATION,STATUS,1,Speaking,testivr3,istvantest2,1,testivr3,[6e4351661777543861707k49334rmwp],,1,2,2,0,0,0,0,NEOL

WPNOTIFICATION,STATUS,-1,Speaking (0 sec),NEOL

WPNOTIFICATION,STATUS,-1,Hangup,NEOL

WPNOTIFICATION,STATUS,-1,Speaking (2 sec),NEOL

WPNOTIFICATION,EVENT,EVENT,hangup [wpmain],NEOL

WPNOTIFICATION,STATUS,1,CallDisconnect,testivr3,istvantest2,1,testivr3,98,98,0,100,,[6e4351661777543861707k49334rmwp],1,2,0,0,0,0,0,NEOL

WPNOTIFICATION,STATUS,-1,Call Finished,NEOL

WPNOTIFICATION,CDR,1,testivr3,istvantest2,testivr3,voip.mizu-voip.com,1499,1969,1,User Hung Up (exD),[6e4351661777543861707k49334rmwp],NEOL

WPNOTIFICATION,STATUS,1,Finishing,testivr3,istvantest2,1,testivr3,[6e4351661777543861707k49334rmwp],,1,2,0,0,0,0,0,NEOL

WPNOTIFICATION,EVENT,EVENT,Call duration: 2 sec [ep: 1 6e4351661777543861707k49334rmwp Finishing 12538],NEOL

WPNOTIFICATION,STATUS,1,Finished,testivr3,istvantest2,1,testivr3,[6e4351661777543861707k49334rmwp],,1,2,0,0,0,0,0,NEOL

WPNOTIFICATION,STATUS,-1,Registered.,NEOL

WPNOTIFICATION,STOP,api,NEOL

 

Parse notifications code example

 

Below is a short code snippet demonstrating basic notification parsing.

Notifications handling is all about a bit of string parsing so maybe better if you just implement it from scratch so you will be more familiar with your own logic then the string handling practices in this example code.

In this example we assume that we receive the notifications in a function called ProcessNotifications.

 

public void ProcessNotifications(String receivednot)
{
   
if (receivednot == null || receivednot.length() < 1) return;

   
// we can receive multiple notifications at once, so we split them by CRLF or with ",NEOL \r\n" and we end up with a String array of notifications
   
String[] notarray = receivednot.split(",NEOL \n");
   
for (int i = 0; i < notarray.length; i++)
    {
        String notifywordcontent = notarray[i];
       
if (notifywordcontent == null || notifywordcontent.length() < 1) continue;
        notifywordcontent = notifywordcontent.trim();
        notifywordcontent = notifywordcontent.replace(
"WPNOTIFICATION,", "");

       
// now we have a single notification in the "notifywordcontent" String variable
       
Log.v("JVOIP", "Received Notification: " + notifywordcontent);

       
int pos = 0;
        String notifyword1 =
""; // will hold the notification type
       
String notifyword2 = ""; // will hold the second most important String in the STATUS notifications, which is the third parameter, right after the "line' parameter

        // First we are checking the first parameter (until the first comma) to determine the event type.
        // Then we will check for the other parameters.
       
pos = notifywordcontent.indexOf(",");
       
if(pos > 0)
        {
            notifyword1 = notifywordcontent.substring(
0, pos).trim();
            notifywordcontent = notifywordcontent.substring(pos+
1, notifywordcontent.length()).trim();
        }
       
else
       
{
            notifyword1 =
"EVENT";
        }

       
// Notification type, "notifyword1" can have many values, but the most important ones are the STATUS types.

        // After each call, you will receive a CDR (call detail record). We can parse this to get valuable information about the latest call.
        // CDR,line, peername,caller, called,peeraddress,connecttime,duration,discparty,reasontext
        // Example: CDR,1, 112233, 445566, 112233, voip.mizu-voip.com, 5884, 1429, 2, bye received
       
if (notifyword1.equals("CDR"))
        {
            String[] cdrParams = notifywordcontent.split(
",");
            String line = cdrParams[
0];
            String peername = cdrParams[
1];
            String caller = cdrParams[
2];
            String called = cdrParams[
3];
            String peeraddress = cdrParams[
4];
            String connecttime = cdrParams[
5];
            String duration = cdrParams[
6];
            String discparty = cdrParams[
7];
            String reasontext = cdrParams[
8];
        }
        
// lets parse a few STATUS notifications
       
else if(notifyword1.equals("STATUS"))
        {
    //ignore line number. we are not handling it for now
   
pos = notifywordcontent.indexOf(",");
   
if(pos > 0) notifywordcontent = notifywordcontent.substring(pos+1, notifywordcontent.length()).trim();

    pos = notifywordcontent.indexOf(
",");
   
if(pos > 0)
    {
          notifyword2 = notifywordcontent.substring(
0, pos).trim();
          notifywordcontent = notifywordcontent.substring(pos+
1, notifywordcontent.length()).trim();
    }
   
else
   
{
          notifyword2 = notifywordcontent;
    }

           
if (notifyword2.equals("Registered."))
            {
               
// means the SDK is successfully registered to the specified VoIP server
           
}
           
else if (notifyword2.equals("CallSetup"))
            {
               
// a call is in the setup stage
           
}
            else if (notifyword2.equals("Ringing"))
            {
               
// check the other parameters to see if it an incoming call and display an alert for the user
            }
           
else if (notifyword2.equals("CallConnect"))
            {
               
// call was just connected
           
}
           
else if (notifyword2.equals("CallDisconnect"))
            {
               
// call was just disconnected
           
}
           
else if (notifyword1.equals("CHAT"))
            {
               
// we received an incoming chat message (parse the other parameters to get the sender name and the text to be displayed)            }
        }
       
else if(notifyword1.equals("ERROR"))
        {
           
// we received an error notification; at least log it somewhere
           
Log.e("JVOIP", "ERROR," + notifywordcontent);
        }
       
else if(notifyword1.equals("WARNING"))
        {
           
// we received a warning notification; at least log it somewhere
           
Log.w("JVOIP", "WARNING," + notifywordcontent);
        }
         else if(notifyword1.equals("EVENT"))
        {
           
// display important event for the user
            Log.v(notifywordcontent);
        }

   
}
}

 

Parameters


Parameters can be specified in the following ways:

·         command line (when used as a standalone executable. Example: JVoIP.jar serveraddress=1.2.3.4 username=xxx password=xxx loglevel=5)

·         config file: wpcfg.ini file in ini file format

·         using the API_SetParameter function

·         SIP signaling (sent from server) with the x-mparam header (or x-mparamp if need to persist). Example: X-MParam: loglevel=5;aec=0

·         environment variable (prefix environment variables names with “wp_”. For example wp_username)

·         if used from a webpage:

applet parameters (by using the applet tag and set the parameters like: <param name = "parameter_name" value = "parameter_value">

webpage URL (the webhone will simply look at the embedding document/window url at startup. Prefix all parameter with “wp_”)

cookies (prefix cookie keys with “wp_”. For example wp_username)

skin config file: config.js  (if you are using our skin templates)

Any of these methods can be used or they can be even mixed.
All parameters can be passed as strings and will be converted to the proper type internally by the VoIP SDK.
Parameters can be also
encrypted.

For a basic usage you will have to set only your VoIP server ip or domain name (“serveraddress” parameter)
The rest of the parameters are optional and should be changed only if you have a good reason for it.

Note: once a parameter is set, it might be cached by JVoIP and used even if you remove it later. To prevent this, set the parameter to “DEF” or “NULL”. So instead of just deleting, set its value to “DEF” or “NULL”. “DEF” means that it will use the parameter default value if any. “NULL” means empty for strings, otherwise the parameter default value. Example: transport=DEF

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Main Parameters


The parameters can be used to control the most important settings and behavior like server domain, SIP authentication parameters, called party number and whether a call have to be started immediately as JVoIP starts or you let the user to enter these parameters manually.

serveraddress

(string)

The domain name or IP (IPv4 or IPv6 address of your SIP server. By default it uses the standard SIP port (5060). If you need to connect to other port, you can append the port after the address separated by colon.

Examples:

                mydomain.com”  -this will use the default SIP port: 5060

sip.mydomain.com:5062

10.20.30.40:5065

[ipv6]:port

Default value is empty.

 

If the server address is not set with this serveraddress parameter, then alternatively it can be set with the API_Register or API_Call functions (if domain part is passed).

If the serveraddress was not set, then you (or the endusers) will be able to make calls only by using full SIP URI and it is more difficult to accept incoming calls.

If set, then any username/phone number can be called what is accepted by the server (it is enough to pass the username part in this case, no need to specify the full SIP URI for calls).

As the SIP server you can use any softswitch, IP-PBX, SIP proxy server or SIP gateway (with or without registrar).

It might be possible that your service requires also SIP proxy configuration, which can be set with the proxyaddress parameter. Always specify the proxyaddress If you are using a logical non-resolvable SIP domain/realm as the serveraddress (for example with multi-tenant servers where the tenant name is not a resolvable domain name).

 

username

(string)

This is the SIP username (A number/Caller-ID for the outgoing calls). The JVoIP SIP endpoint will authenticate with this username on your SIP server.

Default value is empty.

 

Note:

You should set only the username part of your SIP account here, not the full SIP URI. For example if your account looks like abc@xyz.com, then you should set xyz.com as the serveraddress parameter and abc as the username parameter.

If you need a different name for SIP user name and Auth name (authorization name) then you might have to also use the sipusername parameter.

You might also specify the display name. More details here.

 

password

(string)

SIP authentication password.

If your server doesn’t require digest authentication or if you wish to make peer to peer calls then this parameter can be omitted.

This parameter can be set also in encrypted format or you can use the md5 parameter instead of the password. More details about the parameters encryption can be found here.

Default value is empty.

 

register

(int)

With this parameter you can set whether the SIP UA should register (connect) to the sip server at startup.

 

Possible values:

·         0: no

·         1: auto guess (yes if serveraddress/username/password is set, otherwise no)

·         2: yes

 

Default value is 1.

 

You might also use the API_Register function call to register (Set the register parameter to 0 and call API_Register later when you need it).

JVoIP will also reregister automatically based on the registerinterval parameter (there is no need to periodically call the API_Register).

 

 

 

 

 

 

 

 

Other Parameters


These parameters are more rarely used or should be used only if you have at least a minimal technical knowledge (VoIP and/or Java). You should modify only those parameters which you fully understand otherwise better if you leave all with the default values (the default values are already optimized for production).

autocall

(boolean)

If set to true then the VoIP SDK will immediately starts the call with the given parameters (for example with your page load). The serveraddress, username, password, callto must be also set for this to work.

Default value is false.

 

Usually when this parameter is true, then the “compact” parameter is also set true. Usually when this parameter is false, then the “compact” parameter is also set false.

 

callto

(string)

Can be any phone number/username that can be accepted by your server or a SIP URI. When “autocall” or “compact” is true, then this parameter should be filled properly. Otherwise it can be empty or omitted (the user will enter the number to call)

Default value is empty.

 

codebase

(string)

Applicable only if you use it as applet from browsers.
This optional attribute specifies the base URL of JVoIP--the directory that contains JVoIP code. If this attribute is not specified, then the document's URL is used (your html page URL).

Use it if you deploy JVoIP.jar in a different directory on your webserver (not the same directory as your webpage).

For the toolkit deployment use “JAVA_CODEBASE” instead of “codebase”.

Default is ‘.’ which means the same directory (the html document directory)

 

use_rport

(int)

Check rport in SIP signaling (requested and received from the SIP server by the VIA header)

0=don’t ask (rtport request will not be added to the VIA header)

1=use only for symmetric NAT (only when it is sure that the public address will be correct)

2=always (always request and use the returned value except if already on public ip)

3=request even on public IP (meaningless in most cases)

9=request with the signaling, but don’t use the returned value (good If you want to keep the local IP and for peer to peer calls)

Default is 1.

Change to 0, 2 or 9 only if you have NAT issues (depending on your server type and settings).

You might adjust also the use_fast_stun parameter if you change the use_rport.

More details can be found here.

 

upnpnat

(int)

Nat traversal via UPnP supported routers (IGD)

0: disable

1: enable

Default is 1

 

use_fast_ice

(int)

Fast ICE negotiations (for p2p rtp routing):

-1: suggest server side media routing (X-P2PM: 1)

0: no (set to 0 only if your server needs to always route the media)

1: auto

2: yes

3: always (not recommended)

Default is 1

 

Note:

If set to 1 or 2 then the stun should not be disabled.

If enabled, then the media might be negotiated directly between the endpoint (without the use of server suggestions in the SDP) and might be routed directly encrypted.

 

use_fast_stun

 (int)

Fast stun request on startup.

-1=force private address (if the client has both private and public IP, than the private IP will be sent in the signaling)

0=no

1=use only for stable symmetric NAT

2=use only if both tests match even if not symmetric (recommended)

3=use for symmetric NAT even if only one match

4=always

5=use even on public IP

 

Default is 2.

 

Change if you have NAT issues (depending on your server type and settings). You might adjust also the use_rport parameter  if use_fast_stun is changed.

If your router or NAT device often changes the external port binding then you might set it to 0 so JVoIP will use the private address to avoid any confusion on the SIP server (in this case you should also set the use_rport parameter to 9.

If your SIP server doesn’t have any NAT support, then you should set it to 3 or 4 and you might set also the use_rport parameter to 2.

More details can be found here.

 

udpconnect

(int)

Specify whether the UDP have to be connected before sending on the socket. (Some IP-PBX might require udp connect and in this way the VoIP SDK can always detect its local address correctly. However this should not be used whit multiple servers or separate domain and outbound proxy)

0=no

1=on init

2=on first send (not recommended. can block)

3=on both or any (not recommended)

Default value: 0

 

keepalivetype

(int)

NAT keep-alive packet type.

0=no keep-alive

1=space + CRLF (_\r\n)   (very efficient because low bandwidth and low server usage)

2=NOTIFY   (standard method)

3=CRLF (\r\n)   (very efficient because low bandwidth and low server usage. Not recommended)

4=CRLFCRLF (\r\n\r\n) (very efficient because low bandwidth and low server usage. After RFC draft)

 

Default is 4.

 

keepaliveival

(int)

NAT keep-alive packet send interval in milliseconds.

Keep-alive is a mechanism to keep the NAT open between register resends (so the server can initiate a new incoming transaction on the same stream with no issues, such as incoming call).

 

Possible values:

o    -1: auto (will default to around 28000 -28 sec- on UDP and 600000 – 10 min- on TCP)

o    0: disabled

o    other: interval in milliseconds (must be above 3000, otherwise treated as seconds)

 

Default value is -1.

 

registerinterval

(int)

Registration interval in seconds (used by the re-registration expires timer).

Default value is -1 (auto guess)

 

Valid range is -1 (auto) or between 10 (10 seconds) and 86400 (one day).

 

Notes:

o    Many servers will not accept values above 3600 (although the SIP stack can be auto adjust it based on server negotiation)

o    The actual resend of the REGISTER messages might be done at a shorter interval to cover any potential packet loss and network/server delays (usually in less than half interval, configurable also with the actualregisterexpires_val or actualregisterexpires_div settings)

o    When set to auto guess (-1), it will calculate an optimal interval depending on the circumstances such as network type, server load, transport method. It will result to around 90-180 under normal conditions on UDP.

o    If your softswitch supports keep-alive messages (to prevent NAT binding timeouts), then you might set to a longer interval (~3600 sec) to prevent high CPU usage on your server especially if you have many hundreds of SIP UA running at the same time.  If your server doesn’t support keep-alive, then you might set this to a lower value (between 30 and 90 sec. 60 sec is a good choice for most NAT devices and routers).  Note that usually this is not necessary because server side support is not needed to keep the NAT bindings.

o    If the register expire interval is not accepted by the server, then the SIP stack is capable to automatically negotiate a new value as directed by the server Min-Expire header or auto-guess.

 

needunregister

(boolean)

Set to false to prevent unregister messages to be sent by JVoIP (for example to prevent unregister on web page reload).

Default is true

 

contactaddressfailback

(int)

Specify if to try to reregister with another (better) local address if register fail or if previous (first) register went with a private address (and the server is on public IP).

Possible values:

·         -1: auto (same as 2 if server is on public IP and stun/rport are not disabled and server is not known NAT friendly; otherwise same as 1)

·         0: never

·         1: if failed (will try to reregister with other local address on register failure)

·         2: always (also try to reregister with public address when possible which helps for servers with poor NAT support)

Default: -1

 

Note:

With the unbindbeforereregister parameter you can also specify if to unbind (unregister) the previous (private) address before registering the new one.

This might be forced on servers with no or poor call fork support, otherwise most servers should be able to just replace the previous address without the need to unregister.

Possible values: -1: auto, 0: never, 1: always (default).

 

 

extraregisteraccounts

(string)

Use this setting for multi-account registration.

You can specify multiple SIP accounts in the following format:

IP,usr,pwd,t,proxy,realm,authuser;IP2,usr2,pwd2;IP3,usr3,pwd3, , ,realm3;IP4,usr4,pwd4…

where:

·         IP: is the SIP server address (domain or IP:port)

·         usr: is the SIP username

·         pwd: is the SIP password

·         t: is the register timeout in seconds (optional)

·         proxy: SIP proxy (optional)

·         realm: SIP realm (optional)

·         authusr: auth (sipusername if separate extension id and authorization username have to be used)

 

See the Multiple account registration FAQ for more details.

 

acceptsrvexpire

(int)

Accept the expires interval sent by the server.

0: no

1: yes (prioritize the contact expire)

2: yes (prioritize the global expire)

Default value is 1.



changesptoring

(int)

If to treat session progress (183) responses as ringing (180). This is useful because some IP-PBX never sends the ringing message, only a session progress and might start to send in-band ringing (or some announcement)

The following values are defined:

0: do nothing,

1: change status to ring

2: start local ring and be ready to accept media (which is usually a ringtone or announcement)

3: start media receive and playback (and media recording if the “earlymedia” parameter is set)

4: change status to ringing and start media receive and playback (and media recording if the “earlymedia” parameter is set to true)

Default value is 2.

 

*Note: on ringing status JVoIP is able to generate local ringtone. However this locally generated ringtone playback is stopped immediately when media is started to be received from the server (allowing the user to hear the server ringback tone or announcements)

 

allowcallredirect

(int)

Set to 1 to auto-redial on 301/302 call forward.

Set to 0 to disable auto call forward.

Default value is 1.

 

natopenpackets

(int)

Change this option only if you have RTP setup issues with your server(s).

UDP packets to send to open the NAT device and initiate the RTP.  Some servers will require at least 5 packets before starting to send the media after the 183 “session in progress” response. In this case set this value to 10 (In this way the server will receive at least 5 packets even on high packet loss networks)

0: no

1: write only an empty udp packet

2: write a normal RTP packet

3 or more: write this number of RTP packets

 

Default is 2

 

*Note: instead of sending more “fake” packets, you can set the “earlymedia” to 1 or more to begin the rtp stream immediately.

*Note: you can use the natopenpackettype parameter to specify the keep-alive RTP packet format:
             -1 means auto, 1 means short CRLFCRLF packet (default). 2 means full RTP packet with zeroed content, 3 means ED-137 keep-alive.

 

 

earlymedia

(int)

Start to send media when session progress is received.

0: no

1: reserved

2: auto (will early open audio if wideband is enabled to check if supported)

3: just early open the audio

4: null packets only when sdp received

5: yes when sdp received

6: always forced yes

Default is 2.

 

 

*Note: For the early media to work, JVoIP has to open the NAT when SDP is received. This can be done by sending a few fake rtp packets or by starting to send the media immediately when session in progress is received. The first method consume less bandwidth, but it is not supported by some softswitch.

 

answerwithallcodec

(int)

Set to 1 to answer with a list of supported codec’s in the SDP by the UAS.

0: no (negotiate one final codec)

1: yes (list all supported/negotiated codec’s in 200 answer)

2: all (list all supported codec’s in 200 answer even those not offered by the caller)

Default is 0.

 

 

setfinalcodec

(int)

JVoIP might negotiate the final codec for a session with the ACK message if your server send multiple codec’s in the 200 OK call connect answer.

Some server cannot handle the final codec offer in the ACK message correctly.

In this case you will have to set this setting to 0, otherwise you will have one way audio.

0=never (RFC compliant)

1=auto guess (not send in case of certain servers and autocorrect in subsequent calls)

2=when multiple codecs are received

3=always reply with the final codec in the ACK message

Default value is 1.

 

 

ims3gpp

(int)

Enable 3GPP (IMS/5G/VoLTE) features.

Possible values:
-1: auto detect (default)

0: disable

1: basic

2: full/all

 

It is also possible to enable/disable certain 3GPP features separately. In this case use the following parameters instead of ims3gpp:

o    ims3gpp_phonenum:  use tel URI and set user=phone (-1: auto, 0: no, 1: user=phone, 2: also tel uri). Note: you might also use the sipproto param

o    ims3gpp_minphonelen: tel uri only if phone number is longer then this. Default is 4. Set to 0 to use tel also for non-phone number peers

o    ims3gpp_authuname: auth username must contain the domain (-1: auto, 0: no. 1: yes)

o    ims3gpp_ussd: IMS USSD described at 3GPP TS 24.390. Send with API_SendUSSD, receive as USSD notifications (-1: auto, 0: no, 1: yes)

o    ims3gpp_sms: +g.3gpp.smsip with MESSAGE using binary encoded PDU’s described in 3GPP TS 24.011 (-1: auto, 0: no, 1: yes)

o    ims3gpp_smsc: SMSC Center Address number. Otherwise JVoIP might use the destination number (if that is a phone number)

 

enable_3pcc

(int)

Specify if to enable 3PCC Third Party Call Control as described at RFC 3725.

Note: 3PCC has nothing to do with 3GPP. They are completely different technologies.

This feature is often used in callcenters or for click-to-call to setup calls between two or more other parties.

Possible values:
0: disable (block 3PCC requests)

1: don't handle

2: accept (handle incoming requests)

3: initiate 3PCC calls by sending with no SDP

4: initiate 3PCC calls by sending SDP with connect IP set 0.0.0.0

5: initiate 3PCC calls by sending SDP with no media line

Default is 2.

 

If 3pcc is enabled, then JVoIP will send the codec answer in ACK if not received by INVITE or it will re-INVITE if received SDP with no media line or with 0.0.0.0 contact IP, thus allowing all the possible third party call controls.

Some more related information can be found here, here, here and here.

You might also set the enableautoaccept parameter to 3 if JVoIP acts as an auto-responder.

 

ed137

(int)

Enable/disable the ED-137 behavior to be used for air traffic management services.

Set to 0 to ignore the ED-137 specification (act as normally)

Set to 1 to turn on the ED-137. This will change a list of internal settings and behaviors to conform with the ED-137 specification.

Default value is 0.

See the ED-137 guide for more details.

 

backupserver

(string)

Specify secondary SIP server address for failover in case if you have multiple SIP servers.

You can specify domain, ip and if port is not 5060 then you must also specify the port like mybackupserver.com:7080.

You might also specify a backupserverdomain parameter (use IP in backupserver and domain name in backupserverdomain).

More details can be found here.

 

inet

(int)

Internet protocol (IP layer).

Specify if you wish to prefer IPv4 or IPv6.

Possible values:

-1: Auto

0: IPv4 only (disable IPv6)

1: IPv4 (parse also IPv6)

2: Both (prefer IPv4)

3: Both (no preference)

4: Both (prefer IPv6)

5: IPv6 only (disable IPv4)

 

Default is -1/Auto (auto guessed from configurations such as serveraddress and from the SIP signaling / SDP)

 

Other IP related parameters (all are set based on this inet parameter, but can be set also separately if you have some special requirement):
hasipv4 (true/false), hasipv6 (true/false), listenonipv6 (true/false), ipvdualstack (true/false), cropipv6scopeid (true/false), preferipv (-1: auto (def to 1), 0: no preference, 1: prefer ipv4, 2: prefer ipv6)

 

proxyaddress

(string)

Outbound proxy address (Examples: mydomain.com,  mydomain.com:5065, 10.20.30.40:5065)

Leave it empty if you don’t have a stateless proxy. (Use only the serveraddress parameter)

Default value is empty.

 

usehttpproxy

(int)

Used only for HTTP tunneling with Mizu VoIP servers.

0: no

1: same as sip proxy (proxyaddress)

2: system default

3: manual (must be set by the httpproxyurl parameter –deprecated after version 3.5)

4: auto

Default value is 4.

 

httpserveraddress

(string)

Useful when the transport parameter is set to 4 (auto) to specify the http tunneling gateway address.

Default value is null (address loaded from the “serveraddress” parameter)

 

transport

(int)

Transport protocol for the SIP signaling.

-1: Auto detect

0: UDP  (User Datagram Protocol. The most commonly used transport for SIP)

1: TCP (signaling via TCP. RTP will remain on UDP)

2: TLS (encrypted signaling -SIPS)

3: HTTP tunneling (both signaling and media. Supported only by mizu server or mizu tunnel)

4: HTTP proxy connect (requires tunnel gateway or server)

5: Auto (automatic failover from UDP to HTTP as needed if tunnel gateway or server is used)

Default is -1.

 

See the How to configure SIPS FAQ point for more details about TLS transport.

 

 

mediaencryption

(int)

Media encryption method for the RTP streams.

-1: auto guess (might use SRTP if TLS transport is set)

0: not encrypted

1: auto (will encrypt if initiated by other party)

2: SRTP (recommended for RTP encryption)

Default is -1.

 

Note:

To enable full encryption, set both the transport and the mediaencryption parameter to 2.

Mode details here.

 

strictsrtp

(int)

Media encryption method.

0: most compatible (skip SRTP auth failures)

1: default auto (will try to use SRTP with less constrains, might failback to RTP on error or if SRTP is not supported by the peer)

2: strict (might disconnect if peer is not respect the standard or on protocol error)

3: allow only strict SRTP call, otherwise disconnect

Default: 1

 

Note:

This parameter is considered only if the mediaencryption parameter is also set.

Mode details here.

 

 

srtp_suite

(string)

You might specify the preferred srtp suite.

Possible values:

AES_CM_128_HMAC_SHA1_80 (recommended)

AES_CM_128_HMAC_SHA1_32 (supported)

AES_CM_256_HMAC_SHA1_80 (beta / not tested)

AES_CM_256_HMAC_SHA1_32 (beta / not tested)

 

Default: AES_CM_128_HMAC_SHA1_80

 

JVoIP might be able to negotiate also other values as suggested by your server.

 

has_video

(boolean)

Enable/disable video features.

You must download the phone video package for this to work and read its documentation for more details. The video module is provided “as is”. Mizutech currently doesn’t provide direct technical support for this functionality.

 

dtmfmode

(int)

DTMF send method.

0=disabled

1=SIP INFO method (out-of-band in SIP signaling INFO messages)

2=auto (auto guess from peer advertised capabilities)

3=INFO + NTE

4=NTE (Named Telephone Events as specified in RFC 2833 and RFC 4733; DTMF in RTP headers)

5=In-Band (DTMF audio tones in the RTP stream)

6=INFO + InBand

 

Default is 2 (and you should change it only if you have a good reason to do so, since the auto-detect should work in all circumstances, except if your SIP server is sending bogus DTMF capabilities).

 

Note:

DTMF digits can be sent with the API_Dtmf or if you press a digit on the built-in user interface (if that is used).

When more than one method is used (dtmfmode 3 or 6), the receiver might receive duplicated dtmf digits.

If the message sending was initiated with SIP INFO, then it might failover to rfc2833 or inband if no answer or error code was received from server.

 

sendearlydtmf

(int)

Specify whether to allow sending DTMF digits before call connect

0=no

1=auto (yes if rfc2833 or inband is allowed and already sent/received rtp packets)

2=yes (always send)

 

Default: 1

 

offlinechat

Will try to resend not delivered messages later (on next register and/or when any message received from peer). The offline message queuing will take care of filtering out duplicates and will try to resend the message multiple times on failure until max number of resend or timeout reached.

(int)

-1=auto (usually yes, no for 3gpp sms)

0=no (disable offline chat)

1=yes (default)

2=force always

 

Default: -1

 

voicemail

(int)

Subscribe to voicemail notifications (MWI). Accepted values:

0=disabled

1=display voicemail only if NOTIFY is received automatically without subscription

2=auto-detect if voicemail SUBSCRIBE is needed

3=subscribe for voicemail messages after successful registration

4=subscribe for voicemail messages on startup

Default value is 2. You might set it to 3 if your server has support for MWI to be sure that JVoIP will check the voicemail in all circumstances.

 

voicemailnum

(String)

Specify the voicemail address. Most IP-PBX will automatically send the voicemail access number so you don’t need to set this parameter.

 

transfertype

(int)

-1=default transfer type (same as 6)

0=call transfer is disabled

1=transfer immediately and disconnect with the A user when the Transf button is pressed and the number entered (unattended transfer)

2=transfer the call only when the second party is disconnected (attended transfer)

3=transfer the call when JVoIP is disconnected from the second party (attended transfer)

4=transfer the call when any party is disconnected except when the original caller was initiated the disconnect (attended transfer)

5=transfer the call when JVoIP is disconnected from the second party. Put the caller on hold during the call transfer (standard attended transfer)

6=transfer the call immediately with hold and watch for notifications (unattended transfer)

7=transfer with no hold and no disconnect (simplest unattended transfer)

8=transfer with conference (will put the parties to conference on transfer; will mute or hold the old party by default)

 

Default is -1 (which is the same as 6)

 

Note:

·          Unattended means simple immediate transfer (just a REFER message sent)

·          Attended transfer means that there will be a consultation call first

·          The most popular transfertypes are 1, 5 and 6

·          If you have any incompatibility issue, then set to 7 (unattended is the simplest way to transfer a call and all sip server and device should support it correctly)

·          More details can be found here.

 

 

transfwithreplace

(int)

Specify if replace should be used with transfer so the old call (dialog) is not disconnected but just replaced.

This way the transferee party is never disconnected, just the called party is changed. The transferee party must be able to handle the replace header for this.

(Transferee party means the endpoint which received the REFER transfer request)

Possible values:

-1=auto

0=no

1=yes

Default is -1

 

allowreplace

(int)

Allow incoming replace requests.

0=no

1=yes and always disconnect old ep

2=yes and don't disconnect if in transfer

3=yes but never disconnect old ep

Default is 2.

 

discontransfer

(int)

Specify if line should disconnect after transfer if not determined by the other transfer related configurations.

-1=auto
0=never

1=on C party connected status

2=on timeout

3=on connected or timeout

4=on ok for refer

Default is -1 (disconnect if transfertype is 1)

disconincomingrefer

(int)

Specify if line should disconnect after incoming transfer.

-1=auto
0=no

1= yes

 

Default is -1

 

inversetransfer

(int)

Specify inverse attended transfer.

0: no. The REFER will be sent to the ep for which the API_Transfer was called.  This is the standard behavior.

1: yes. The REFER will be sent to the ep for which the API_Hangup was called. Might be used only if the original ep (for which the API_Transfer was called) doesn't support transfer (REFER sip message).

Default is 0 (standard transfer behavior)

 

 

transferdelay

(int)

Milliseconds to wait before sending REFER/INVITE while in transfer.
Default value is 400.

 

newdialogforrefer

(int)

Specify if the REFER have to be sent in a new dialog (for compatibility reasons).

0: no (after SIP standards)

1: yes, with no to tag
Default is 0

 

useserverdomainforrefer

(int)

Specify the domain part to be used in REFER for the Refer-To and Referred-By headers.

0: no (use default domains loaded from the dialog)

1: yes for Refer-To only

2: yes for Referred-By only

3: auto (usually yes for both)

4: force server domain for both

Default is 0.

 

Note: Servers should accept the domain from the dialog for the Refer-To and Referred-By headers after the SIP standards, however for some reasons a few popular server would reject the REFER request if they found some other domain (such as proxy server address) and thus this settings defaults to 3 for compatibility reasons.

 

 

checksubscriptionstate

(int)

Specify if to handle transfer subscription state (such as reload the call on transfer failure)

-1=auto
0=no

1= disconnect

2= reload

 

Default is -1

 

subscribefortransfer

(int)

Create subscribe dialog for call transfer.

-1=auto
0=never

1= if no notify received

2= always

 

Default is -1

 

enabledirectcalls

(int)

Specify whether to enable direct call to SIP URI  (peer to peer or via server)

0=no (so you should use only the username part of the SIP URI to make calls. set the domain part as the sipserveraddress parameter)

1=check IP in URI  (will recognize full SIP URI if the domain part can be resolved to a valid IP)

2=always check (so you can make calls to full SIP URI without a SIP server to be set)

3=crossdomain (so you can register to domain A and make direct call to domain B)

 

Default is 1

 

 

checksrvrecords

(int)

SRV DNS record lookup setting:

-1: auto (will check SRV record for the VoIP server, but remembers if fails and will not check again next time)

0: don’t lookup (will use only A record)

1: lookup A records first. If fails then lookup srv record (because mostly the srv record is not set anyway)     

2: lookup SRV records first for VoIP server address. If fails then lookup A record (RFC compliant)

3: always lookup SRV records first. If fails then lookup A records.

4: check also without the _sip._udp. prefix

If the SRV or A lookup returns multiple records, than SIP UA will failover to the next server on connection failures taking in consideration both record priority, weight and previous failures/successes.

Default value is -1.

 

 

dnslookup

(int)

Domain record lookup mode

0=auto (same as 2)

1=yes always re-query

2=use cache if needed (default)

3=use cache whenever possible

4=from cache only

5=disable

Default value is 0.

 

enableaudiostreams

(int)

You can disable audio playback and/or recording with this option

0=disable all

1=disable recording

2=disable playback

3=enable all

Default value is 3.

 

audiodevicein

(string)

Audio device name for recording (microphone). Set to a valid device name or “Default” which would select the system default audio device.

 

audiodeviceout

(string)

Audio device name for playback (speaker). Set to a valid device name or “Default” which would select the system default audio device.

 

audiodevicering

(string)

Audio device name for ringtone. Set to a valid device name or “Default” which would select the system default audio device. You can also set it to “All” to have the ringtone played on all devices.

 

playring

(int)

Generate ringtone for incoming and outgoing calls.

0=no (you can generate ringtone also by using the Java API to playback a sound file when you receive ringing notifications)

1=play ringtone for incoming calls

2=play ringtone for incoming and outgoing calls. (ringtone for outgoing calls can be generated also by your VoIP sever. When remote ringtone is received, java softphone will stop the local ringtone playback immediately and starts to play the received ringtone or announcement)

Default is 2.

 

Note: you might set the earlymedia parameter to 5 in case if you wish to hear ringtone or any announcement from your server before call connect.

 

ringtone

(string)

Specify a ringtone sound file to be used. (Only the file name, not the full path. Copy the file near JVoIP.jar). If not specified, then JVoIP will use its own built-in ringtone for call alert.

The file should be in the following format: PCM SIGNED 8000.0 Hz (8 kHz) 16 bit mono (2 bytes/frame) in little-endian (128 kbits).

You can use any sound editor to convert your file to this format (usually from File menu -> Save as).

 

Possible values:

·         Empty/default: will try to load the embedded ringtone or from the ring.wav near the app or in path

·         File name (for example “ring.wav”): will try to load the specified file from near the app or from the java path (and failover to embedded ring if not exists)

·         Full path (for example “C:\webphone\myring.wav”): will try to load the ringtone from the specified path first (and failover to embedded ring if not exists)

 

Default value is empty (which means that the default ringtone will be used).

 

If you need a different ringtone for outgoing call, it can be set with the ringtoneout parameter. If the ringtoneout parameter is also set, then the ringtone will be used for incoming calls and the ringtoneout will be used for outgoing calls.

 

 

ringincall

(int)

Ring while in call if incoming or outgoing call

0=No

1=Only a beep for incoming call

2=Yes, normal ring

Default value is 1

 

playdisc

(int)

Play a disconnect tone on call reject.

0=No

1=Auto (if there was no early media with possible disconnect reason announcement)

2=Always

3=Also for normal disconnect on connected call

Default value is 1

 

 

checkvolumesettings

(int)

Check if audio device is muted or volume settings are too low (and un-mute and/or increase volume if necessary).

0: no

1: at first run

2: always

Default value is 1

 

focusaudio

(int)

Specify whether to use audio “focus”. (Auto decrease the volume of other apps).

This will use VoIP optimizations on windows (WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE) and also will enable audio ducking (auto lowering the volume for other processes while JVoIP is in call).

 

Possible values:

0=auto (will default to yes on windows)

1=no

2=yes

Default value: 0

 

Note: This new setting will deprecate the old usecommdevice parameter, but usecommdevice can be still used as-is

 

 

volumein

(int)

Default microphone volume in percent from 0 to 100. 0 means muted. 100 means maximum volume, 0 is muted.

Default is 50% (not changed)

 

Note:

The result volume level might be affected by the AGC if it is enabled.

Volume levels above 70% might result in distorted sound.

You can also set/get the volume at runtime using the API_SetVolume/API_GetVolume functions.

You can also change the volume from OS system level volume controls.

 

 

volumeout

(int)

Default speaker volume in percent from 0 to 100. 0 means muted. 100 means maximum volume, 0 is muted.

Default is 50% (not changed)

 

Note:

The result volume level might be affected by the AGC if it is enabled.

Volume levels above 70% might result in distorted sound.

You can also set/get the volume at runtime using the API_SetVolume/API_GetVolume functions.

You can also change the volume from OS system level volume controls.

 

volumering

(int)

Default ringback volume in percent from 0 to 100. 0 means muted. 100 means maximum volume, 0 is muted.

Default is 50% (not changed)

 

Note:

Volume levels above 70% might result in distorted sound.

You can also set/get the volume at runtime using the API_SetVolume/API_GetVolume functions.

You can also change the volume from OS system level volume controls.

 

 

beeponconnect

(int)

Will play a short sound when calls are connected

0=Disabled

1=For auto accepted incoming calls

2=For incoming calls

3=For outgoing calls

4=For all calls

Default value is 0

 

 

agc

(int)

Automatic gain control.

0=Disabled

1=For recording only

2=Both for playback and recording

3=Guess

Default value is 3

 

This will also change the effect of the volumein and volumeout settings.

For the AGC to work the mediaench module must be also deployed. See the related FAQ section for more details.

Download: https://www.mizu-voip.com/Portals/0/Files/mediaench.zip

 

 

stereomode

(boolean)

Set to true for 2 audio channel or false for 1 (mono).

When stereo is set, the VoIP SDK will convert also mono sources to stereo output.

Default is false.

 

Note: many sound devices might convert mono sources to stereo by default

 

plc

(boolean)

Enable/disable packet loss concealment

Default is true (enabled)

 

vad

(int)

Enable/disable voice activity detection.

0: auto

1: no

2: yes for player (will help the jitter)

3: yes for recorder

4: yes for both

Default is 2.

 

Notes:

·         The vad parameter is automatically set to 4 by default if the aec2 algorithm is used.

·         If you wish to use VAD related statistics in your application, you might have to also set the vadstat parameter after your needs:
0=no,1=auto (default),2=detect no mic audio,3=send statistics, 4=send also when changed.  See the VAD notification and API_VAD for more details.

·         If you wish to force vad (usually not required), then you might set the forcevad parameter accordingly:
0: no (default), 1: force also if conference, 2: force also if rtp muted/holded, 3: force always

·         If you want to disable audio related notifications (microphone warning on no signal detected) then set the enablenomicvoicewarning parameter to 0

·         More details here

 

 

rtpstat

(int)

Enable/disable RTP statistics by triggering RTPSTAT notifications.

Possible values:

-1: auto (will trigger RTPSTAT events in every 6-7 seconds and more frequently at the beginning of the calls)

0: disabled

Positive value: seconds to generate RTPSTAT events.

 

Default is 0 (disabled)

More details here.

 

 

aec

(int)

Enable/disable acoustic echo cancellation

0=no

1=yes except if headset is guessed

2=yes if supported

3=forced yes even if not supported (might result in unexpected errors)

Default is 1.

 

For this AEC to work the mediaench module must be also deployed. See the related FAQ section for more details.

Download: https://www.mizu-voip.com/Portals/0/Files/mediaench.zip

Note: the aec decision might be overwritten by the aectype parameter.

 

 

aec2

(int)

Secondary AEC algorithm.

0=no

1=auto

2=yes

3: yes with extra (this might be too much under normal circumstances)

Default is 1

 

Note: the aec decision might be overwritten by the aectype parameter.

 

aectype

(string)

AEC algorithm(s) to use.

One or more of the following strings separated by comma.

auto: will select automatically based on circumstances (CPU power, device capabilities, network)

none: disable aec

software: software aec (requires extra CPU processing)

hardware: hardware aec capabilities (not supported on all platforms)

fast: a fast software aec implementation

volume: this will just decrease the volume when speech detected from other end (using VAD)

Default is auto.

 

Note:

It is recommended to leave both the aec and aectype values with its default values.

To force full echo cancellation in all circumstances you might set the aec to “2”, aec2 to 2 and the aectype to “software,hardware,fast”

To completely disable aec you might set the aec to “0”, aec2 to “0” and the aectype to “none” (for example when you know that you will have only one way audio such as IVR calls)

 

denoise

(int)

Noise suppression.

0=Disabled

1=For recording only

2=Both for playback and recording

3=Auto guess

Default value is 3

 

For this to work the mediaench module must be also deployed. See the related FAQ section for more details.

Download: https://www.mizu-voip.com/Portals/0/Files/mediaench.zip

 

 

silencesupress

(int)

Enable/disable silence suppression

Usually not recommended unless your bandwidth is really bad and expensive.

-1=auto

0=no (disabled)

1=yes

Default is -1  (which means no, except mobile devices with low bandwidth)

 

rtcp

(boolean)

Enable/disable rtcp. (RFC 3550. Partial support)

 

codec

(string)

List of allowed audio codec’s separated by comma.

Will accept one or more of the following strings (upper or lower case doesn’t matter):
pcmu, pcma, g711 (for both PCMU and PCMA), g729, gsm, ilbc, speex, speexwb, speexuwb, opus, opuswb, opusuwb, opusswb, g7221, g7221uwb, def

 

By default the SIP library will automatically choose the best codec depending on available codec’s, circumstances (network/device) and peer capabilities.

Set this parameter only if you have some special requirements such as forcing a specific codec, regardless of the circumstances.

Default: empty (which means auto detection and negotiation)

Recommended value: leave it empty for “best” codec negotiation unless if you have some specific requirement.

 

Example: OpusWB,G729,PCMU (This will disable Speex, GSM, iLBC, GSM and PCMA).

You can also set one single codec (if your server/peers allows only one codec or for testing to rule out all kind of codec negotiation related issues).

You can set to “def” to enable all the default codec’s again.

 

Under normal circumstances, the following is the built-in codec priority:

          I.            Wideband Speex and Opus (These are set with top priority as they have the best quality. Likely used for VoIP to VoIP calls if the peer also has support for wideband)

        II.            G.729 (Usually the preferred codec for VoIP trunks used for mobile/landline calls because it’s excellent compression/quality ratio for narrowband)

       III.            iLBC, GSM (If G.729 is not supported then these are good alternatives. iLBC has better characteristics and GSM is better supported by legacy hardware)

       IV.            G.711: PCMU and PCMA (Requires more bandwidth, but has the best narrowband quality)

 

Note: for the codec configuration, either use the codec/prefcodec settings OR the use_xxx settings (where xxx is the codec name). You can achieve the same result with both. The use_xxx settings are a little bit more flexible regarding the codec prioritization.

 

prefcodec

(int)

Set your preferred audio codec.

Will accept one the following strings (upper or lower case doesn’t matter):
pcmu, pcma, g711 (for both PCMU and PCMA), g729, gsm, ilbc, speex, speexwb, speexuwb, opus, opuswb, opusuwb, opusswb, g7221, g7221uwb

Default is empty which means the built-in optimal prioritization.

By default the SIP stack will present the codec list optimized regarding the circumstances (the combination of the followings):

·          available client codec set (not all engines supports all codecs)

·          server codec list (depending on your server, peer device or carrier)

·          internal/external call: for IP to IP calls will prioritize wideband codecs if possible, while for outbound calls usually G.729 will be selected if available

·          network quality (bandwidth, delay, packet-loss, jitter): for example iLBC is more tolerant to network problems if supported

·          device CPU: some old mobile devices might not be able to handle high-complexity codec’s such as opus or G.729.  G711 and GSM has low computational costs

You can also fine-tune the codec settings with the use_xxx settings described below.

 

 

use_gsm

(int)

GSM codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1.

 

use_ilbc

(int)

iLBC codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1.

 

Note: the ilbc mode defaults to 30 and will be negotiated automatically. You might change the default with the “ilbcmode” parameter to 20 or 30.

 

use_speex

(int)

Narrowband speex codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1

use_speexwb

(int)

Wideband speex codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 2

 

Note: to enable wideband in all circumstances, set the “disablewbforpstn” and “disablewbonmac” parameters to false.

 

use_speexuwb

(int)

Ultra wideband speex codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1

 

Note: to enable wideband in all circumstances, set the “disablewbforpstn” and “disablewbonmac” parameters to false.

 

use_opus

(int)

Narrowband (8000 Hz) opus codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1

 

Note: The opx dll/so/jnilib files have to be placed near the JVoIP.jar for the opus codec to work.

 

use_opuswb

(int)

Wideband (16000 Hz) opus codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 2

 

Note: to enable wideband in all circumstances, set the “disablewbforpstn” and “disablewbonmac” parameters to false. The opx dll/so/jnilib files have to be placed near the webhone.jar for the opus codec to work.

 

use_opusswb

(int)

Super wideband (24000 Hz) opus codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1

 

Note: this codec might not work on all devices, depending on the audio device and driver capabilities!

 

use_opusuwb

(int)

Ultra wideband (fullband at 48000 Hz) opus codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1

 

Note: to enable wideband in all circumstances, set the “disablewbforpstn” and “disablewbonmac” parameters to false. The opx dll/so/jnilib files have to be placed near the webhone.jar for the opus codec to work.

 

use_g7221

(int)

G.722.1 wideband codec.

Low-complexity Siren 7 audio coding format with sample-rate 16000 (7kHz audio bandwidth  16k samples/second).

Possible values: 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1.

 

Note:

The payload number is 114 by default and it will be negotiated automatically. You might change the default with the “g7221payload” parameter.

The bitrate is 24000 by default and it will be negotiated automatically. You might change the default with the “g7221bitrate” parameter to 24000 (24kbps) or 32000 (32kbps).

 

use_g7221uwb

(int)

G.722.1 ultra-wideband codec.

Low-complexity Siren 7 audio coding format with sample-rate 32000 (14kHz audio bandwidth 32k samples/second).

Possible values: 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 1.

 

Note:

The payload number is 115 by default and it will be negotiated automatically. You might change the default with the “g7221uwbpayload” parameter.

The bitrate is 32000 by default and it will be negotiated automatically. You might change the default with the “g7221uwbbitrate” parameter to 24000 (24kbps) or 32000 (32kbps) or 48000 (48kbps).

 

 

disablewbonmac

(boolean)

Whether to disable wideband codec on mac devices.

Mac OS X has a JVM bug which prevents java to reopen the audio devices with different sample rate.

Set this to false only if you are using wideband codec for each calls (so there is no chance that a call have to be handled in narrowband)

Default value is true

disablewbforpstn

(int)

This setting will disable opus, speex and g.722.1 wideband and ultrawideband for outgoing calls to regular phone numbers since these are usually not supported for pstn calls and they might requires longer initialization.

0: no

1: check at first call

2: check all calls

Default is 1. Set to 0 to never disable wideband.

 

 

use_g729

(int)

G.729 codec setting. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 2

*In some countries a license/patent is required if you use G.729 so enable only if you have licenses or licenses are not required in your case (consult your lawyer if you are not sure)

use_pcma

(int)

G711alaw codec. 0=never,1=don’t offer,2=yes with low priority,3=yes with high priority

Default is 2

 

use_pcmu

(int)

G711ulaw codec. 0=never, 1=don’t offer, 2=yes with low priority, 3=yes with high priority

Default is 1

 

alwaysallowlowcodec

(int)

Set to 2 to always put low computational and low bandwidth codec in the offer list, specifically GSM and PCMU. Low CPU or bandwidth devices might choose these codecs (such as a mobile phone on 3G).

Set to 0 to disable.

Default is 1 (auto)

 

codecframecount

(int)

Number of payloads in one UDP packet (frames per packet). This will directly influence RTP packet time (packetization interval) and packet size as shown here.

 

o    By default it is set to 0 which means 2 frames for G729 and 1 frame for all other codec.

This usually means 20 msec rtp packetization interval for all codec’s and it is the most optimal setting, compatible with all SIP/media stack implementations.

 

o    In case if you wish to minimize delay, then you might set the codecframecount to 1. This usually will result in 10 msec packetization interval and will increase the required bandwidth by 40% due to high header/data ratio.

o    In case if you wish to minimize bandwidth, then you might set the codecframecount to 4.

 

 

mediatos

(int)

Sets traffic class or type-of-service octet in the IP header for packets sent from UDP socket which can be used to fine-tune the QoS in your network. As the underlying network implementation may ignore this value applications should consider it a hint.

 

The value must be between 0 and 255.

Valid values (HEX):

Ø  0: disabled

Ø  1: automatic (set to 10 under normal conditions and disabled when in tunneling)

Ø  2: low-cost routing

Ø  4: reliable routing

Ø  8: throughput optimized routing

Ø  10: low-delay routing

Ø  or’ing the above values (from above 2)

Default value is 1.

 

Notes:

The old parameter name was udptos (still accepted, but changed to mediatos to clarify that this is applied only for RTP sockets, not for the signaling).

 

For Internet Protocol v4 the value consists of an number with precedence and TOS fields as detailed in RFC 1349. The TOS field is bitset created by bitwise-or'ing values such the following (DEC):

 

    IPTOS_LOWCOST: 2

    IPTOS_RELIABILITY: 4

    IPTOS_THROUGHPUT: 8

    IPTOS_LOWDELAY: 16

 

The last low order bit is always ignored as this corresponds to the MBZ (must be zero) bit.

 

This parameter might work only in preset environments; java JVoIP might not have enough rights to modify the IP TOS/DSCP headers.

Under Windows OS this has to be enabled by setting the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TcpIp\Parameters\DisableUserTOSSetting registry value to 0.

 

In case if you wish to set the TOS also for the signaling, use the sigtos parameter (the same way as the above mediatos, except that this will be applied for the signaling only, not for the media; it’s default value is 1 which will default to 4 - reliable routing).

 

automute

(int)

Specify if other lines will be muted on new call
0=no (default)

1=on incoming call

2=on outgoing call

3=on incoming and outgoing calls

4=on other line button click

5=on outgoing call and on other line button click (like 2+4)

6=on any call and on other line button click (like 3+4)

 

Default is 0

 

autohold

(int)

Specify if other lines will be put on hold on new call
0=no (default)

1=on incoming call

2=on outgoing call

3=on incoming and outgoing calls

4=on other line button click

5=on outgoing call and on other line button click (like 2+4)

6=on any call and on other line button click (like 3+4)

 

Default is 0

 

holdontransfer

(int)

Specify if initial line should be put on hold on transfer.

-1=auto
0=no

1=yes, hold before transfer

2=yes, hold before transfer and reload if needed (on transfer failure)

3=yes, hold on successful transfer init (OK for REFER received or attended call progress or success received; transferred call might not be initiated/connected yet). Will reload if needed (on transfer failure).

Default is -1 (which means 3 for transfertype 5 and 6, otherwise 0)

 

holdtypeonhold

(int)

Specify call hold type.

Call hold is usually initiated by the API_Hold function and with parameter you can specify which type of call hold do you wish to request.

Possible values:

-2: no

-1: auto (defaults to 2)
0: no (don’t hold. a=sendrecv)

1: reserved (not used)

2: send only: instructs the peer to not send audio (mute speaker. Local JVoIP: a=sendonly, peer: a=recvonly)

3: receive only: not sending audio to the other (mute microphone. Local JVoIP: a=recvonly, peer: a=sendonly)

4: hold: both (mute both in/out audio. a=inactive)

 

Default is -1.

 

Note:

By default the hold will check the previous state. For example if previously it was local hold (2) and you switch to remote hold (3) then actually will switch o both hold.
There is also a holdexplicite parameter which if set to 1, then the hold will be done strictly after the holdtypeonhold parameter, without considering previous state. This way you can also change between local and remote hold without the need to unhold first.

 

muteonhold

(int)

Specify if call also have to be muted with hold (stop recording/playback and stop the according RTP stream).

Possible values:

-2: no mute,

0: mute in and out

1: mute out (speakers)

2: mute in (microphone)

3: mute in and out (same as 0)

4: mute default

5: according to call hold.

 

Default is 5.

 

Usually you should set this either to -2 or 5.

 

defmute

(int)

Default mute direction.

0: both

1: mute out (speakers)

2: mute in (microphone)

3: both

4: both

5: disable mute

 

 

ackforauthrequest

(int)

If to send ACK for authentication requests (401,407).
0=no

1=yes (default)

Should be changed only if you have compatibility issues with the server used.

 

 

favorizecontactaddr

(int)

You may change it if you have compatibility issues with stateless proxies
0=never

1=no

2= conform RFC

3= yes. Sending for both server and contact URI (default)

4=always

 

prack

(boolean)

Enable 100rel (PRACK)

Set to false if you have incompatibility issues.

Default is false.

 

sendmac

(boolean)

Will send the client MAC address with all signaling message in the X-MAC header parameter.

Default value is false.

 

useragent

 (string)

This will overwrite the default User-Agent setting.

Do not set this when used with mizu VoIP servers because the server detects extra capabilities by reading this header.

Default is empty.

 

alloweventsheader

 (string)

This will overwrite the default Allow-Events setting.

Default value is: presence,refer,telephone-event,keep-alive,dialog

Note: not all capabilities are listed by default.

You might list the other expected capabilities here such as hold, talk, message-summary etc.

 

sendsessionid

 (int)

Specify if to send the Session-ID header as specified in RFC 7989.

Possible values:

-1: if received (default)

0: no (disable)

1: yes (enable)

Default is -1.

 

customsipheader

(string)

Set a custom sip header (a line in the SIP signaling) that will be sent with all messages. Can be used for various integration purposes (for example for sending the http session id or any other data to your SIP server). Multiple lines can be separated by semicolon (;) or CRLF (\r\n).

 

Default value is empty.

 

Examples:

Add a SIP header:

customsipheader="X-MyData: 1"

Add multiple headers:

customsipheader="X-MyData: 1CRLFX-MyFlag: 2"

You can also rewrite known SIP headers if you set the keepoldcustomvalues parameter to -1:

customsipheader="To: <sip:user@domain.com>"

 

Notes:

·         You might use the keepoldcustomvalues parameter to control how the keys are merged: -1: merge also with SIP msg overwriting calculated known headers, 0: merge customsipheaders, but not with existing known precalculated headers (default), 1: don’t merge / keep duplicated headers.

·         Custom SIP headers can be set also at runtime with the API_SetSIPHeader function.

·         Instead of custom SIP headers you might use other method to communicate with your backend, such as NOTIFY, INFO, UUI, MESSAGE, UUSD, custom SIP requests or separate API calls.

 

customsdpfield

(string)

The customsdpfield works like the customsipheader parameter but it is to be used for SDP (or for any SIP message body) instead of the SIP headers.

Use the customsdpfield parameter to set a custom global SDP field (a line in the SDP body before the m= line) that will be sent with all messages.

It can be set also at runtime with the API_SetSDPField function.

 

 

customsdpmediafield

(string)

Set a custom media SDP field (a line in the SDP body after the m= line) that will be sent with all messages.

It can be set also at runtime with the API_SetSDPField function.

Default value is empty. Multiple lines can be separated by semicolon (;).

 

rtpextraheader

(string)

Set RTP extra header bytes.

The string will be converted to RTP extra header word(s).

If only one extra word needs to be set, then pass it as an integer (integer value converted to string).

Multiple words can be set by separating them with semicolon (;) .Example: 98;76543 will set the first word to 98 and the second word to 76543.

It can be set also at runtime with the API_RTPHeaderExtension function “extension” parameter.

See the RTP header extension FAQ point for more details.

 

 

rtpextraheader_profile

(int)

Set the profile number (the first two bytes) for the RTP extra header if required.

If not set then the profile bytes will be set to 0.

It can be set also at runtime with the API_RTPHeaderExtension function “profile” parameter.

See the RTP header extension FAQ point for more details.

 

 

sip_uui

(string)

Specify UUI data (User-to-User Call Control Information as described in RFC 7433).

Can be used to send data to other endpoints. Not all endpoints and SIP servers supports this feature.

If prefixed with *0: then the UUI will be sent only to peer with the User-to-User header.

If prefixed with *1: then the UUI will be sent only to target party with call transfer or redirect escaped in Contact or Refer-To URI.

If not prefixed or prefixed with *2: the UUI will be sent both way.

 

It can be set also at runtime with the API_SetUUI function.

Default value is empty.

 

Simple example: mydata

Example with parameters: *2:mydata;encoding=hex;purpose=foo;content=bar

 

techprefix

(string)

Add any prefix for the called numbers.

Default is empty.

 

normalizenumber

(int)

Normalize (called) numbers by removing .-,;()[]: and space if the string otherwise doesn't contains a-z or A-Z characters (looks like a phone number).

Possible values:

-1: auto (usually defaults to 1 yes, except if our username also contains special characters)

0: no

1: yes

Default is -1.

 

numrewriterules

(string)

Simple called number prefix rewrite rules.

Although you can rewrite any number from your own code as you wish, you might use this numrewriterules parameter to let the SIP stack rewrite the prefix of the called numbers.

Format (parameters): from;to;minlength;maxlength

If you wish to add more rewrite rules, then you can separate them with comma.

Example:

07;00407;8;12,74;004074

This will rewrite prefix 07 to 00407 if number length is between 8 and 12 characters and will rewrite prefix 74 to 004074 regardless of the number length.

 

Note: this parameter is same with numpxrewrite

 

numrewriterulesadv

(string)

Advanced number rewrite rules.

Although you can rewrite any number from your own code as you wish, you might use this numrewriterulesadv parameter to let the SIP stack rewrite numbers.

 

Parameters can be separated by ; or _P_

Rules can be separated by , or _L_

Rules must begin with the separator character.

 

Parameters:

1.        apply to sessions: 0=outgoing calls, 1=incoming calls, 2=all calls, 10=outgoing all, 11=incoming all, 12=all (Defaults to 0)

2.        apply if number: 0=all numbers, 1=start with, 2=ends with, 3=contains, 4=equals, 5=not contains, 6=not start with (Defaults to 1)

3.        string (used if needed for the above condition)

4.        min number length  (Defaults to 7)

5.        action: 0=rewrite, 1=rewrite all, 2=remove, 3=add prefix, 4=add suffix  / 10=auto answer, 11=ignore, 12=forward, 13=reject (Defaults to 2)

6.        rewrite from (used if the above action is 0)

7.        string (used if needed for the above action is less then 10)

8.        stop further rule processing if this rule match (0/1)   (Defaults to 0)

 

Example rule to insert 00 prefix if not already there for outgoing calls if number length is more than 8 digit:

_P_0_P_6_P_00_P_8_P_3_P_0_P_00_P_0_P__L_

 

 

mustconnect

(boolean)

If set to true, than users must register before to make any calls.

Default value is false.

 

rejectonbusy

(boolean)

Set to true to reject all incoming call if there is already a call in progress.

Default value is false.

 

disablesamecall

(int)

This setting can be used to don't allow/block double call the same number.

Possible values:

-1: auto-guess depending on config/usage

0: allow multiple calls to the same destination username/number.

1: reject call attempt with numbers already in call when the previous call was initiated less than 6 seconds ago.

2: reject call attempt with numbers already in call.

3: reject call attempt with numbers already in call regardless if it is incoming or outgoing current call.

 

Default value is 1

 

maxsimcalls

(int)

Maximum number of simultaneous calls (channel limit/number of call limit).

Will impose a max concurrent call limit applied for both incoming and outgoing calls.

For example if you set it to 1, then the enduser can’t initiate or receive new calls while already in call.

Default value is -1 which means no call limit.

 

Note: if set to 0 then all calls will be denied.

 

 

redialonfail

(int)

Retry the call on failure or no response.

·         0: no

·         1: yes

Default value is 1.

 

A related setting is the “allowrecall” parameter which can be used for more precise control:

o    0: no

o    1: normal invite resend (same as redialonfail 0)

o    2: yes srv record and other important retry

o    3: always when malfunction is detected such as no answer or no incoming RTP (same as redialonfail 1)

 

These parameters will affect only failed unconnected calls.

 

 

autoredial

(int)

Redial on call disconnect.

Possible values:

·         0: no (default)

·         1: if it was disconnected because rtp timeout and we were the originator

·         2: if it was disconnected because rtp timeout

·         3: if we were the originator

·         4: if we were the called

·         5: always

The redial will be performed only if there are no other call in progress and the call was not locally terminated (such as pushing the Hangup button or calling the API_Reject or API_Hangup functions).

For better control on when to redial, you might use the API_Call instead on certain conditions as required for your app logic.

 

callforwardonbusy

(String)

Specify a number where calls should be forwarded when the user is already in a call. (Otherwise the new call alert will be displayed for the user or a message will be sent on the API)

Default is empty.

 

callforwardonnoanswer

(String)

Forward incoming calls to this number if not accepted or rejected within 15 seconds. You can modify this default 15 second timeout with the callforwardonnoanswertimeout setting.

Default is empty.

 

 

callforwardalways

(String)

Specify a number where ALL calls should be forwarded.

Default is empty.

 

calltransferalways

(String)

Specify a number where ALL calls should be transferred.

This might be used if your softswitch doesn’t support call forward (302 answers).

Default is empty.

 

autoignore

(int)

Set to ignore all incoming calls.

0=don’t ignore

1=silently ignore

2=reject

Default value is 0.

 

Note: this will not reject the calls, but they will be ignored/muted.

 

autoaccept

(boolean)

Deprecated by enableautoaccept.

Enable/disable automatically accepting incoming calls.

Set to true to automatically connect all incoming calls (auto answer).

Default is false.

 

You might also specify a delay with the autoacceptdelay parameter.

More details here.

 

enableautoaccept

(int)

Specify to enable auto-answer for incoming calls.

Possible values:

0: never (except for barge-in calls if the bargeinheader is set and it has a match in the incoming call INVITE message)

1: enable only if the autoacceptheader is set and it has a match in the incoming call INVITE message

2: enable also for server-side initiated auto answer (if headers such as Call-Info, Alert-Info, Answer-Mode or Auto-Answer are received with the incoming INVITE)

3: force auto answer: auto connect all incoming calls

Default is 1.

 

For example you might just set this parameter to 3 to auto-answer all incoming calls.

More details here.

 

Note: the old autoaccept parameter is deprecated now and replaced with this parameter (enableautoaccept set to 3 is the same like the old autoaccept set to true).

 

 

autoacceptheader

(string)

With this parameter you can specify a special string which when received form your SIP server incoming call INVITE message, JVoIP will auto-answer the incoming call.

For example if you set it to "myspecialstring" and the "myspecialstring" is a substring of the incoming INVITE, then the call will be automatically accepted.

The string can be set to anything, including an extra header (such as "X-My-Auto-Accept: yes") or even to a caller-id.

The search is case insensitive.

Default is empty (which means that it will not check for any strings for auto-accept)

 

Note: Instead of a special string, you might set the enableautoaccept parameter to 2 and use the known server-initiated headers instead such as Call-Info, Alert-Info or Auto-Answer.

More details here.

 

bargeinheader

(string)

JVoIP barge-in feature allows you to bare into any call and create a hidden conference endpoint, so you can hear the JVoIP conversation(s).

With this parameter you can specify a special string which when received form your SIP server incoming call INVITE message, JVoIP will auto accept the incoming call as a hidden call-leg. This is very similar to the above autoacceptheader parameter. The main difference is that in this case the incoming call will be hidden.

This feature can be used to silently listen for JVoIP calls. It is often used in callcenters by supervisors to monitor the agents activity.

Default is empty (no barge-in calls checked and allowed).

 

Note:

In case if you wish to use JVoIP for the supervisor barge-in calls, then you can set it with the customsipheader parameter. For example if you have set the bargeinheader for the agents JVoIP instances to "X-BargeIn: yes", then set the exact same as the customsipheader parameter for the supervisor JVoIP instance and just call any agent(s) to listen on their calls.

Instead of using barge-in calls, you might consider to just enable call recording or use media streaming as alternatives for quality controls.

 

autoacceptdelay

(int)

Specify a delay (milliseconds) for call auto-answer.

This is applicable for both server side initiated auto-answer or if you have set the enableutoaccept parameter to 3 to auto answer all incoming calls.

Possible values:

-1: default (will check the answer-after flag received from your server or instant answer if not received)

0: always instant answer

1+: always force this amount of delay in milliseconds

Default is -1.

 

This timer has a resolution of around 1000 milliseconds (1 seconds).

For example if you set this to 4000 then then calls will be answered only after a 4 seconds delay (up to 5 seconds).

More details here.

 

 

blacklist

(string)

Block incoming communication from these users. (users/numbers separated by comma).

Default value is empty.

 

rejectcallto

(int)

Set to ignore calls if target doesn’t match

0=accept all incoming calls

1=check if target user match

2=check rinstance

3=check rinstance strict

4=check all strict

Default value is 0.

 

hideautocall

(int)

Set to 1 to suppress notifications (STATUS, CDR) from automatically handled calls (ignored, forwarded, rejected and similar).

0=send status notifications also about auto handled calls

1=do not send status notifications from auto handled calls

Default is 0.

 

ringtimeout

(int)

Maximum ring time allowed in millisecond.

Set to 0 to disable.

Default is 90000 (90 second)

 

calltimeout

(int)

Maximum speech time allowed in millisecond.

(With other words, this is a maximum call duration limitation applied for each call session separately).

Set to 0 to disable.

Default is 10800000 (3 hours)

 

startsipstack

(int)

Automatically start the sipstack after a specified time.

0=no (the sipstack will be started on the first register or call event)

1=on startup if not tunneling or serveraddress/username/password are set (the sipstack will be started at app init)

2=on startup always (the sipstack will be started at app init)

Other=seconds (the sipstack will be started after the specified seconds)

Default value is 1

 

You can set to 0 if there is less change that JVoIP will be used once the users will open the app or webpage hosting JVoIP.

You can set to 1 or higher if there is a high probability that the user will use JVoIP to make calls (this will shorten the setup time for the first call).

You can also start the SIP stack explicitly by using the API_Start function.

 

timer

(int)

You can slow down or speed up the SIP protocol timers with this setting. You may set it to 15 if you have a slow server or slow network.

Default value is 10.

 

timer2

(int)

Same as “timer” but it affects idle, connect and ring timeout and maximum call durations.
Default value is 10.

 

mediatimeout

(int)

RTP timeout in seconds to protect again dead sessions.

Calls will be disconnected if no media packet is sent and received for this interval.

You might increase the value if you expect long call hold or one way audio periods.

Set to 0 to disable call cut off on no media.
Default value is 300 (5 minute).

At the beginning of the calls, the half of the mediatimeout value is applied (2.5 minute by default if there was no incoming audio at all).

 

 

mediatimeout_notify

(int)

RTP timeout in seconds for API notify.

After this timeout a warning message is sent via notifications without any further action.

The following log will be generated: “WARNING,media timeout (notify)”
Default value is 0 (disabled)

 

rtpkeepaliveival

(int)

RTP stream keep-alive packet send interval in milliseconds.

This is useful if your PBX has an RTP timeout setting to prevent disconnects when the java softphone is hold or muted.

Default value is 0 which means no keep-alive packets. (You might set it to 25000 for example to send a packet in every 25 seconds)

 

sendrtponmuted

(boolean)

Send rtp even if muted (zeroed packets)

Set to true only if your SIP server is malfunctioning when no RTP is received (such as dropping the call on media timeout).

Default value is false.

 

sendrtponfailed

(int)

Specify if to send RTP packets if unable to open the recording device.

Possible values:

0: No

1: At the beginning (to open the NAT for incoming audio)

2: Yes always

3: Must

Default is 1.

 

sendrtpondisabled

(int)

Specify if to send RTP packets if useaudiodevicerecord is set to false.

Possible values:

0: No

1: at the beginning (to open the NAT for incoming audio)

2: yes always

3: must

Default is 3.

 

 

discmode

(int)

For call disconnect compatibility improvements. Some VoIP devices might have bugs with CANCEL forking, so it is better to always send a BYE after the CANCEL message on call disconnect. In this case set the discmode parameter to 3.

1: quick

2: conform the RFC

3: send BYE after CANCEL when needed

4: double: always repeat the CANCEL and the BYE messages

Default value is 2.

 

waitforunregister

(int)

Maximum time in milliseconds to wait for unregistration when the API_Unregister is called or the java sip stack is closed.

If set to 0 that an unregister message is sent (REGISTER with Expires set to 0) but JVoIP is not waiting for the response, which means that it will not repeat the un-register in case if the UDP packet was lost.

Default value is 2000.

 

clearcredentialsonunreg

(int)

Specify whether user login details (server/username/password settings) have to be cleared on unregister or not.

Possible values:

-1: auto

0: no

1: yes

Default: -1

 

 

md5

(string)

Instead of using the password parameter you can pass an MD5 checksum for better protection: MD5(username:realm:password)

(The parameters are separated with the ‘:’ character)
The realm is usually your server domain name or IP address (otherwise it is set on your server)

If you are not sure, you can find out the realm in the “Authenticate” headers sent by your server with the” 401 Unauthorized” messages. Example:

WWW-Authenticate: Digest realm="YOURREALM", nonce="xxx", stale=FALSE, algorithm=MD5

Default is empty.

 

 

realm

(string)

Set if your server realm (SIP domain) is not the same with the “serveraddress” parameter.

If the “md5” parameter was set, then this must match with the realm used to calculate the md5 checksum.

Default is empty, which means that the “serveraddress” will be used.

 

 

encrypted

(boolean)

Specify if the transport will be encrypted (both media and the signaling)

Compatible only with Mizu VoIP servers.

Automatically turned on when using http tunneling.

Default is false.

 

authtype

(int)

Some IP-PBX doesn’t allow “web” or “proxy” authentication.

0=normal

1=only proxy auth

2=only simple auth

 

sipproto

(string)

You can change the URI with this string.

Default value is “sip”.

You might change it to “sips” or “tel” if needed.

 

sipusername

(string)

Specify default SIP username. Otherwise the “username” parameter will be used for both the username and the authentication name.

Default is empty.

 

If this is not specified, then the “username” will be used for the From field and also for the authentication.

If both the username and sipusername is set then:

-the username will be used in the From and Contact fields (CLI/caller-id)

-the sipusername will be used for authentication only

 

More clarifications here.

 

 

displayname

(string)

Specify default display name used in “from” and “contact” headers.

This is usually the full name of the enduser such as “John Smith”.

Default is empty (the “username” field will be displayed for the peers)

 

More clarifications here.

 

pwdencrypted

(int)

Specify if you will supply encrypted passwords via parameters or via the Java API
0=no (default)

1=xor

2=des+base64

3=xor+base64 (this is the preferred method; easiest but still secure enough)

4= base64

This method is deprecated from version 3.4. All parameters can be passed encrypted now by just prefixing them with the “encrypted__X__” string where X means the id of the encryption method used.

 

From version 4.8 there is no need to specify this parameter anymore. Just prefix any parameter with encrypted_X as described here.

 

voicerecording

(int)

0=no (default)

1=local

2=remote ftp or http upload

3=both

 

If set to 2 or 3 then either the voicerecftp_addr or the http_addr parameter have to be set.

Local recorded files are placed in the mwphonedata folder which is usually created near the JVoIP.jar if it has permission to its own folder or otherwise to another location such as the user home directory.

The voice recording can be also toggled on/off at runtime with the API_VoiceRecord function.

For more details see the voice record FAQ.

 

voicerecfilename

(int)

The format of the recorded filenames.

0=date-time + peer name (default)

1=date-time + sip call-id

2=sip call-id

3=date-time + username

4=date-time + username + peer name

 

The date-time will be formatted in the following way: yyyyMMddhhmmss

 

Note: You can also use the “voicerecfilenameprefix” parameter to add a prefix for the file name.

 

voicerecftp_addr

(string)

FTP location for the recorded voice files if the “voicerecording” parameter is set to 2 or 3.

Format: ftp://USER:PASS@HOST:PORT/PATH/TO/THEFILE

Example: ftp://user01:pass1234@ftp.foo.com/FILENAME

 

The FILENAME part of the string will be replaced with the file name according to the “voicerecfilename” parameter.

 

voicerecformat

(int)

Recorded file compression.

0: PCM wave stereo files with separate channels for in/our (default)

1: raw gsm. (two files will be generated for each call. One for the recorder file and another for the playback. These files can be played with players supporting gsm codecs for example quicktime, which works also as a browser plugin, or a winamp plugin is downloadable from here. Backups here.)

2: ogg/vorbis (optional, on request; module not included by default; notify Mizutech to include ogg/vorbis support in your build if you need this option)

3: mp3 (Make sure that lame is near the jar or is found on the path. It can be downloaded from here for windows or use your package manager on linux. New JVoIP versions will try to download it automatically on demand)

 

 

voicerecordingbuff

(int)

The maximum recorded file length.

-1: dynamic, no limit

1: max around 1 minute

2: max around 2 minute

 

Default is -1.

 

syncvoicerec

(int)

How to synchronize the recording/playback side:

-1: Auto

0: No (don’t synchronize)

1: Yes (fill with noise the other channel)

2: Yes (wait for both side)

Default: 2

 

Note: you should set this to 0 if you have one-way audio calls such as IVR calls.

 

uploadretry

(int)

Specify whether the file upload should be retried on failure if the voicerecording parameter is set to 2 or 3.

0: no

1: once

2: until success

Default: 1

(Old parameter now was ftpretry which can be still used but now applies also for http uploads)

 

ftp_addr

(string)

FTP location for general storage (for example for settings, contactlists)

Format: ftp://USER:PASS@HOST:PORT/PATH/TO/THEFILE

Example: ftp://user01:pass1234@ftp.foo.com/FILENAME

 

The FILENAME part of the string will be replaced with the actual file name.

 

 

http_addr

(string)

HTTP location for general storage (for example for voice recording, settings,or contactlists). It can be a HTTP or HTTPS URL.

Example: https://www.yourdomain.com/storage/

 

For this parameter to work, you need a server side script capable to accept the file uploads (standard HTTP file upload).

 

If the file name part can be omitted (in this case the filename will be set as specified by the voicerecfilename or API_VoiceRecord function call).

 

You can also suggest a particular file format by appending its extension to the file name (for example .wav or .mp3).

For example: http://www.foo.com/myfilehandler.php?filename=callrecord_DATETIME_USER.wav

 

You can also set just a path, without any URL query parameter, like this:

For example: https://www.foo.com/myfilehandler.php/rec_DATETIME_CALLID

 

Example HTTP POST header packet if you set the url to “http://yourdomain.com/myapi/voicerecord/anyentry?filename=callrecord_DATE_CALLID.mp3”:

POST /myapi/voicerecord/anyentry?filename=callrecord_2022_02_12_xxx.mp3 HTTP/1.1

Host: yourdomain.com

User-Agent: webphone

Accept: */*

X-type: fileupload

X-filename: callrecord_2022_02_12_xxx.mp3

X-user: local_username

X-caller: caller_party

X-called: called_party

X-callid: sip_callid

X-server: your_sip_server_address

Content-Length: 18623

Expect: 100-continue

Content-Type: multipart/form-data; boundary=------------------------fde9999399e1b8eb

 

--------------------------fde9999399e1b8eb

Content-Disposition: form-data; name="file"; filename="callrecord_2022_02_12_xxx.mp3"

Content-Type: application/octet-stream

.....

 

You will receive “file” as the form name parameter and the name of the file as the form data “filename” parameter.

(So you will receive the file name as both the “filename” form parameter and also in the X-filename HTTP header).

The content type can be application/octet-stream, audio/x-wav,  audio/mpeg, audio/x-gsm or audio/ogg.

(Regardless of the suggested file name, you can save the files on your server with any name, this is your choice).

A working example for PHP can be downloaded from here.

More details about handling HTTP file upload: C#ASP.NET, PHP, PHP (2), NodeJS, Java.

 

 

autocfgsave

(int)

Configurations and statistics are stored in a local file to be reused in next sessions.

This is not critical and the Java VoIP client will work just fine if this file is lost or deleted by the user.

Sometime is useful to not allow configuration/settings storage on the user device.

The autocfgsave option can be set to the following values:

·         -2: disable all file write forced

·         -1: disable file write

·         0: disable config storage

·         1: save only

·         2: load only

·         3: save and load

Default is 3.

 

resetsettings

(boolean)

Set to true to clear all previously stored or cached settings.

Should be passed as command line parameter only.

Default is false.

 

maxlogsize

(int)

Specify maximum log file size in bytes.

Default is 31457280 (which means 30 MB).

 

Note:

This is just an upper hard limit and it is relevant only if you run JVoIP for days without restart with higher loglevel. Otherwise, it is unlikely that you will reach it since the logs are cleared with each restart (as specified with the above deloldlogs parameter). Under normal circumstances the log file is usually below 10 MB with loglevel 5 and below 100 KB with loglevel 1.

 

 

configversion

(int)

Set to a positive value or increment it with one to reset setting once (clear all previously stored or cached settings).

Default is 0 which means no reset.

 

signalingport

(int)

Specify the local SIP signaling port to use (bind port / local port). This might be useful for some use cases, for example if you wish to reach JVoIP directly, without the need to register to a SIP server first. See the P2P FAQ point about this.

Default value is 0 (which means that a stable port will be selected randomly at the first usage and will be kept the same)

 

Note:

This is not the port of your server where the messages should be sent. This is the local port for sip user agent and it doesn’t have to be 5060. For more details see here.

If JVoIP can’t bind to the specified port (for example if the port is already used by some other local app) then it will try to use another port.

 

rtpport

(int)

Specify local RTP port base.

Default is 0 (which means signalingport + 2)

Note: If not specified, then VoIP SDK will choose signalingport + 2 which is then remembered at the first successful call and reused next time (stable rtp port). If there are multiple simultaneous calls then it will choose the next even number, thus the port range will be from: rtpport to: rtpport + 2x maximum number of calls + any additional ports which might have been skipped if used by some other app.

The RTCP port for each call will be the rtpport+1.

For more details see here.

 

incrtpport

(int)

Increment RTP port for each call by this value.

Might be needed only with some misbehaving routers. If not set, then JVoIP will try to use the same RTP ports for all calls if available (if can bind to it, otherwise will try the next even number).

Default is 0.

 

Note: You will still have a different RTP port for each simultaneous calls even if this is set to 0.

 

bindip

(String)

Specify local network interface IP address for the sockets to bind to.

This parameter might be used only on devices with multiple local IP addresses to force the specified IP.

This parameter should be used only with local private IP.

Default is empty (by default it doesn’t bind to any IP and it is up to the OS routing table from which IP the packets are sent)

 

Note: JVoIP by default will auto detect the “best” IP to be used and this parameter should be used only in very specific circumstances.

 

 

localip

(String)

Specify local IP address to be used for the SIP signaling.

This parameter might be used only on devices with multiple ethernet interface to force the specified IP or if JVoIP is behind NAT to specify it’s public IP.

This parameter should be used only with static IP (if the device IP doesn’t change dynamically from DHCP)

Default is empty (auto-detect best interface to be used)

 

Note:

JVoIP by default will auto detect the “best” IP to be used and this parameter should be used only in very specific circumstances.

It is also possible to set the address sent in SDP explicitly with the localsdpip and localsdpport parameters.

 

 

favlocalip

(String)

Specify local subnet preference.

For example if the device where JVoIP is running might have two separate IP (such as 192.168.1.5 and 10.0.0.5) then you might set the favlocalip to 192 to always prefer the 192.x.x.x subnet.

This parameter might be used only on devices running on a known environment (local LAN) in case if you wish to suggest the subnet to be used.

Default is empty (auto-detect best subnet to be used)

 

Note: JVoIP by default will auto detect the “best” IP to be used and this parameter should be used only in very specific circumstances.

 

 

bindtolocalip

(int)

Specify if sockets must bind to the configured (localip parameter) or to the auto detected local ip.

Possible values:

-1: auto (guess)

0: no

1: yes

Default is 0.

 

Note:

·         This setting can applied even if the localip parameter is not explicitly set (auto detected best local ip to use), but it doesn’t make sense if bindip is set.

·         The disadvantage of setting to 1/yes is that the SIP stack might not tolerate so easy the local IP change (in case if running on a dynamic IP assigned DHCP)

·         The advantage of setting to 1/yes is that the packets will be always sent from the same address specified in the signaling (some SIP server might be confused if receives packets from a different address then the address specified in the signaling)

·         The -1/auto will bind to local IP if detected or configured local IP is found locally assigned and it is in the same subnet with the SIP server

·         JVoIP by default will auto detect the “best” IP to be used and this parameter should be used only in very specific circumstances.

 

        

jittersize

(int)

Although the jitter size is calculated dynamically, you can modify its behavior with this setting.

0=no jitter,1=extra small,2=small,3=normal,4=big,5=extra big,6=max

Default is 3

 

Increase the jittersize if audio is breaking up or decrease to minimize delay. The default 3 is a good compromise between quality and latency.

 

maxjitterpackets

(int)

You can limit the jitter buffer size with this setting.

This is an hard limitation for the jitter algorithm and usually should not be set.

With the jittersize left as default (3) the maximum buffered packet count is limited to around 8, so you might set this parameter to a lower value.

One packet means a received udp packet which might contain one or more audio frame.

For example when using G.729 the typical media stream are with 2 frames/packet. Each frame is 10 msec length.

A jitter limitation of 5 would mean maximum 100 msec to be cached. (while the default setting would allow 8 packet which means 160 msec)

Default value is 70 (which basically means no limitation)

 

allowspeedup

(int)

Specify whether to enable audio playback speedup on high queue size.

(Instead of dropping packets, it might attempt to speed up the playback rate for a short time until queue size drops below threshold)

Possible values:

-1: Auto Guess (default)

0: No (might drop packets instead of speedup)

1: Yes (might speedup instead of packet drop)

 

In VoIP it is very common that the call setup/audio device open might take some time (10-400 milliseconds in case of JVoIP, depending on mediaench/device capabilities/audio hardware/driver).

Most SIP clients will simply drop audio packets arrived during this time (when their jitter buffer or other queue is full) which results in a small audio loss (it can be heard sometimes, not at other times).

JVoIP might just speedup the playback for a while to catch-up. This might result in a little audio distortion but will prevent audio loss in such situation.

The same algorithm s applied for burst receive or when the peer is sending more packets then expected (clock/synchronization issues).

 

allowfirstdrop

(int)

Specify whether to enable drop of RTP packets on media start.

Sometime the other end might start sending RTP before the media is opened at JVoIP side resulting in accumulation of packets.

Dropping the first few packets will make the playback of the rest more smooth, but might result in some loss of audible media (usually up to 100 milliseconds)

Possible values: -1: Auto Guess (default), 0: No, 1: Yes

 

increasepriority

(boolean)

This will increase the priority for the whole thread-group which might help on slow CPU’s or when other applications are generating high CPU load.

Note: the priority of the threads handling media are increased regardless of this setting.

Default is false.

aqtest

(int)

Audio quality test.

Set to 1 for server/voice quality tests. More details in the FAQ.

 

loglevel

(int)

Tracing level. Values from 0 to 6.

If you set it to more than 3, then a log window will appear and also will write the logs to a file (if file write permissions are enabled on the client side).

With level 0, the VoIP SDK will not even display important even notifications for the user. Don’t use this level if possible.

Loglevel 5 means a full log including SIP signaling. Higher log levels should be avoided in production as it can slow down the application.

Text logs are sent to the following outputs:

-status display (only level 1 –these are the most important events that needs to be displayed also for the user)

-log window (if loglevel is higher than 3 then a log window will appear automatically. Copy the logs with Ctrl+A,Ctrl+C,Ctrl+V)

-file if loglevel is higher than 3 (\mwphonedata\webphonelog.dat near the app or in the java user home directory which depends on the OS/java/browser used)

-java console (if the logtoconsole parameter is set to true)

Default loglevel for demo/trial builds: 5

Default loglevel for licensed builds: 1

 

More details can be found here.

 

logtoconsole

(int)

Whether to send tracing to the java console (System.out.print or often referred as STDOUT).

Possible values:

o    0: no (disable log to console)

o    1: auto (depending on loglevel)

o    2: always (always log to stdout)

Default is 1.

 

canopenlogview

(boolean)
JVoIP might open a log view window if the loglevel is higher the 2.

You can disable this log window by setting this parameter to false.

Default value is true.

 

canlogtofile

(boolean)

With loglevel set to 2 or more, the logs are written also to a local file. To disable the log files, set the canlogtofile parameter to “false” (or set the “loglevel” to 1).

Default is true.

 

logpath

(string)

You might specify the log file path. Environments variables enabled. It might be useful in corporate environments with centralized logging.

Default is empty (which means mwphonedata subfolder or if no write access then in user, tmp or appdata folder)

 

deloldlogs

(boolean)

Specify whether you wish to delete the old log files.

0: no (new logs will be appended)

1: yes (the previous log file will be kept, older files will be deleted)

3: delete old log

Default: 1

 

 

capabilityrequest

(boolean)

If set to true then will send a capability request (OPTIONS) message to the SIP server on startup. The serveraddress parameter must be set correctly for this to work. This method is useful to release the security restrictions when using the VoIP SDK with the API and also to open the NAT devices.

Default value is false.

 

 

keepaliveival

(int)

NAT keep-alive interval in milliseconds which is usually sent from register endpoints.

Possible values:

o    -1: auto (this will default usually to 28 seconds on UDP and 600 seconds on TCP, but can be influenced by many factors)

o    0: disable

o    1-3000: invalid

o    3000 ore more: milliseconds to send keep-alive packets.

Values below 20000 (20 sec) should not be used.

Default value is -1.

 

recaudiobuffers

(int)

Number of buffers used for audio recording.

Default is 7.