Click here to Skip to main content
Click here to Skip to main content

Tagged as

Spokes SDK: REST Service

, 7 Jan 2013 CPOL
One of the features in the Spokes SDK is a REST Service that exposes Plantronics device features and call control feature via a RESTful interface.

Editorial Note

This article is in the Product Showcase section for our sponsors at CodeProject. These reviews are intended to provide you with information on products and services that we consider useful and of value to developers.

 

One of the features in the Spokes SDK is a REST Service that exposes Plantronics device features and call control feature via a RESTful interface. The device features exposed by the Spokes REST service includes device command that the host can send to a device, device event (button presses and device state changes). The call control features include a way to notify about incoming /outgoing calls to Spokes, get call state change events and a way to make call via a default Soft phone.

Why REST?

REST (Representational State Transfer) is an architecture style for designing distributed applications. With REST, rather than using a distributed application framework such as CORBA, XML RPC or SOAP to build services, simple HTTP request is used to make calls between a client and a service. REST is a lightweight alternative to other mechanisms like RPC (Remote Procedure Calls) and Web Services (SOAP/ WSDL), as there are no client side proxies or stubs needed and the request response is handled via basic HTTP GET/POST/PUT or DELETE. RESTful applications identify resources with well define URIs and use simple HTTP request for all basic CRUD (Create (POST) / Retrieve (GET)/ Update (PUT) / Delete (DELETE)) operations. The "ST" in "REST" stands for "State Transfer", and in a good REST design operations are self-contained, and each client request carries with it (transfers) all the information (state) that the service needs in order to complete it.

Like Web Services, a REST service is platform-independent, the client and server can be running on different platforms/OS. It is standards-based, as it can run on top of HTTP/HTTPS and can easily be used in the presence of firewalls.

UnLike Web Services and WS-* standards, REST offers no built-in end to end message level security, encryption, session management, transaction and QoS guarantees, etc. In RESTful services, for security, username/password tokens are often used and for encryption REST services can use HTTPS.

The Spokes REST Service plug-in will act as a host for REST service instances. The REST service will expose device service and call service with well know URLs so clients can do simple HTTP POST, GET and get serviced in a RESTful way. The service instance will register for device events such as headset button presses, headset state changes, base/hub/handset button presses, base/hub/handset state changes and ATD state changes (Mobile and PSTN call indications). The service instance will also register for Spokes session level call events such as call state changes and call requested events.

This device service will expose device commands and device events and the call service will expose call commands and call events. Third party business applications, web (via JQuery Ajax post back) or thick client (via simple HTTPWebRequest and HTTPWebResponse) can interface out of process with the Spokes REST Service and communicate with the device and the Spokes runtime engine.

Device Service

The device service will expose URIs for getting a device list, getting metadata about a given device (such as PID, product name, version #, serial #, etc.), send a command to a given device and also query for events from a given device.

  1. Query Device List
  2. http://localhost:port/Spokes/DeviceService/DeviceList

  3. Query Device PID, Name, Version, Serial etc.
  4. http://localhost:port/Spokes/DeviceService/Device#1/Info

  5. Device Commands exposed in IDeviceListener
  6. http://localhost:port/Spokes/DeviceService/Device#1?Ring=true

    http://localhost:port/Spokes/DeviceService/Device#1/Mute

    http://localhost:port/Spokes/DeviceService/Device#1?Mute=true

    http://localhost:port/Spokes/DeviceService/Device#1/AudioState

    http://localhost:port/Spokes/DeviceService/Device#1?AudioState=MonoON

  7. Device Events exposed in IDeviceListenerEvents

    http://localhost:port/Spokes/DeviceService/Device#1/Events

    http://localhost:port/Spokes/DeviceService/Device#1/Events/HeadsetEvents

    http://localhost:port/Spokes/DeviceService/Device#1/Events/BaseEvents

    http://localhost:port/Spokes/DeviceService/Device#1/Events/ATDEvents

Call Service

The call service will expose URIs to query active plugins, send call commands and query call states per registered client, query make call requests and query session manager level call states across plugins.

  1. Query Active plugins

    http://localhost:port/Spokes/CallService/PluginList

  2. Call command exposed in ICallCommand
  3. http://localhost:port/Spokes/CallService/IncomingCall

    http://localhost:port/Spokes/CallService/OutgoingCall

  4. Call events exposed in ICallEvents
  5. http://localhost:port/Spokes/CallService/Client#1/CallEvents

    http://localhost:port/Spokes/CallService/Client#1/CallRequests

  6. SessionManager level events exposed in ISessionManagerEvents
  7. http://localhost:port/Spokes/CallService/Events

NOTE: The URI listed here may not match the ones in the released products so please refer to the Spokes SDK developer guide for more details and there are sample code available in PDC as well.

Following is a simple code snippet to show available devices in a HTML web page Sample 1: Getting Device List via JSON and updating a HTML div in the web page

<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
<title>Device service test web site</title> 
    <script src="js/jquery.js" type="text/javascript"></script>  
     <script type="text/javascript"> 
         var Type;
var Url;
var Data;
var ContentType;
var DataType;
var ProcessData; 
         //Generic function to call Device Service
function CallService() 
         {
$.ajax({
type: Type, // GET or POST or PUT or DELETE verb
url: Url, // Location of the service
data: Data, // Data sent to server
contentType: ContentType,         // Content type sent to server
dataType: DataType, // Expected data format from server
processdata: ProcessData,         // True or False
success: function(msg) { //On Success call
ServiceCallSucceeded(msg);
},
error: ServiceCallFailed //On Failure call
});
} 
function ServiceFailed(result) 
         {
alert('Service call failed: ' + result.status + '' + result.statusText);
Type = null; Url = null; Data = null; ContentType = null; DataType = null; ProcessData = null;
} 
function GetDeviceList() 
         {
Type = "GET";
Url = "http://localhost/Spokes/DeviceService/DeviceList";
            ContentType = "application/json; charset=utf-8";
DataType = "json"; 
             ProcessData = true; 
             CallService();
} 
function ServiceCallSucceeded(result) 
         {
if (DataType == "json") 
             {
resultObject = result.GetUserResult; 
if (result.length <= 0) 
                 { 
                     $("#result").fadeOut('fast', function() {
$("#result").html("NONE");
$("#result").fadeIn('fast');
}); 
                     return;
} 
$('myDiv').load(result); 
                 var output = "";
for (var i in result) 
                 {
output += i +". "+ result[i] + "<BR>";
}            
                 
                 $("#result").fadeOut('fast', function() {
$("#result").html(output);
$("#result").fadeIn('fast');
});  
}         
         } 
function ServiceCallFailed(xhr) 
         {
alert("Service call failed");
} 
$(document).ready(
function() 
            {
                 setInterval(GetDeviceList, 1000); 
            }
);         
    </script>
</head> 
<body>
    <form id="form1" runat="server">
    <p>Devices Found </p>
    <div id="result">
    None
    </div>
    </form>
</body>
</html>

This article was contributed by Ramesh Theivendran. Ramesh has been a member of the Corporate Software development team at Plantronics since October 2007. Currently, he server as the software architect for Plantronics Spokes. Prior to joining Plantronics, Ramesh served as a Principal Architect at Borland International and as a Programmer at the Indian Institute of Technology, Bombay (IITB), INDIA. He has over 20 years of experience in building software tools & SDK for wide variety of distributed applications. Ramesh lives in Scotts Valley, California with his wife, Aruna, and their two daughters, Vineha and Vinusha.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Plantronics

United States United States
Today’s smart devices and applications have untapped potential in the realm of context-aware computing. Plantronics is making it possible for its audio devices to deliver contextual information to a range of applications through Plantronics headsets. The Plantronics Spokes SDK allows developers to create a range of business applications that will have the power to change the way we communicate and collaborate.

Please check out our DevZone for more info on the Spokes SDK:
http://developer.plantronics.com/community/devzone

Comments and Discussions

 
-- There are no messages in this forum --
| Advertise | Privacy | Terms of Use | Mobile
Web02 | 2.8.1411023.1 | Last Updated 7 Jan 2013
Article Copyright 2012 by Plantronics
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid