This Diva SDK for Linux supplies our customers with an easy to use interface to create own fax, voice, data transfer and monitoring applications. This functionality is provided by a library, which has to be linked to the customers application. The interface specification necessary for building the application is provided in the respective header file supplied with the Diva SDK.
To demonstrate the basic design of a Diva SDK related application, various samples are provided with the Diva SDK. These samples cover fax server, fax client and fax polling, voice sending/recording and monitoring applications. Some samples are designed just to demonstrate basic functionality without any error handling (single source files). Other samples are intended to be more comfortable and can be used as starting point for own applications. All samples are designed to be portable between operating systems. The actually supported operating systems are Linux and Windows. This is due to the operating system support of the used underlying CAPI and hardware drivers.
The Diva SDK is available as RPM and Debian packages. Use a package tool or the command line versions of RPM/dpkg to install the Diva SDK.
For RPM-based distributions:
| To install: | rpm -i dssdk-<version>-1.i386.rpm |
| To upgrade: | rpm -U dssdk-<version>-1.i386.rpm |
dssdk-<version>-1.x86_64.rpm
For Debian distributions:
| To install: | dpkg -i dssdk-<version>-1.i386.deb |
| To upgrade: | (Debian does not differentiate between installation and upgrade) |
dssdk-<version>-1.x86_64.deb
Due to binary incompatibilities between version 2.xx and 3.xx of the GNU C/C++ compiler, the Diva SDK is provided for both mainstream versions of this compiler as separate packages. Please use the correct package suitable to the installed compiler on your system. Thanks to RPM's dependency system, you will get errors if you try to install the wrong package on your system. This is not true for the Debian packages, however. For 64 bit platforms, version 4.xx of the compiler is needed.
During installation the following files will be installed:
| File | Description |
|---|---|
| /usr/include/dssdk.h | Diva API interface specification and constants |
| /usr/include/smssdk.h | Specification of SMS (short message service) interface |
| /usr/lib/libDivaS.a | Diva API static library |
| /usr/lib/libDivaS.so, *.so.1, *.so.1.<version> | Diva API shared library and symbolic links |
| /usr/lib/libDivaJava.so, *.so.1, *.so.1.<version> | Diva JNI shared library and symbolic links |
| /usr/share/doc/packages/dssdk-gcc3x/CxDtmf.pdf | Documentation about proprietary DTMF extensions to CAPI interface |
| /usr/share/doc/packages/dssdk-gcc3x/CxEcho.pdf | Documentation about proprietary echo cancelling extensions to CAPI interface |
| /usr/share/doc/packages/dssdk-gcc3x/CxFax.pdf | Documentation about proprietary FAX extensions to CAPI interface |
| /usr/share/doc/packages/dssdk-gcc3x/CxModem.pdf | Documentation about proprietary Modem extensions to CAPI interface |
| /usr/share/doc/packages/dssdk-gcc3x/CxTone.pdf | Documentation about proprietary tone generation and recognition extensions to CAPI interface |
| /usr/share/doc/packages/dssdk-gcc3x/DivaSAPI.pdf | The main Diva API documentation |
| /usr/share/doc/packages/dssdk-gcc3x/readme.html | This file |
| /usr/share/doc/packages/dssdk-gcc3x/examples.tgz | Archive that contains the Diva SDK samples |
The directory for the documentation files differ for the various package variants:
| Variant | Directory |
|---|---|
| RPM, gcc 2.x | /usr/share/doc/packages/dssdk-gcc2x |
| RPM, gcc 3.x | /usr/share/doc/packages/dssdk-gcc3x |
| RPM, gcc 4.x, 64 bit | /usr/share/doc/packages/dssdk-gcc4x |
| Debian, gcc 2.x | /usr/share/doc/dssdk-gcc2x |
| Debian, gcc 3.x | /usr/share/doc/dssdk-gcc3x |
| Debian, gcc 4.x, 64 bit | /usr/share/doc/dssdk-gcc4x |
For the 64 bit packages, the libraries will be placed the directory /usr/lib64.
Unpacking the file 'examples.tgz' into the current directory creates one directory for each sample. The created directories and a short description of the sample are listed in the table below. A more detailed description of each sample including the sample subdirectory tree and file structure is provided by the 'readme.html' file inside each sample directory. The samples are written in 'C'.
| Directory | Sample Description |
|---|---|
| audiomonitor | Monitoring calls and record audio streams |
| audiomonitorcodecs | Monitoring calls and record audio streams using compression codecs |
| audiomonitorex | Interactively monitoring calls and record audio streams |
| faxdial | Sample for processing outgoing fax calls |
| faxinsimple | Mainstream sample for fax reception |
| faxoutsimple | Mainstream sample for sending fax |
| faxserver | Simple faxserver |
| POS_modem_scenarios | Process incoming modem calls for various low bit rate modem protocols |
| RoutingGateway | Answer incoming calls, route them to outgoing calls and bridge the audio. Dial numbers and attributes for the outgoing calls can be manipulated based on routing information. |
| setdevicestatus | Enable or disable the layer 1 state of a line |
| showdevicestatus | Show the status of a device, including layer 1, layer 2 and alarm states. |
| showdevicestatusevents | Show initial line device status and changes on device status |
| smsservicecenter | SMS service center |
| voicedtmfmode | Use DMTF mode SIP Info, RTP or inband for SIP calls |
| voiceext1 | Simple answering machine or processing incoming voice calls |
| voiceext2 | CTI-sample for voice processing and call transfer |
| voiceinsetvolume | Streaming audio with volume control |
| voiceinsimple | Answering machine |
| voiceonleasedline | Streaming audio data on leased lines |
| voiceoutsimple | Announcement machine |
| voicesetsipheader | Add SIP header to outgoing SIP messages and report specific SIP header from incoming SIP messages. |
| voicewithdatacodec | Use compression codecs for audio in the data channel |
| Directory | Sample Description |
|---|---|
| FaxServer | Inbound fax server to answer calls on one or all line devices. Store received fax document in TIFF format and write journal file with information on called and calling numbers, amount of pages and used speed. |
| ShowDevices | Simple application that prints out the information of one or all line devices. |
| SimpleApp | Simple voice application to service one incoming or outgoing call. |
| SimpleIVR | Voice application that answers incoming calls on one or all line devices, plays audio prompts for different menus, navigates via detected digits into sub menus or transfers the call to an operator. |
| VoiceReminder | Voice application that dials out, detects answering machines or human talker and leaves a voice message. |
| VoiceVAD | Simple voice application that answers incoming calls and prints VAD and human talker detection results. |
To use the Diva SDK in your application you have to include the header 'dssdk.h' in the source files (and 'smssdk.h' if you use SMS functionality) and link your application with either the static library 'libDivaS.a' or the shared library 'libDivaS.so'. Because the Diva SDK uses threads internally, the pthread library must be linked additionally.
For details how to compile and link your application please have a look at any of the samples provided with the Diva SDK. In every sample subdirectory you will find a makefile, that describes the compilation and link process of that application. The evaluation of the makefile requires some knowledge of shell scripting and makefile syntax and is beyond the scope of this document.
The Diva SDK accesses the Diva Media Boards and Diva softIP Virtual Board via two devices:
The Diva SDK for Linux supports Diva Media Boards and Dialogic HMP. For information on installing and starting Dialogic HMP refer to the "Dialogic Host Medial Processing Software Release 3.1 Linux" documentation.
The Dialogic HMP software is delivered with a demonstration license for one channel. This license allows for making a voice call on one channel using H.323 or SIP. If you need more than one channel, you need to request a license from Dialogic. For information on obtaining and activating a license refer to the "Dialogic Host Medial Processing Software Release 3.1 Linux" documentation.
The Diva SDK is installed as described above under "Installation".
By default, the Diva SDK automatically detects all installed Diva Media Boards and the Dialogic HMP software. For all Diva Media Boards, the configuration is done via the configuration delivered with the Diva System Release software. For the Dialogic HMP software, the default configuration is the following:
The Diva SDK allows for overwriting the existing defaults with a configuration file. The configuration file is XML-based, needs to be named "dssdk.xml", and needs to reside in the directory "/etc". A default configuration file is installed at "usr/share/doc/packages/dssdk-gccxx".
The Diva SDK supports multiple line devices, which are the E1/T1 trunks or the BRI interfaces of the Diva Media Boards. For the Dialogic HMP software, a line device can support either SIP or H.323, and multiple line devices can be configured, e.g., multiple devices using SIP but different proxy server.
The format of the XML files is shown in the Samples for configuration files below. The tables below provide the information about the configuration options.
Note: The common parameters and the H.323 gatekeeper parameters can only be specified once. The SIP registrar parameters may be specified for multiple registrar servers.
| Name | SIP/H.323 | Description |
|---|---|---|
| NetworkInterface | SIP/H.323 | Specifies the IP address to be used. If this field is empty, the default IP address is used. |
| Channels | SIP/H.323 | Specifies the amount of channels for this line device. The channels for all configured line devices must not exceed the amount of licensed IP channels. By default, the licensed channels are used. |
| SignalingProtocol | SIP/H.323 | The signaling protocol is either SIP or H323. By default, SIP is used. |
| SignalingPort | SIP/H.323 | If the default port should not be used, specify the port. The default depends on the signaling protocol. |
| SignalingTransportProtocol | SIP/H.323 | Either UDP or TCP, the default is UDP. |
| FaxEnableClearChannel | SIP/H.323 | If set to YES, the clear channel fax mode is enabled. By default, only T.38 is enabled. The application can overwrite this parameter on a per call base. |
| OutboundInitialMediaVoice | SIP/H.323 | If the switch does not support T.38 as initial media, but the application dials with fax immediately, the calls would fail. If this option is set to yes, the Diva SDK will initiate the call as voice first and then switch to fax. This allows existing applications to run unchanged. |
| IgnoreAlertRequest | SIP/H.323 | If the option IgnoreAlertRequest is enabled, a call to DivaAlert done by the application is ignored. This allows existing applications sending alerts to run in environments where proxy or gatekeeper run into problems with alerting. The default value is NO. |
| ProxyIPAddress | SIP | Optional parameter, specifies the IP address of a proxy server. If set, the host name is ignored. |
| ProxyPort | SIP | Optional parameter, specifies the port of a proxy server. |
| ProxyHostname | SIP | Optional parameter, specifies the host name of a proxy server. It is used only if the ProxyIPAddress is not set. |
| ProxyUser | SIP | User name for authentication at the configured SIP proxy server. |
| ProxyPassword | SIP | Password for authentication at the configured SIP proxy. |
| ProxyRealm | SIP | Realm for authentication at the configured SIP proxy. Only necessary if different from the proxy domain. |
| AutoDiversion | SIP | If set to YES, the Diva SDK will handle the diversion implicit. By default, no diversion is done and the request is rejected. The application can overwrite this parameter on a per call base. |
| MaxRegistration | SIP | Specifies the maximum amount of registration at registrar servers. |
| EnableTransparentAddresses | SIP | The parameter specifies how SIP addresses of incoming calls, for which no mapping is found, are passed to the application. If set to "YES", the addresses are passed unchanged to the application. If set to "NO", the system will try to extract the number information and pass it to the application. The default value is "NO". |
| DefaultFromAddress | SIP | The parameter DefaultFromAddress specifies the local address to be used for SIP-based calls if the application does not specify a local or calling number for an outgoing call. The address must be a valid SIP address. |
| GatewayIPAddress | H.323 | Optional parameter of an H.323 gateway. If specified, all requests that do
not contain the TA: |
| GatewayPort | H.323 | Optional parameter, specifies the port number of the H.323 gateway. |
| H245ChannelOptional | H.323 | The parameter H245ChannelOptional specifies that the H.245 channel establishment is optional in fast start connections. The default value is NO. |
| H323MediaWaitForConnect | H.323 | The parameter H323MediaWaitForConnect specifies that no fast start is enabled. Therefore the media is established after the signaling. |
| Name | Description |
|---|---|
| RegistrarAddress | IP address of the registrar server. IP address and port name of full name for optional port. |
| UserID | User part of SIP address used for "From:" and "To:" fields. |
| Domain | Domain part of the users public SIP address. |
| Password | Password for the authentication at the registrar server. |
| AuthorizationUser | If a different user name than the one specified for the UserId is required for authentication, it must be specified here. |
| AuthorizationRealm | Realm used by the registrar server when authentication is requested. If the registrar uses the domain name as realm, this parameter can be left empty. |
| DisplayName | Optional name used for the registrar request. This parameter can be left empty. |
| AutoRefreshInterval | Time for re-registration in seconds. The default is 3600 seconds. |
| Name | Description |
|---|---|
| GatekeeperAddress | The address or name of the gatekeeper. This may be an IP address with or without the port number or a DNS name. |
| EndpointType | Endpoint type with possible values "Terminal" or "Gateway". |
| Aliases | The H.323 aliases for this endpoint, which need to be separated by a comma. The names may contain spaces. |
| Prefixes | Prefixes according to H.323. Only valid for the EndpointType "Gateway". |
| Number | Specifies a comma separated list of numbers that should be routed to this endpoint. |
| Name | The name specifies the H.323 ID. |
| AutoRefreshInterval | Specifies the time for re-registration in seconds. The default is no repetition. |
For compatibility with existing applications, the Diva SDK allows for mapping phone numbers
to SIP or H.323 addresses. For each device, multiple MAP entries can be added, which have the following syntax:
<Map>
<Number>123</Number>
<Address>sip:joe.smith@cia.org</Address>
</Map>
The codecs can be selected by the application or preconfigured in the dssdk.xml file. To pre-configure codecs a "Codec" section for each enabled codec must be added. By default, G711_ALaw and G711_ULaw are enabled; if a fax license is available, also T38 is enabled. The following table shows the parameter for a codec configuration.
| Name | Description |
|---|---|
| Capability | The symbolic name of the codec. Valid options are:
|
| Direction | Specifies in which direction the codec should be offered or negotiated. Valid options are:
|
| FrameSize | Specifies the frames size or the frames per packet depending on the codec. If a zero is entered all valid frame sizes or frames per packet options are enabled. |
If the Diva System Release software is installed the Diva SDK tracing options are configured via the configuration delivered with the Diva System Release software. If the Diva SDK is installed on a system, with only Dialogic HMP, the configuration for the tracing options is done via the file /etc/dssdk_cfg.rc. A default configuration file is installed at "/usr/share/doc/packages/dssdk-gccxx" for RPM based systems and at "/usr/share/doc/dssdk-gccxx" for Debian based systems.