Author: Lewis Collins, Plantronics
 

Introduction


This article is a guide to the development, test, and deployment of integrating the Plantronics desktop SDK into your softphone.
 
  1. Please goto http://developer.plantronics.com/ and become a registered member
  2. Download the SDK based on your environment http://developer.plantronics.com/sdks
  3. Follow the approaches we recommend in the next sections of this article particularly in terms of API choice and deployment method
  4. Refer to the API Overview: http://developer.plantronics.com/api-overview
  5. Refer to the new sample codes: http://developer.plantronics.com/article/get-started-code-samples
  6. Refer to the API specification: http://developer.plantronics.com/api-specification-doc
  7. Refer to the example test cases linked at the end of this document (see Example Test Cases section) that should be executed and passed.


Recommended integration approach

We offer 4 APIs within the SDK, as follows: COM, COM .NET, REST and Native Library (Spokes.dll/Spokes.so).

Use if the standalone library approach Native Library (Spokes.dll) is now discouraged.

Benefits of COM, COM .NET and REST APIs over Native Library (Spokes.dll)
This is because the 3 other APIs we offer (COM, COM .NET and REST) provide several key benefits over the Native Library approach:
  • Allows your solution to work with Plantronics Manager Pro (Read more here!)
  • Support multi-softphone configurations
  • Support multi-device configurations
  • Makes deployment easier, avoiding potential version conflicts between Native Library and Plantronics Hub
    • Spokes.dll is used by Hub itself, so if customer deploys a partner solution with Spokes.dll as well as Hub, the 2 separate instances of Spokes.dll are talking to the same headset - this can in some circumstances lead to interference.


Deployment options

Regardless of which API you choose there are 2 deployment options to choose from: Plantronics Hub or Plantronics SDK minimal runtime (the redistributable packages), discussed here:
http://developer.plantronics.com/api-overview#second 

Note: we do not recommend "hand-picking" files from the deployment, but rather to use the standard packages (MSI on Windows, .pkg on Mac), or advise end-user to download Plantronics Hub from www.plantronics.com/software to enable the integration.

Full details on the distribution packages can be read here: http://developer.plantronics.com/article/plantronics-sdk-3x-deployment-options


New sample codes!

We have some new samples codes to ensure you can integrate very efficiently! Here are the links and some information about them:


Key points to consider for a successful integration


For REST API:

  1. Device unplug/replug support: If you unplug/replug the Plantronics headset the REST API session that your application was using will become invalid. In order to fix this your application needs to detect this state and release and attempt the re-register the device session.
  2. Resilience: If Plantronics Hub quits, crashes, is upgraded or is exited/killed by user, your integration will lose connection. It is possible to poll for reconnect so when user restores Plantronics Hub, the call control can continue working.


For COM API:

  1. Device unplug/replug support: SpokesSDKCOMNETSample that is included with the SDK download does not illustrate device unplug/replug support. If you unplug/replug the Plantronics headset, SpokesSDKCOMNETSample will not reconnect and call control will stop working.
  2. Ensure you use the IncomingCall/OutgoingCall/AnswerCall methodology to program the call control, with the COMSession onCallStateChanged events indicating to your softphone that user has answered/ended the call via headset.
    • Do not rely on button events, such as Talk button, etc, as this would not work in Plantronics multi-line product, e.g. Savi 700 Series.
    • To tell the headset you have an incoming call use the COMCallCommand.IncomingCall method rather than the COMHostCommand.SetRing command, because the latter only turns on the ring signal, it does not inform Plantronics of the new call and is therefore not compatible with Plantronics call switching and multi-softphone features
  3. All calls to Plantronics COM .NET API must be done from the same thread.
  4. Is Hub installed? If Plantronics Hub is not installed when you attempt to connect COM .NET API this could result in a long timeout, e.g. 60 seconds.
    • There are 2 approaches to avoid this problem:
      • Check for presence of this key before attempt to connect:
        • (for 64 bit machine) HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{750B4A16-1338-4DB0-85BB-C6C89E4CB9AC}\LocalServer32
        • (for 32 bit machine) HKEY_CLASSES_ROOT\CLSID\{750B4A16-1338-4DB0-85BB-C6C89E4CB9AC}\LocalServer32
        • If none of these keys exist then do not connect. 
        • Below is a C# example code to perform this check...
          OR:
      • Do the connection and all Plantronics COM .NET API interaction on a separate thread, then the timeout does not impact your other application thread…
  5. Resilience: If Plantronics Hub quits, crashes, is upgraded or is exited/killed by user, your integration will lose connection. It is possible to automatically re-connect to the COM .NET API in these scenarios (connection resilience). We have the sample of this here:


C# code to check if Hub COM API is installed

using System;

namespace HubDetectExample
{
    class Program
    {
        static void Main(string[] args)
        {
            if (IsPlantronicsHubInstalled())
            {
                Console.WriteLine("Plantronics Hub is installed");
            }
            else
            {
                Console.WriteLine("Plantronics Hub is not installed");
            }
            Console.WriteLine("Press enter to continue...");
            Console.ReadLine();
        }

        private static bool IsPlantronicsHubInstalled()
        {
            bool foundCOMSessionManagerKey = false;

            Console.WriteLine("About to look see if Plantronics Hub COMSessionManager is in registry");
            try
            {
                // reg keys of interest...
                string Hub3xKeyName = @"Plantronics.COMSessionManager\CLSID";
                string Hub3xSubKeyName = @"{750B4A16-1338-4DB0-85BB-C6C89E4CB9AC}";

                // open key
                Microsoft.Win32.RegistryKey Hub3xKey = Microsoft.Win32.Registry.ClassesRoot.OpenSubKey(Hub3xKeyName, false); // non writable

                // is Plantronics Hub 3x installed?
                if (Hub3xKey != null)
                {
                    if (Hub3xKey.GetValue(null) != null)
                    {
                        // did we find Plantronics Hub 3x COMSessionManager sub-key?
                        if (Hub3xKey.GetValue(null).ToString() == Hub3xSubKeyName)
                            foundCOMSessionManagerKey = true;
                    }
                    Hub3xKey.Close();
                }
            }
            catch (Exception e)
            {
                Console.WriteLine("An exception was caught while looking to see if Plantronics Hub COMSessionManager is in registry.\r\nException = " + e.ToString());
            }

            return foundCOMSessionManagerKey;
        }
    }
}
 

Example Test Cases

How do you know when your integration works well? We have uploaded an example "basic test suite" of tests you can run to check your Plantronics headset integration is working as expected! Here is the link to the test suite: http://developer.plantronics.com/system/files/BasicTestSuite.xlsx


Get in touch!

We would love to hear from you with any questions, comments or feedback. Please use the forums to get in touch!
Good luck!
News Articles Classification: