Spokes SDK: Headset Proximity

Headset Proximity feature in the Spokes SDK allows application developers to query the proximity of their Bluetooth headset with respect to their Bluetooth USB dongle that is connected to the PC.

Spokes SDK developers can access the IHostCommandExt interface by casting the HostCommand property in IDevice. If it returns a valid interface then you can call GetProximity() to request the proximity. If the request is successful GetProximity() will return true otherwise false. The proximity response from the headset will be reported to the host as an async event so application developers have to register for Proximity events by registering either for HeadsetStateChanged event exposed in DeviceListener property of IDevice or by registering for the HeadsetStateChanged event exposed in IDeviceEventsExt. Developers can access the IDeviceEventsExt interface by casting the DeviceEvents property in IDevice. If it returns a valid interface then you can register for HeadsetstateChanged event

Following interfaces IHostCommandExt, IDeviceEventsExt, IDeviceListenerEvents will expose proximity events and a way to request proximity as part of the Spokes SDK. These interfaces can be accessed by applications that directly interface with the device manager or plug-ins that interface with the Spokes SDK.

NOTE: This feature will be supported in Spokes 2.6 SDK and only on a prototype Bluetooth headset. You need an updated version of the Bluetooth dongle and Voyager Pro Bluetooth Headset firmware to experiment with Proximity.

IHostCommandExt Interface

    public interface IHostCommandExt : IHostCommand, IExtendedVersion
{

        bool GetProximity();
        bool EnableProximity(bool bEnable);
}

Method: bool GetProximity()

GetProximity() will send a request to the Plantronics device connected to the USB to get the proximity of the headset. This function returns true if the request is successful otherwise false. On a device that doesn’t support proximity the SDK will throw a DeviceManagerException and applications should handle that exception.

Method: bool EnableProximity(bool bEnable)

EnableProximity() will send a command to the device to enable or disable Proximity reporting from the headset. bEnable = true, enables proximity reporting and bEnable=false disables proximity reporting.

IDeviceEventsExt Interface

     public interface IDeviceEventsExt : IDeviceEvents
{
        ..
        event HeadsetStateEventHandler HeadsetStateChanged;        
          }

IDeviceListenerEvents Interface

    public interface IDeviceListenerEvents
{
        //Headset : Covers Corded, Cordless headsets events
        event DeviceListenerEventHandler HeadsetButtonPressed;
        event DeviceListenerEventHandler HeadsetStateChanged;

        //Base: Covers Base, Hub, Handset events
        event DeviceListenerEventHandler BaseButtonPressed;
        event DeviceListenerEventHandler BaseStateChanged;

        //ATD: Covers Mobile, PSTN and other ATD events
        event DeviceListenerEventHandler ATDStateChanged;
}

Code Snippets

Sample 1: Requesting Headset Proximity

private void radBProximity_Click(object sender, EventArgs e)
{
      try
      {
          if (m_command != null)
          {
              m_command.GetProximity();
          }
      }
      catch (DeviceManagerException ex)
      {
          MessageBox.Show(ex.Message, "Spokes DM SDK");
      }
  }

Sample 2: Registering for Headset Proximity via IDeviceEventExt

IDevice m_device = null;
IDeviceEventsExt m_events = null;
IHostCommandExt m_command = null;
//Get a valid device and init m_device

//Cast HostCommand and init m_command and m_events
m_command = device.HostCommand as IHostCommandExt;
 
m_events = device.DeviceEvents as IDeviceEventsExt;
 
 
//Register for HeadsetStateChanged event on Attach()to the device
 
if (m_events != null)
{
                    
   m_events.HeadsetStateChanged += events_HeadsetStateChanged;       
                   
}
 
//UnRegister for HeadsetStateChanged event on Detach() to the device
 
if (m_events != null)
{
                    
   m_events.HeadsetStateChanged -= events_HeadsetStateChanged;       
                   
}
 
//Event handler for HeadsetStateChanged
void events_HeadsetStateChanged(object sender, HeadsetStateEventArgs e)
{            
   UpdateHeadsetState(e);     
} 
      
 
private void UpdateHeadsetState(HeadsetStateEventArgs e)
{            
            StringBuilder strB = new StringBuilder();
            strB.Append("Device Event: ");
          
            if (e.State == HeadsetState.Proximity)
            {
                strB.Append(String.Format("Headset Proximity received. (Proximity = {0})", e.Proximity));  
            }
            else
                strB.Append(String.Format("Headset state changed. ({0})", e.State.ToString()));  
 
            strB.AppendLine();
 
           //Update UI after marshalling to Main GUI thread
 
 richTextBoxTrace.AppendText(strB.ToString());
 
 }

Sample 3: Registering for Headset Proximity via IDeviceListenerEvents

IDevice m_device = null;
IHostCommandExt m_command = null;
IDeviceListener m_devListener = null;

//Get a valid device and init m_device

//Cast HostCommand and init m_command and m_devListener
m_command = device.HostCommand as IHostCommandExt;
m_devListener = device.DeviceListener as IDeviceListener;


//Register for HeadsetStateChanged event on Attach()to the device

if (m_devListener != null)
{
                    
 m_devListener.HeadsetStateChanged += listenerEvents_HeadsetStateChanged;
}

//UnRegister for HeadsetStateChanged event on Detach() to the device

if (m_devListener != null)
{
                    
 m_devListener.HeadsetStateChanged -= listenerEvents_HeadsetStateChanged;
}


//Event handler for HeadsetStateChanged

void listenerEvents_HeadsetStateChanged(object sender, DeviceListenerEventArgs e)
{
            UpdateMainThreadUI(String.Format("Headset state Changed {0}", e.HeadsetStateChange.ToString().ToUpper()));
}

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.