Jabra SDK Wrapper for Windows User Guide

Revision History

Revision Date Description
2.1 15-11-2018 Updated firmware update and added RemotemMMIv2 interfaces
2.0 09-10-2018 Updated 'Not Supported' interfaces
1.9 05-10-2018 Added deprecated interfaces
1.8 28-09-2018 Updated bluetooth adapter interface names
1.7 27-09-2018 Removed load and save settings interfaces
1.6 25-09-2018 Removed lock references in interfaces
1.5 12-04-2018 Updated ringtone, image upload and set date and time interfaces
1.4 11-12-2017 Updated the firmware update and load and save settings interfaces
1.3 01-12-2017 Version update
1.2 16-06-2017 Version update and corrections
1.1 18-04-2017 Updated the Device, Bluetooth Adapter, Button Events and Settings Interfaces
1.0 22-03-2017 Initial version covering Jabra SDK Wrapper

Introduction

Purpose

The purpose of this document is to give an overview of the Jabra SDK Wrapper for Windows and explain how it can be used to integrate Windows applications with Jabra headsets.

Target Audience

The target audience for this document is software developers and the reader of this document is assumed to be familiar with C#, the .NET framework, and Microsoft Visual Studio.

Abbreviations and Acronyms

Acronym Description
API Application Programming Interface
DLL Dynamic Link Library
HID Human Device Interface
SDK Software Development Kit
USB Universal Serial Bus
WPF Windows Presentation Foundation

In this document the term "Jabra device" refers to a Jabra device that can be used for telephony, such as headsets, handsets, and speakerphones.

Overview

Supported Environments

The Jabra SDK V2 provides managed APIs for Jabra devices. This SDK can only be used by Windows Desktop applications, not intended for Windows Store Apps.

The purpose of this SDK is to provide telephony integration for Jabra USB connected devices. The SDK provides properties, methods, and events required for reading and writing the call state of a Jabra device. This SDK is used to integrate softphones, and other VoIP applications, with a Jabra device in order to provide: remote call control, device settings, details for Bluetooth adapters, busylight features, and remote MMI features. Remote call control allows users to control a softphone call using the buttons on a Jabra device (for example, answer, end, reject, mute, unmute, hold, resume a call). Also, incoming softphone calls are indicated on the device (for example, by a flashing light and/or a ringtone).

The SDK can be used on Windows 7 or later.

Compatibility with Previous SDKs

This SDK replaces the telephony SDK that was shipped with Jabra Direct. The device API in this SDK is almost identical to the device API in the Jabra Direct SDK, so the transition to the new SDK is easy.

Prerequisites

The prerequisites for the SDK are:

  • Microsoft .NET Framework version 4.5 Client Profile.

(Download URL: https://www.microsoft.com/en-us/download/details.aspx?id=30653)

The sample applications are provided as Visual Studio 2015 solutions. They can be built with the free edition of Microsoft Visual Studio Community.

(Download URL: http://www.visualstudio.com/en-us/products/visual-studio-community-vs)

Installation

The SDK Wrapper is provided as a single ZIP archive or as a NuGet package. No installation is required - just unpack the archive to a local folder on your hard disk.

Using Wrapper DLL

The Native C++ DLL (Libjabra.dll) supports only x86 and x64 platforms. So, the Managed wrapper DLL (JabraSDK.dll) can only be used on x86 and x64 platforms. When creating applications using Wrapper DLL (JabraSDK.dll) as NuGet package, make sure to set the platform as x86 or x64.

Contents of the SDK

After unpacking, the target folder contains these files and folders:

File Description
readme.txt Provides information on Jabra SDK
library\Nuget\JabraSDK.x.x.xx.nupkg Nuget package(where x.x.xxx) is the version number of the package
library\[platform]\libjabra.dll Jabra SDK dynamic library for platform (x86 and x64)
doc\Jabra DotNet SDK API.chm Doxygen generated API documentation for Wrapper
doc\DotNet User Guide.html Wrapper User Guide and API documentation
doc\ReleaseNotes.txt Release information
Demo\src Source code for a demo application

Integration with Jabra Direct

The SDK has no dependencies on Jabra Direct. However, it offers an optional integration with Jabra Direct with following benefits:

  • The name and status of the integrated softphone is shown in the Jabra Direct home screen and dashboard.

  • The integrated softphone can be selected as "Preferred Softphone" in Jabra Direct.

  • The integrated softphone can be set "in focus" by Jabra Direct

A softphone integrated using this SDK wrapper will appear the same as softphones natively supported in Jabra Direct.

To integrate with Jabra Direct you should install Jabra Direct. Jabra Direct can be downloaded from www.jabra.com

Deprecated APIs

Below is a list of APIs which are deprecated from this version of SDK wrapper.

  • Lock
  • Unlock
  • IsLocked
  • IsLyncCompliant

Below event handlers are deprecated

  • DeviceRemoved
  • ButtonInput
  • BatteryStatusChanged

Not Supported APIs

Below is a list of APIs which are not supported or implemented for this version of SDK wrapper. The user will get a default value for not supported APIs. This is done so there is backward compatibility between the earlier and later versions of the SDK.

  • Get functionality not supported:
    • AudioDeviceName
    • IsLineBusySupported
    • IsAudioLinkOpen
    • IsMicrophoneMuted
    • IsRinging
    • IsOffHook
    • IsOnHold
    • IsCommunicationLinkOpen
    • HasProprietaryHidTelephonyInterface
    • IsOutBandRingerSupported
    • IsCallerIdSupported
    • IsOutOfRangeSupported
    • IsMessageWaitingSupported
    • IsQdConnectionStateSupported
    • IsJackConnectionStateSupported
    • IsCommunicationLinkSupported
    • IsLineBusy
    • IsOutOfRange
    • IsHeadsetDocked
    • IsHeadsetQdConnected
    • IsHeadsetJackConnected >Note: All the above APIs will return default values.
  • Get and Set functionality not supported:
    • UseInBandRinger
    • SetCommunicationLinkState(bool linkOpen)
    • SetRinger(bool ringing, string callerId)
    • SetRinger(bool ringing, bool noRingTone)
    • SetCallerId(string callerId)
    • SetMessageWaiting(bool msgWaiting)
    • GetPhoneNumber(PhoneNumberId id)
    • SelectProprietaryHidTelephonyInterface()
    • AudioInputDeviceName
    • AudioOutputDeviceName
    • CallControlDeviceName

Note: All the above APIs will throw exceptions. So, handle the exception in your code.

  • Event handlers not supported:
    • StateChanged
    • FocusChanged

Using the SDK

Getting Started

Unpack the SDK to a folder on your hard disk. To build, Community Edition of Visual Studio is sufficient.

After reading this User Guide you are ready to browse and build the sample code.

Referencing the API Assembly

The Assemblies folder in the SDK contains the JabraSDK.x.x.xxx.nupkg or JabraSDK.dll with libjabra.dll assembly that comprises the API.

There are two ways to use the API from your .NET application:

  1. Use as Nuget package - Add the JabraSDK.x.x.xxx.nupkg using "Manage Nuget Packages..." from Visual studio project solution. The user can create their own Nuget server, and copy the same to that server folder, and then add it to the project.
Install-Package JabraSDK -Source \"\<Server Path\>\" -Version x.x.xxx
  1. Add a reference to the JabraSDK.dll assembly and copy the libjabra.dll to the Debug or Release folder.

Building the Sample Applications

The SDK includes these one WPF sample applications with source code:

  • Demo Application: This application has a rich UI that enables you to test most of the features of the API.

Sample application has a Visual Studio 2015 solution file (.sln) that you must load in Visual Studio.

The next step is to either reference the downloaded NuGet, or change the project reference to the API assembly called JabraSDK.dll and copy the libjabra.dll to the Debug or Release folder.

  1. In Visual Studio, expand the DemoApplication node in the Solution Explorer window.
  2. Expand the References node.
  3. Under References, you see a broken reference to JabraSDK as shown below.
  4. Delete the broken reference to JabraSDK, and then add a new reference where you point to the JabraSDK assembly in the Assemblies folder or Use Nuget to restore the package.

Reference

You should now be able to build the sample application.

Plug in a Jabra device, run the sample applications, and try out the available features. After that you should examine the source code.

The following sections explain the main features and concepts in the SDK.

Service factory

The API provides two central services:

  • Device Service - that handles device discovery.
  • Integration Service - that handles integration into Jabra Direct.

You get an interface to these services from the static ServiceFactory class. Each of these services are explained further below.

Device Service

The Device Service reports available Jabra devices that support telephony. You can access and use the Device Service as shown below.

Device Service

As a mandatory step, user must provide "Client Id" to the SDK while registering the Device Service, failing which, callbacks will not be registered with SDK. The "Client ID" must be obtained by registering to Jabra portal by App developers.

The user will subscribe to FirstScanDone, DeviceAdded, and DeviceRemoved events from Device Service to keep track of connected Jabra devices. Also, the user can subscribe to ButtonConfigurationInput event (provides button inputs from a device supporting Remote MMI), BluetoothPairingList event (provides pairing list details from supported device), FirmwareUpdateProgressInput to know the firmware updater and the firmware file download progress, RawButtonInput and TranslatedButtonInput events (provides button inputs from device) and FileUploadProgressInput event(provides file upload progress).

User needs to subscribe for LoggingEvent to log the events like DEVICE CONNECTED, DEVICE DISCONNECTED, BATTERY STATUS CHARGING, BATTERY STATUS LOW, BATTERY STATUS LEVEL provided by Jabra Device's.

Note: Remember to call IDeviceService.Dispose() when you no longer need the device service and always before terminating your application.

Device Interface

The devices reported by the Device Service are accessed through an interface called IDevice.

This interface exposes properties, events, and methods pertaining to a specific device. The sample applications show how to use the device interface to get and set the telephony state of a device.

Audio Link

For wireless headsets, the radio link between the headset and its base or Bluetooth USB adapter is usually closed if there are no active calls. This is done to preserve battery time. When the radio link is closed, there is no audio path between the headset and its base or Bluetooth USB adapter. If you want audio to and from the headset outside calls, you can manually open and close an audio (radio) link with the method

SetAudioLinkState().

A typical use case for the manual open/close audio link feature is if you want to listen to music in the headset between calls.

Note: Some Jabra headsets can be configured to automatically open an audio link when they detect that audio is streamed from the PC to the headset.

Device Support Features

Device support features are used to control the Jabra device. IDevice interface provides a set of methods which report whether the device is supported.

The methods which report whether the device is supported are:

  • IsHookStateSupported - Indicates whether hook state signaling is supported.
  • IsMicrophoneMuteSupported - Indicates whether the device has microphone mute support.
  • IsCallOnHoldSupported - Indicates whether the device supports call on hold / resume call (aka flash).
  • IsSetBusylightSupported - Indicates whether busylight is supported.
  • IsAudioLinkSupported - Indicates whether the device supports open/close audio link.
  • IsFactoryResetSupported - Indicates whether the device supports Factory Reset.
  • IsButtonConfigurationSupported - Indicates whether the device supports configuring button events.
  • IsInBandRingerSupported - Indicates whether the device can play in-band ringtones (ringtones played by the softphone).
  • IsOutBandRingerSupported * - Indicates whether the device can play out-band ringtones (ringtones generated locally in the headset).
  • IsCallerIdSupported * - Indicates whether the device can show caller ID.
  • IsBatteryStatusSupported - Indicates whether the device can report battery status.
  • IsLineBusySupported * - Indicates whether line busy (in a call) signaling is supported.
  • IsOutOfRangeSupported * - Indicates whether \'out of range\' signaling is supported for a wireless headset.
  • IsMessageWaitingSupported * - Indicates whether the device has a message waiting indicator.
  • IsQdConnectionStateSupported * - Indicates whether the device (controller) can report Quick Disconnect (QD) connection state.
  • IsJackConnectionStateSupported * - Indicates whether the device (controller) can report jack plug connection state.
  • IsCommunicationLinkSupported * - Indicates whether the device supports open/close communication link.
  • IsUploadRingtoneSupported - Indicates whether the device can support ringtone upload.
  • IsUploadImageSupported - Indicates whether the device can support image upload.
  • IsSetDateTimeSupported - Indicates whether the device can support date and time synchronization
  • IsGnHidStdHidSupported - Indicates whether the device supports GN HID and Std HID and able to switch between them.
  • IsFeatureSupported - Indicates whether the device supports provided DeviceFeature.

* Not supported APIs

GetBatteryStatus

Provides the battery status of the supported devices.

GetDeviceImageThumbnailPath / GetDeviceImagePath

Provides the image of the device with resolution of 80x80 and 380x380 respectively.

FactoryReset

Returns the supported device configuration to factory default state.

GetAudioFileParametersForUpload

Returns the details of audio file format for uploading to device.

UploadWavRingtone

Uploads wav ringtone file to device.

UploadImage

Uploads bitmap image file to device.

SetDateTime

Set custom date time or local date time to device.

Bluetooth Adapter Interface

The Jabra Bluetooth adapter interface is used to connect a Bluetooth device with the Jabra Bluetooth adapter. The following methods are available in this interface:

  • ConnectDevice - Connects to Bluetooth device.
  • ConnectDevice - Connects to Bluetooth device using Bluetooth address of supported devices.
  • DisconnectDevice - Disconnects the Bluetooth device from the Bluetooth adapter.
  • IsAutoPairing - Checks whether the pairing status is set to auto mode.
  • SetAutoPairing - Sets the pairing status to auto or vice versa.
  • StartPairing - Starts pairing and connects with the first found Bluetooth device.
  • SearchForDevicesInPairingMode - Starts the search process for nearby Bluetooth devices in pairing mode.
  • ClearPairing - Clears the pairing details from the Jabra Link 360 Bluetooth adapter.
  • GetConnectedDeviceName - Gets the name of the device connected to the Bluetooth adapter.
  • IsPairingListSupported - Indicates whether the Bluetooth adapter supports pairing list.
  • GetPairedDevice - Gives the list of paired devices.
  • ConnectPairedDevice - Connects the Bluetooth adapter to the paired device.
  • DisconnectPairedDevice - Disconnects the paired device from the Bluetooth adapter.
  • ClearPairedDevice - Clears the paired device information from the list of paired devices.

Button Events Interface

The button events interface enables the user to configure Button Events in Jabra devices. IsButtonConfigurationSupported property reports whether the device supports configuration of button events.

The other methods provided by button event interface are:

  • GetConfigurableButtons - Get the list of user configurable button events of the device.
  • SetConfigurableButtons - Updates the user configured button events on the supported device.
  • ResetConfigurableButtons - Clears the user configured button events on the supported device.

Remote MMI v2 Interface

The remote MMIv2 interface enables the user to configure remote MMIv2 events in Jabra devices. IsFeatureSupported property with RemoteMMIv2 feature reports whether the device supports configuration of remote MMIv2 events.

The other methods provided by remote MMIv2 interface are:

  • GetRemoteMmiv2Configurations - Get the supported remote MMIs for the device.
  • IsRemoteMmiv2InFocus - Gets the status of the remote MMI focus.
  • GetRemoteMmiv2Focus - Gets the focus of the Remote MMI specified.
  • ReleaseRemoteMmiv2Focus - Releases the focus of the Remote MMI specified.
  • SetRemoteMmiv2Action - Sets an output action on the Remote MMI.

Settings Interface

The settings interface enables the user to get and set the settings for Jabra devices.

The methods provided in this interface are:

  • GetSettings - Get the settings for the device.
  • SetSettings - Set the settings for the device.

Firmware update interface

Firmware update interface provides methods to upgrade or downgrade the firmware of Jabra devices.

The methods provided in this interface are:

  • IsFirmwareAvailableForUpdate - Check's if firmware update is available for target device.
  • GetLatestFirmware - Get the details of latest firmware available for the target device from cloud.
  • DownloadFirmware - Download the selected version firmware for target device from cloud.
  • CancelUpdate - Cancel the download of the selected firmware for the target device.
  • GetFirmwareFilePath - Get the downloaded firmware local file path for the target device.
  • UpdateDevice - Update the selected firmware for the target device.
  • GetFirmwareErrorDetails - Get the error details if any exception happens during firmware update process.
  • DownloadFirmwareUpdater - Download the latest firmware updater from cloud.
  • GetAllFirmwares - Get the details of all firmwares available for the target device from cloud.

Integration Service

The Integration Service is used to integrate a third-party softphone into Jabra Direct. Use of the integration service is optional, but recommended. By integrating into Jabra Direct you get the following benefits:

  • Your softphone will be listed alongside the softphones natively supported by Jabra Direct.
  • The current status of your softphone is shown in the Jabra Direct home screen and dashboard.
  • Your softphone can coexist with the other softphones natively supported by Jabra Direct.

The integration service uses an inter-process communication (IPC) mechanism based on shared memory to pass status and messages between your application and Jabra Direct.

The integration service, or any other parts of the Jabra SDK Wrapper, do not have any dependencies on Jabra Direct components. So even if you use the integration service, your end-users do not have to install Jabra Direct.

Using the Integration Service

The integration service is accessed through the IIntegrationService interface. You get an instance of this interface by calling ServiceFactory.CreateIntegrationService().

The first thing to do is to connect your application to the integration service by calling ConnectClient(). This method takes three arguments: a globally unique identifier (GUID) for your application, a name, and a version. You can choose the GUID as you like, but make sure it is unique and not reused from another application or from the sample code in the SDK. You should hard-code the GUID in your application so it always connects with the same ID.

Remember to call DisconnectClient() before terminating your application.

Both sample applications in the SDK demonstrate how to use the integration service.

HID Working state

Most Jabra devices have two USB HID Telephony interfaces, a standard USB Telephony interface(Std. HID) defined by the USB Implementers Forum (www.usb.org) and a proprietary telephony interface(GN HID) defined by Jabra and understood only by Jabra applications and SDKs. Softphones with built-in HID telephony support, such as Microsoft Skype for Business (Lync), use the standard telephony interface. Softphones integrated via this SDK or Jabra Direct uses the proprietary telephony interface (if available in the Jabra device).

The purpose of having a proprietary telephony interface is to improve the interoperability between a softphone with built-in HID telephony support (e.g. Skype for Business) and softphones integrated via this SDK or Jabra Direct. When a call is started on a softphone integrated via this SDK or Jabra Direct, the HID events from the device will not be detected by Skype for Business because they are sent on the proprietary interface.

Note:If the Jabra device you use has a proprietary HID telephony interface, and you do not force the device to use the proprietary interface, then HID inputs sent from the device to the PC will be sent on the standard HID telephony interface. For these dual interface Jabra devices, this SDK is only listening for incoming events on the proprietary HID telephony interface, so events received on the standard HID telephony interface is not reported.

Another reason to use the proprietary HID telephony interface is to avoid interference with Microsoft Skype for Business running on the same PC as your softphone solution. Microsoft Skype for Business is communicating directly with Jabra devices via the standard HID telephony interface.

Use GetHidWorkingState to know the current telephony interface of the device and SetHidWorkingState to switch the device to use GN HID telephony interface.

Reporting Status

When you are connected to the integration service you must report your current status by setting these properties on IIntegrationService:

ClientState - Reports whether your application (softphone) is ready for telephony.

AudioInputDeviceName - Reports the name of the audio input (microphone) device used by your application (softphone).

AudioOutputDeviceName - Reports the name of the audio output (speaker) device used by your application (softphone).

CallControlDeviceName - Reports the name of the device your application (softphone) is using for remote call control.

Note: AudioInputDeviceName, AudioOutputDeviceName, and CallControlDeviceName are not supported in this version of Jabra SDK Wrapper.

Setting the AudioInputDeviceName, AudioOutputDeviceName, and CallControlDeviceName is optional but this information is used in Jabra Direct to inform the user if the softphone audio path or call control device does not match a given Jabra device.

Softphone in Focus

An important concept when using the integration service is the softphone in focus. The softphone in focus is a selection done in Jabra Direct. Only one softphone at a time can be in focus. Only the softphone in focus is allowed to react on button inputs from a Jabra device when the device lock has not been acquired (when no calls are active in the softphone).

Whenever the user changes the softphone in focus in Jabra Direct, the new selected softphone in focus is communicated to your application through the integration service property IsInFocus and the FocusChanged (not supported in this version of Jabra SDK Wrapper) event.

The purpose of selecting the softphone in focus is to ensure that only one softphone reacts to a button event from a Jabra device when all softphones are idle. The button event from the device could be an off-hook event to bring the softphone window in focus (and make a dial tone), a last number redial event, or a dialpad key input.

Note: Softphones with built-in HID call control support for Jabra headsets, such as Microsoft Skype for Business (Lync), may not comply with the selected softphone in focus.

Migration from Jabra PC Suite SDK

This SDK replaces the SDK shipped with Jabra Direct. The major differences between this SDK and the earlier SDK are:

Completely standalone - The new SDK can be used on its own. It has no dependencies on Jabra Direct or any other Jabra software installations.

Better integration with Jabra Direct - By utilizing the optional integration service, a third-party softphone application can be integrated to the same extent as the softphones natively supported in Jabra Direct.

The new device interface IDevice in the later SDK is exactly same as the interface IDevice in the earlier SDK.