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