NUANCE PowerScribe SDK API User manual

Reference Guide
Microphone SDK API
For PowerScribe®SDK Version 3.2

Trademarks
Nuance®, the Nuance logo, Dictaphone®, and PowerScribe®are trademarks or registered trademarks of Nuance
Communications, Inc. or its affiliates in the United States and/or other countries. All other trademarks referenced herein are
trademarks or registered trademarks of their respective owners.
Patents
The PowerMic II product is the subject of pending U.S and foreign patent applications.
Copyright Notice
This manual is copyrighted and all rights are reserved by Nuance Communications, Inc. No part of this publication may be
reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in
any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior
written permission of Nuance Communications, Inc., 1 Wayside Road, Burlington, MA 01803.
Copyright © 2007, 2009 Nuance Communications, Inc. All rights reserved.
Disclaimer
Nuance makes no warranty, express or implied, with respect to the quality, reliability, currentness, accuracy, or freedom
from error of this document or the product or products referred to herein and specifically disclaims any implied warranties,
including, without limitation, any implied warranty of merchantability, fitness for any particular purpose, or non-
infringement. Nuance disclaims all liability for any direct, indirect, incidental, consequential, special, or exemplary
damages resulting from the use of the information in this document. Mention of any product not manufactured by Nuance
does not constitute an endorsement by Nuance of that product.
Published by Nuance Communications, Inc.
Burlington, Massachusetts, USA
Visit Nuance Communications, Inc. on the Web at www.nuance.com.
L-3265-001 11/2009

iii
Chapter 1: Introducing Microphone SDK Object Model & APIs . . 1
PowerMic II Microphone SDK Object Model . . . . . . . . . . . . . . . . . . . . . . . . . .2
Chapter 2: Microphone SDK API Reference . . . . . . . . . . . . . . . . . . 5
IUSBDeviceMgr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
DeviceCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
_IUSBDeviceMgrEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
DeviceConnected() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
DeviceRemoved() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
IUSBDevice and IPowerMicII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Manufacturer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
ProductID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
ProductString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
VendorID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
VersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
IUSBDevice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
USBDeviceType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
USBDeviceObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
IPowerMicII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
IsConnected() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Scan() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
ScanResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
ScannerPresent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
SetLedState() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
IPowerMicIIEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
ExclusiveControl() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
SetProcessID() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
InterceptEventsForApplication() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
_IPowerMicIIEvents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
ButtonPress() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
ButtonRelease() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Contents

iv
Microphone SDK API Reference Guide
Connected() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Removed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
ScanStarted() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
ScanFinished() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Appendix A: Values for PowerMic II Microphone Buttons
in Microphone SDK API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
PowerMic II Buttons in Microphone SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Appendix B: Configuration for Microphone Sharing . . . . . . . . . . 49
Configuration for Microphone Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50

1
Chapter 1
Introducing Microphone
SDK Object Model & APIs
Objectives
The Microphone Software Development Kit (SDK) is a set of
application programmer interfaces (APIs) that you use to work
with the PowerMic II microphone in your dictation and speech-
recognition system.
This chapter presents an overview of the object model for the
PowerMic II Microphone SDK and the types of capabilities that
this SDK provides in PowerMic II Microphone SDK Object
Model.

2
Microphone SDK API Reference Guide
PowerMic II Microphone SDK Object
Model
PowerMic II Microphone SDK APIs are available as a supplement to the full SDK Client.
The object model for these APIs (shown below) contains several types of objects and their
related event objects. The IUSBDevice object represents any USB device, including a
PowerMic II device, also represented by the IPowerMicII and the IPowerMicIIEx objects.
Events of the IUSBDevice object are the plugging in and unplugging of any USB device,
whereas the events of the IPowerMicII and the IPowerMicIIEx objects are specific to the
PowerMic II—pressing buttons on the microphone or scanning with the microphone’s
scanner.
IPowerMicII/
Scanner Device
Buttons Device
Hardware Types:
IUSBDevice
IUSBDeviceMgr
1N
_IUSBDeviceMgrEvents _IPowerMicIIEvents
Notifications about
Plugging In/Unplugging
Devices
Notifications from
PowerMic II Buttons
and Scanner
IPowerMicIIEx
The IUSBDeviceMgr object manages events from all USB devices (including the PowerMic
II) by providing a DeviceCount property to determine how many devices have been
connected and a Device property to retrieve an object for the device.
The IUSBDevice object provides a USBDeviceType property that helps you determine the
type of device connected to a USB port, distinguishing between a PowerMic II with a scanner
and one without a scanner. (The usbdevUnknown and usbdevVecPedal values are never
returned in this version.) The IUSBDevice object also provides the USBDeviceObject
property to retrieve an object for a particular USB device. In this release, the IUSBDevice
object supports only the PowerMic II microphone.
The _IUSBDeviceMgrEvents object provides DeviceConnected() and DeviceRemoved()
methods triggered when those types of events occur.

3
Chapter 1: Introducing Microphone SDK Object Model & APIs
The IPowerMicII object provides methods that make the PowerMic II microphone take
particular actions or check the status of the microphone, such as IsConnected(), Scan(), and
SetLedState(). This object also provides a ScanResult property that you use to retrieve the
scanned data from the microphone and a ScannerPresent property that you use to determine
whether or not the microphone has a scanner.
The IPowerMicIIEx object provides methods that enable sharing of the PowerMic II
microphone across applications that have been enabled to listen for PowerMic II events.
Both the IUSBDevice and IPowerMicII objects provide a series of properties that you can
use to determine information about the hardware itself, such as Manufacturer, ProductID,
ProductString, VendorID, and VersionNumber.
The _IPowerMicIIEvents object provides methods triggered when a user takes specific
actions with the PowerMic II microphone, such as ButtonPress(), ButtonRelease(),
Connected(), Removed(), ScanStarted(), and ScanFinished().

4
Microphone SDK API Reference Guide

5
Chapter 2
Microphone SDK API
Reference
Objectives
This chapter contains reference information on each PowerMic II
API. The APIs are organized by these object types:
•IUSBDeviceMgr
•_IUSBDeviceMgrEvents
•IUSBDevice and IPowerMicII (properties that
apply to both object types)
•IUSBDevice
•IPowerMicII
•IPowerMicIIEx
•_IPowerMicIIEvents
The examples shown in this chapter are all COM implementations in
C++. However, you can use these APIs in other contexts, including
on platforms other than Windows and in languages other than C++.

6
Microphone SDK API Reference Guide
IUSBDeviceMgr
Properties
DeviceCount
Purpose:
Read-only property of the IUSBDeviceMgr object. Returns the total number of USB devices
available on the computer running the application.
Prototype:
Propget HRESULT DeviceCount( [out, retval] LONG* pVal );
Parameters:
pVal
Pointer to the number of USB devices on the computer. Is never NULL.
Example in Visual Basic
To check the number of USB devices connected to the computer running your speech-
recognition application, you can check the value of the DeviceCount property. First you
instantiate the IUSBDeviceMgr object, then retrieve its DeviceCount value:
Dim index As Integer
Dim ncount As Integer
usbmgr = New USBMGRLib.USBDeviceMgr
ncount = usbmgr.DeviceCount
index = 0
Once you have the number of devices, you can take action on each device in a loop:
While (index < ncount)
usbdevice = usbmgr.Device(index)
index = index + 1

7
IUSBDeviceMgr
... // take action on each device
End While
Example in C++:
To check the number of USB devices connected to the computer running your speech-
recognition application, you can check the value of the DeviceCount property:
long nDcount;
if (&nDcount == IUSBDeviceMgr->DeviceCount())
{
return nDcount;
}
else
{
AfxMessageBox( _T("No USB device is connected.\n");
}
}
Returned Values:
Number of USB devices on the computer.
Device
Purpose:
Read-only property of the IUSBDeviceMgr object. Returns the USB device object identified
by the index number you pass it. That identifier is a number that is unique for the USB port on
the computer running the application.
Prototype:
Propget HRESULT Device( [in] LONG index, [out, retval] IUSBDevice** pVal );
Parameters:
index
Index number of the device on the computer, starting at 0and progressing to the maximum
device number of DeviceCount – 1.
pVal
Returned value. Pointer to the USB device object identified by the index.

8
Microphone SDK API Reference Guide
Example in Visual Basic:
After you instantiate the IUSBDeviceMgr object, to retrieve an object for the device
connected to the USB port of the computer running your application, you call the Device
property and pass it the number of the device. If you have one microphone, it is device zero
(0). If you have more than one, to retrieve the first device, you can start with 0 and loop
through all the devices until you find the first one that is not NULL:
Dim index As Integer
Dim ncount As Integer
usbmgr = New USBMGRLib.USBDeviceMgr
FindFirstDevice:
While (index < ncount)
objDevice = usbmgr.Device(index)
index = index + 1
If (objDevice != NULL)
return objDevice
GoTo UseDeviceRoutine
End If
End While
UseDeviceForDictation:
rem Execute dictation
Example in C++:
To retrieve an object for the device connected to the USB port of the computer running your
application, you can use the Device property and pass it the number of the device. If you have
one microphone, it is device zero (0):
if (&&nMicDeviceObj == IUSBDeviceMgr->Device(0))
{
return &nMicDeviceObj;
}
else
{
AfxMessageBox( _T("No USB device is connected.\n");
}
}
Returned Values:
Pointer to the USB device object.

9
_IUSBDeviceMgrEvents
_IUSBDeviceMgrEvents
Methods
You should implement this event notification object on the client side. Returned values of the
methods of this object are usually S_OK and you can choose to ignore them.
DeviceConnected()
Purpose:
Method of the _IUSBDeviceMgrEvents object. The framework calls this method when a new
device has been plugged in to a USB port. The method call indicates that the device is
available for use.
Prototype:
HRESULT DeviceConnected([in] IUSBDevice* pDevice);
Parameters:
pDevice
Pointer to the USB device just plugged in to the computer.
Example in C++:
To take action when a device is plugged in to a USB port, you should take that action in the
DeviceConnected() method of the _IUSBDeviceMgrEvents object. When you define the
class for the object, you should define the DeviceConnected() method. To have the method
initiate tests of the microphone and display the results in a dialog whenever a device is
plugged in, you can have the DeviceConnected() method call a function that takes that action:
STDMETHODIMP CUsbMgrSink::DeviceConnected(IUSBDevice* pDevice)
{
if ( !m_pDlg )
return E_FAIL;

10
Microphone SDK API Reference Guide
{
m_pDevice->InitiateMicrophoneTests();
m_pDlg->DisplayResults();
return S_OK;
}
}
Returned Values:
None.
DeviceRemoved()
Purpose:
Method of the _IUSBDeviceMgrEvents object. The framework calls this method when a
device has been unplugged from a USB port. The method call indicates that the device is no
longer available for use.
Prototype:
HRESULT DeviceRemoved([in] IUSBDevice* pDevice);
Parameters:
pDevice
Pointer to the USB device just unplugged from the computer.
Example:
To take action when a device is unplugged from a USB port, you should take that action in the
DeviceRemoved() method of the _IUSBDeviceMgrEvents object. First, you should define
the class for the object, then define the DeviceRemoved() method. To have the method check
whether or not the device removed was a PowerMic II, you can have the method test the
USBDeviceType property value of the device passed in to the method (pDevice) and if the
device is a usbdevPowerMic2 type device, then take appropriate action:
STDMETHODIMP CUsbMgrSink::DeviceRemoved(IUSBDevice* pDevice)
{
...
pDevice->get_USBDeviceType(&pType);
if( pType == usbdevPowerMic2 )
{
AfxMessageBox( _T("Microphone disconnected. \n");
m_pDlg->StopMicDialogDisplay();
return S_OK;
}

11
_IUSBDeviceMgrEvents
return E_FAIL;
}
Returned Values:
None.

12
Microphone SDK API Reference Guide
IUSBDevice and IPowerMicII
Properties Applicable to Both Objects
Manufacturer
Purpose:
Get property of the IUSBDevice or IPowerMicII object. Returns a pointer to a string
containing the name of the manufacturer of the device plugged in to the USB port.
Prototype:
Propget HRESULT Manufacturer([out, retval] BSTR* pVal);
Parameters:
pVal
Returned value. Pointer to a string containing the name of the product manufacturer.
Example in Visual Basic:
You can retrieve the microphone information from the hardware using the properties of the
IPowerMicII object. For instance, to retrieve the name of the manufacturer so that you can
later display the name in a dialog, you would use the Manufacturer property of the object and
retrieve the returned string inside the routine that updates the GUI:
Private Sub FillData(ByVal pDevice As USBMGRLib.IUSBDevice)
Dim strMfr As String
...
strMfr = pDevice.Manufacturer
...
TextBox4.Text = strMfr
...

13
IUSBDevice and IPowerMicII
End Sub
Example 1 in C++:
You can retrieve the microphone information from the hardware using the properties of the
IPowerMicII object. For instance, to retrieve the name of the manufacturer so that you can
later display the name in a dialog, you would use the Manufacturer get property of the object
and pass it the pointer to retrieve the returned string, then call a user-defined function to
update the GUI:
void CUsbmgr_testDlg::FillData( IUSBDevice *pDevice )
{
if ( !pDevice )
return;
HRESULT hr;
CComBSTR bstrManufacturer;
hr = pDevice->get_Manufacturer( &bstrManufacturer );
if ( FAILED(hr) )
return;
m_strManufacturer = bstrManufacturer;
UpdateData( FALSE );
}
Example 2 in C++:
To retrieve the name of the microphone manufacturer, you can create a function that calls the
get property Manufacturer and pass it a pointer to return the string in:
BSTR* function DisplayManufacturuer(IPowerMicII* pDevice)
{
pDevice->get_Manufacturer(&bstrManuf);
if (bstrManuf)
{
AfxMessageBox( _T("Microphone Manufacturer is " + pManuf + "\n"));
return bstrManuf;
}
return E_FAIL;
}
Returned Values:
Pointer to the string of the product manufacturer.

14
Microphone SDK API Reference Guide
ProductID
Purpose:
Get property of the IUSBDevice or IPowerMicII object. Returns the numeric product ID for
the device plugged in to the USB port.
Prototype:
Propget HRESULT ProductID([out, retval] USHORT* pVal);
Parameters:
pVal
Returned value. Pointer to the product ID number.
Example in Visual Basic:
You can retrieve the microphone information from the hardware using the properties of the
IPowerMicII object. For instance, to retrieve the identifier for the product so that you can
later display the name in a dialog, you would use the ProductID property of the object and
retrieve the returned short integer inside the routine that updates the GUI:
Private Sub FillData(ByVal pDevice As USBMGRLib.IUSBDevice)
Dim nProductID As Short
nProductID = pDevice.ProductID
...
TextBox2.Text = nProductID.ToString
...
End Sub
Example 1 in C++:
You can set the retrieve the microphone information from the hardware using the properties of
the IPowerMicII object. For instance, to retrieve the numeric product ID to later display the
number in a dialog, you would use the ProductID get property of the object and pass it the
pointer to retrieve the returned number, then call a user-defined function to update the GUI:
void CUsbmgr_testDlg::FillData( IUSBDevice *pDevice )
{
if ( !pDevice )
return;
HRESULT hr;
USHORT nProductID;

15
IUSBDevice and IPowerMicII
hr = pDevice->get_ProductID( &nProductID );
if ( FAILED(hr) )
return;
m_nProductID = nProductID;
UpdateData( FALSE );
}
Example 2 in C++:
To retrieve the numeric microphone product ID, you can create a function that calls the get
property ProductID and pass it a pointer to retrieve the returned numeric value:
USHORT* function DisplayProductID(IPowerMicII* pDevice)
{
pDevice->get_ProductID( &nProductID);
if ( nProductID )
{
AfxMessageBox( _T("Microphone Product ID is " + nProductID + "\n"));
m_pDlg->OpenPowerMicIIdlg();
return nProductID;
}
return E_FAIL;
}
Returned Values:
Pointer to the product ID number.

16
Microphone SDK API Reference Guide
ProductString
Purpose:
Get property of the IUSBDevice or IPowerMicII object. Retrieves a string containing the
product name of the device plugged in to the USB port.
Prototype:
Propget HRESULT ProductString([out, retval] BSTR* pVal);
Parameters:
pVal
Returned value. Pointer to the string containing the product name.
Example in Visual Basic:
You can retrieve the microphone information from the hardware using the properties of the
IPowerMicII object. For instance, to retrieve the name of the product so that you can later
display the name in a dialog, you would use the ProductString property of the object and
retrieve the returned string inside the routine that updates the GUI:
Private Sub FillData(ByVal pDevice As USBMGRLib.IUSBDevice)
Dim strproduct As String
strproduct = pDevice.ProductString
...
TextBox5.Text = strproduct
End Sub
Example 1 in C++:
You can set the retrieve the microphone information from the hardware using the properties of
the IPowerMicII object. For instance, to retrieve the name of the product in a string, you
would use the ProductString get property of the object and pass it the pointer to retrieve the
string returned, then call a user-defined function to update the GUI:
void CUsbmgr_testDlg::FillData( IUSBDevice *pDevice )
{
if ( !pDevice )
return;
HRESULT hr;
CComBSTR bstrProductString;