Plantronics Developer Connection - plantronics

Advanced SDK Topic: Ensuring Resilience with Plantronics COM API

lcollins — Thu, 27 Apr 2017 10:02:55 +0000

Keywords:

resilience resilient COM API plantronics SDK

Author: Lewis Collins, Plantronics

When using the Plantronics COM API how do you ensure the connection to the Plantronics Hub software is working?

What if the user accidentally shuts down Plantronics Hub (or it crashes), or user upgrades it which would also result in it shutting down and starting again. Would your software re-connect to the COM API automatically?
What if Plantronics Hub is not installed, will your software still attempt to connect to it, resulting in long COM timeout? (Will this timeout impact your applications performance)?

On this page I present a solution to these problems that ensures resilience of connection to Plantronics COM API covering the scenarios mentioned above.

The approach is as follows:

Move all the code that connects / interacts with Plantronics COM API into a seperate class with its own thread. Now Plantronics COM API interaction is done on its own thread it will not impact your application's performance even if a COM timeout / exception occurs. This class is called HubSDKConnector.
In HubSDKConnector add a watchdog timer that polls (attempts to use) the COM API every 5 seconds. If the connection fails (exception occurs) it will attempt to re-establish connection. Note, this interval is slowed to 60 seconds if HubSDKConnector detects that a Plantronics Hub upgrade is in progress (Hub installer is running). This corner case allows user to upgrade Hub without your application attempting to request COM API again, which would respawn the Hub EXE before install operation completes, therefore requiring a reboot to complete install - this is not desirable

Code for this sample: click here>> (note: you must be registered and signed in to access this).

The code is functionally the same is as the basic C# sample (in Get Started, C# Tab), with the integration code moved into HubSDKConnector.cs. The code is in C#, but the same concept could be implemented in C++ with the Plantronics COM API.

Here is a screenshot of it running.

What do you think of this solution? Let me know your feedback or questions using the form at the bottom of the page. Have fun! :-)
Lewis.

ResilientPLTDemo.png

Integrate Plantronics REST API from Go

lcollins — Thu, 01 Sep 2016 12:06:32 +0000

Keywords:

go SDK API REST plantronics

Greetings!

I have recently created an example integrate from the Go language to the Plantronics REST API.

It is still a work in progress but it is functional for receiving device, session and session manager events. (For further guidance on the REST Service API URLs you can use, check out the Java and JavaScript integration samples elsewhere on this site).

Obtain Go language (golang) from here: https://golang.org/

Obtain the sample code from here: http://developer.plantronics.com/system/files/plt%20go%20sample.zip
Note: you must login to this site to download that file.

Here is how you connect to Plantronics from Go (code snippet):

func httpGetJSON(url string) (map[string]interface{}) {
    var dat map[string]interface{}
    resp, err := http.Get(url)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()
    if b, err2 := ioutil.ReadAll(resp.Body); err2 == nil {
        if err := json.Unmarshal(b, &dat); err != nil {
            log.Fatal(err)
        }
    }
    return dat
}

func connectToPlantronics() {
    fmt.Print("Connecting to Plantronics...\r\n")
    var jsondata map[string]interface{} = httpGetJSON("http://127.0.0.1:32017/Spokes/DeviceServices/Attach?uid=0123456789")
    fmt.Print("\r\nSession ID:\r\n\r\n"+jsondata["Result"].(string)+"\r\n\r\n")
    sessionId = jsondata["Result"].(string)
    
    var result string = httpGet("http://127.0.0.1:32017/Spokes/SessionManager/Register?name="+pluginName)
    fmt.Print("\r\nResult:\r\n\r\n"+result+"\r\n\r\n")
    pluginRegistered = true
    
    go eventsListenerThread(sessionId,pluginName)  // start monitoring events after connect to api
}

Below is a picture of the code in action, having received a "Don" event (when I put on the Plantronics headset)...
Have fun!
Lewis.

go sample.png

Using Plantronics SDK from Java

lcollins — Thu, 05 Nov 2015 12:40:30 +0000

Keywords:

Java plantronics SDK integration REST Service API

*Update 22nd Jan 2016*: Since the SDK version 3.7.x, you can now optionally use https:// port 32018 in addition to http:// on port 32017! (however for https you may need to manually deploy the self-signed certificate if using Firefox or Java).

Sample code:
Download this sample code as a ZIP

String tmpResult =
    RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/DeviceServices/Attach?uid=0123456789"
);

This code requires the convenience function SendRESTCommand (available in the sample code ZIP).

0123456789 is a magic uid which tells the REST Service API to attach to the "primary" Plantronics device (primary device is settable via the Plantronics Hub user interface, in the case you have more than one Plantroncis device attached to your PC).

Now we can examine the tmpResult variable to see if the attach was a success.

int pos = tmpResult.indexOf("\"Result\":\"");
if (pos>-1)
{
    tmpResult = tmpResult.substring(pos+10);
    pos = tmpResult.indexOf("\"");
    if (pos>-1)
    {
        tmpResult = tmpResult.substring(0, pos);
        System.out.println("Session id is: " + tmpResult);
        sessionid = tmpResult;
    }
}

This code is extracting the sessionid from the HTTP response. We need that later for some of the other REST Service API commands. Note, the HTTP response is in fact JSON, so it would be better to parse with a JSON parser, but I haven't adopted a suitable JSON parser yet...

After a short delay we can go ahead an register a REST Service API plugin. The plugin is needed for some of the call control commands.

try
{
    Thread.sleep(250);
}
catch (InterruptedException ex)
{
    Logger.getLogger(PlantronicsRESTDemo.class.getName()).log(Level.SEVERE, null, ex);
}                                  
if (sessionid.length()>0)
{
    RESTConvenienceClass.SendRESTCommand(
        "http://127.0.0.1:32017/Spokes/SessionManager/Register?name=My%20Java%20Plugin"
    );               
    pluginRegistered = true;
}

Now we are able to poll for device events using further REST Service API commands, like this:
(Note: the sessid and plugin_name need to match what we registered earlier).
The contents of the responses we get back tell us lots of information, such as when user has answered a call with headset, mutes a call, takes headset off, etc.

RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/DeviceServices/Events?sess="
        + sessid
        + "&queue=0"
)
RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/CallServices/Events"
);
RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/CallServices/SessionManagerCallEvents?name="
        + plugin_name
);

Finally we can control the headset by telling it when we are going on a call, for example:
An incoming call (pass an integer callid, used to refer to this call during its lifecycle, and pass an optional caller name for Plantronics' display device products):

callid = callid + 1;
caller_name = "Bob%20Smith";
RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/CallServices/IncomingCall?name=My%20Java%20Plugin&callID=%7B%22Id%22%3A%22"
        + callid
        + "%22%7D&contact=%7B%22Name%22%3A%22"
        + caller_name
        + "%22%7D&tones=Unknown&route=ToHeadset"
);

End the call:

RESTConvenienceClass.SendRESTCommand(
    "http://127.0.0.1:32017/Spokes/CallServices/TerminateCall?name=My%20Java%20Plugin&callID=%7B%22Id%22%3A%22"
        + callid
        + "%22%7D"
);

For more examples and to see a complete Java implementation, download the sample code ZIP.

Here is a screeshot of the sample code in action running under NetBeans IDE:

false

Have fun!