Plantronics Developer Connection - REST

HubRESTSample – a new C++ REST API Sample for PDC

lcollins — Tue, 06 Jun 2017 14:00:33 +0000

Keywords:

C++ REST API Hub Manager Pro

This new sample code illustrates seamless consumption of Plantronics out-of-proc REST API from C++ code!

Location of full sample code: https://github.com/pltdev/pdc/tree/master/C%2B%2B%20REST%20Sample

Key Benefits

Supports Plantronics Manager Pro configuration
- Works with Plantronics Hub via “out-of-proc” REST API
Supports multi-softphone & multi-device configurations
Same code for both Windows and Mac environments
Follows same model as the other PDC samples for C#, Java, JavaScript, etc
- Providing clear illustrations of basic call control
Illustrates support for resilience to Hub restarting and device changing

Design Overview

The design of the sample uses a threaded (active) object called HubRESTLib, that handles all the REST HTTP requests and resilience (reconnects). It allows Hub SDK commands to be issued and events from Hub SDK to be received via the callbacks of the IHubRestLib interface.

HubRESTSample 1.png

*POCO Libraries were used in this sample for HTTP requests and JSON parsing functionality, but any libraries could be used

The sample code in action…

Note: with this integration sample it is just 1 line of C++ code to connect to Plantronics REST API (instantiate HubSDKConnector object), and 1 line of code to cleanup (delete the object).

Once instantiated you are then able to submit API commands (e.g. IncomingCall, etc) to this object using a HubSDKAction object, as shown below. Some of the actions take parameters, e.g. callid, etc:

Note: you will need the full sample code to use this, obtain from here: https://github.com/pltdev/pdc/tree/master/C%2B%2B%20REST%20Sample

#include <iostream>
#include <string>
#include "HubSDKConnector.h"

using namespace std;

void ShowMenu()
{
	cout << endl;
	cout << "plt sample menu" << endl;
	cout << "--" << endl;
	cout << "1 - ring/incoming call" << endl;
	cout << "2 - outgoing call" << endl;
	cout << "3 - answer call" << endl;
	cout << "4 - hold call" << endl;
	cout << "5 - resume call" << endl;
	cout << "6 - mute call" << endl;
	cout << "7 - unmute call" << endl;
	cout << "8 - end call" << endl;
	cout << "0 - quit" << endl;
	cout << endl;
	cout << "> ";
}

int GetCommand()
{
	string cmdstr;
	int cmd;
	getline(std::cin, cmdstr);
	if (cmdstr.empty()) cmd = -1;
	else
	{
		try
		{
			cmd = atoi(cmdstr.c_str());
		}
		catch (exception const & e)
		{
			cout << "error : " << e.what() << endl;
			cmd = -1;
		}
	}
	return cmd;
}

int main()
{
	cout << "C++ Plantronics Hub REST Sample" <<  endl;
	bool quit = false;
	int callid = 0; 

	HubSDKConnector * hubSDK = new HubSDKConnector(); // Connect to the Plantronics REST API

	while (!quit)
	{
		ShowMenu();
		int cmd = GetCommand();
		HubSDKAction action;
		switch (cmd)
		{
			case 1:
				callid++;
				// inform Plantronics my app has an incoming (ringing) call
				cout << "Performing incoming call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_IncomingCall;
				action.callid = callid; // numeric id to uniquely identify each call
				action.contactname = "Bob%20Smith"; // optional contact name for display devices, e.g. Calisto 240, note: needs url encoding e.g. spaces are %20, etc.
				hubSDK->DoHubSDKAction(action);
				break;
			case 2:
				callid++;
				// inform Plantronics my app has an outgoing call
				cout << "Performing outgoing call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_OutgoingCall;
				action.callid = callid;
				action.contactname = "Bob%20Smith";
				hubSDK->DoHubSDKAction(action);
				break;
			case 3:
				// inform Plantronics my app has now answered an incoming (ringing) call
				cout << "Answering call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_AnswerCall;
				action.callid = callid;
				hubSDK->DoHubSDKAction(action);
				break;
			case 4:
				// place call on hold
				cout << "Holding call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_HoldCall;
				action.callid = callid;
				hubSDK->DoHubSDKAction(action);
				break;
			case 5:
				// resume the call
				cout << "Resuming call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_ResumeCall;
				action.callid = callid;
				hubSDK->DoHubSDKAction(action);
				break;
			case 6:
				// mute the headset (note for wireless products, audio link must be active)
				cout << "Setting headset mute = true";
				action.ActionType = HubSDKActionType_SetMute;
				action.mutestate = true;
				hubSDK->DoHubSDKAction(action);
				break;
			case 7:
				// unmute the headset (note for wireless products, audio link must be active)
				cout << "Setting headset mute = false";
				action.ActionType = HubSDKActionType_SetMute;
				action.mutestate = false;
				hubSDK->DoHubSDKAction(action);
				break;
			case 8:
				// inform Plantronics my app has now terminated the call
				cout << "Terminating call, id = " << callid << endl;
				action.ActionType = HubSDKActionType_TerminateCall;
				action.callid = callid;
				hubSDK->DoHubSDKAction(action);
				break;
			case 0:
				quit = true;
				break;
			default:
				cout << "Unrecognised menu choice." << endl;
				break;
		}
	}

	delete hubSDK; // Cleanup the Plantronics REST API

	return 0;
}

View of the application running:

It presents a menu allowing you to try out the basic call control commands, and see connection information and notifications from Plantronics Hub and the headset:

HubRESTSample 3.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!