1. Manuals
  2. Brands
  3. NUANCE Manuals
  4. Microphone
  5. PowerScribe SDK API
  6. Reference manual

NUANCE PowerScribe SDK API Reference Manual

Hide thumbs
Table of Contents

Advertisement

Quick Links

Download this manual
Reference Guide
Microphone SDK API
®
For PowerScribe
SDK Version 3.2

Advertisement

Table of Contents
loading
Need help?

Need help?

Do you have a question about the PowerScribe SDK API and is the answer not in the manual?

Questions and answers

Subscribe to Our Youtube Channel

Related Manuals for NUANCE PowerScribe SDK API

Summary of Contents for NUANCE PowerScribe SDK API

  • Page 1 Reference Guide Microphone SDK API ® For PowerScribe SDK Version 3.2...
  • Page 2 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.

  • Page 3: Table Of Contents

    Contents Chapter 1: Introducing Microphone SDK Object Model & APIs . . 1 PowerMic II Microphone SDK Object Model ......2 Chapter 2: Microphone SDK API Reference .
  • Page 4 Microphone SDK API Reference Guide Connected() ...........41 Removed() .

  • Page 5: Chapter 1: Introducing Microphone Sdk Object Model & Apis

    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...

  • Page 6: Powermic Ii Microphone Sdk Object Model

    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.
  • Page 7 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.
  • Page 8 Microphone SDK API Reference Guide...

  • Page 9: Chapter 2: Microphone Sdk Api Reference

    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) •...

  • Page 10: Iusbdevicemgr

    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.

  • Page 11: Device

    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;...
  • Page 12 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).

  • Page 13: Iusbdevicemgrevents

    _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.

  • Page 14: Deviceremoved()

    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.
  • Page 15 _IUSBDeviceMgrEvents return E_FAIL; Returned Values: None.

  • Page 16: Iusbdevice And Ipowermicii

    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);...
  • Page 17 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...

  • Page 18: Productid

    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.
  • Page 19 IUSBDevice and IPowerMicII hr = pDevice->get_ProductID( &nProductID ); ( 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);...

  • Page 20: Productstring

    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.
  • Page 21 IUSBDevice and IPowerMicII hr = pDevice->get_ProductString( &bstrProductString ); ( FAILED(hr) ) return; m_strProductString = bstrProductString; UpdateData( FALSE ); Example 2 in C++: To retrieve a string containing the name of the microphone, you can create a function that calls the get property ProductString and pass it a pointer to receive the string returned: BSTR* function DisplayProductString(IPowerMicII* pDevice) pDevice->get_ProductString(&bstrProductString);...

  • Page 22: Vendorid

    Microphone SDK API Reference Guide VendorID Purpose: Get property of the IUSBDevice or IPowerMicII object. Returns a pointer to the numeric ID of vendor for the device plugged in to the USB port. Prototype: Propget HRESULT VendorID([out, retval] USHORT* pVal); Parameters: pVal Returned value.
  • Page 23 IUSBDevice and IPowerMicII hr = pDevice->get_VendorID( &nVendorID ); ( FAILED(hr) ) return; m_nVendorID = nVendorID; UpdateData( FALSE ); Example 2 in C++: To retrieve a string containing the ID of the microphone’s vendor, you can create a function that calls the get property VendorID and pass it a pointer to return the string in: BSTR* function DisplayVendorID(IPowerMicII* pDevice) pDevice->get_VendorID(&nVendorID);...

  • Page 24: Versionnumber

    Microphone SDK API Reference Guide VersionNumber Purpose: Get property of the IUSBDevice or IPowerMicII object. Returns a pointer to the version number the device plugged in to the USB port. Prototype: Propget HRESULT VersionNumber([out, retval] USHORT* pVal); Parameters: pVal Returned value. Pointer to the product version number. Example in Visual Basic: You can retrieve the microphone information from the hardware using the properties of the IPowerMicII object.
  • Page 25 IUSBDevice and IPowerMicII USHORT nVersionNumber; hr = pDevice->get_VersionNumber( &nVersionNumber ); ( FAILED(hr) ) return; m_nVersionNumber = nVersionNumber; UpdateData( FALSE ); Example 2 in C++: To retrieve version of the microphone, you can create a function that calls the get property VersionNumber and pass it a pointer to retrieve the returned value: USHORT* function DisplayVersionNumber(IPowerMicII* pDevice) pDevice->get_VersionNumber(&nVersionNumber);...

  • Page 26: Iusbdevice

    Microphone SDK API Reference Guide IUSBDevice Exclusive Properties USBDeviceType Purpose: Get property of the IUSBDevice object. Returns the device type of the device plugged in to the USB port. Prototype: Propget HRESULT USBDeviceType ([out, retval] USBDevicesType* pVal); Parameters: pVal Returned value. Pointer to the type of device. Equivalent ...
  • Page 27 IUSBDevice and check to be sure the device (usbdevice) is a usbdevPowerMic2 type device, then take appropriate action: Private Sub InitializePMII() Dim index As Integer Dim devtype As USBMGRLib.USBDevicesType Dim ncount As Integer usbmgr = New USBMGRLib.USBDeviceMgr ncount = usbmgr.DeviceCount index = 0 While (index <...

  • Page 28: Usbdeviceobject

    Microphone SDK API Reference Guide USBDeviceObject Purpose: Get property of the IUSBDevice object. Returns a pointer to the device plugged in to the USB port. Prototype: Propget HRESULT USBDeviceObject ([out, retval] IDispatch** pVal); Parameters: pVal Returned value. IDispatch (object) pointer to the device plugged in to the USB port. Example in Visual Basic: After you have determined that the device type is a PowerMic II, you can retrieve an object for the microphone using the USBDeviceObject property:...

  • Page 29: Ipowermicii

    IPowerMicII IPowerMicII Exclusive Methods and Properties IsConnected() Purpose: Method of the IPowerMicII object. Returns 1 if the USB device is connected and ready to use, returns 0 if the device is not connected or not available to use. Prototype: HRESULT IsConnected([out,retval] USHORT* bVal); Parameters: bVal True if the microphone is connected, False if it is not.

  • Page 30: Scan()

    Microphone SDK API Reference Guide Scan() Purpose: Method of the IPowerMicII object. Initiates decoding a bar code with the scanner on the PowerMic II microphone. Prototype: HRESULT Scan(void); Parameters: None. Example in C++: Once you determine the microphone is connected to the computer running the application and that the microphone has a scanner, you can scan a bar code by calling the Scan() method of the IPowerMicII object: if ( pMicDeviceObject->IsConnected())...

  • Page 31: Scanresult

    IPowerMicII ScanResult Purpose: Property of the IPowerMicII object. Returns a string containing the results of the last scan. Prototype: HRESULT ScanResult([out, retval] BSTR* pVal); Parameters: pVal Returned value. String containing the results of the last scan. Example in C++: After you call the Scan() method of the IPowerMicII object, you retrieve the results of the scan using the ScanResult property of the same object: if ( pMicDeviceObject->IsConnected())...

  • Page 32: Scannerpresent

    Microphone SDK API Reference Guide ScannerPresent Purpose: Property of the IPowerMicII object. Returns a BOOL value that reflects whether or not the scanner is present. Prototype: HRESULT ScannerPresent([out, retval] VARIANT_BOOL *pVal); Parameters: pVal VARIANT_BOOL pointer that receives VARIANT_TRUE if the scanner is present and VARIANT_FALSE if it is not.

  • Page 33: Setledstate()

    IPowerMicII SetLedState() Purpose: Method of the IPowerMicII object. Sets the state of the LED light on the PowerMic II to either turn off both red and green diodes or to turn on one of these combinations of diodes: • Both a green and a red diodes •...
  • Page 34 Microphone SDK API Reference Guide Example 2 in C++: You can allow the user of your application to set the color that the LED on the microphone displays during dictation by calling the SetLedState() method of the IPowerMicII object and passing it the constant that corresponds to the color the user chooses from a combo box.

  • Page 35: Ipowermiciiex

    IPowerMicIIEx IPowerMicIIEx Exclusive Methods and Properties ExclusiveControl() Purpose: Method of the IPowerMicII object. Method for assigning exclusive access to mircophone events. For your application to take exclusive control over the microphone, it should call the ExclusiveControl() method. After a call to this method, only the application that called it can receive the PowerMic II events.
  • Page 36 Microphone SDK API Reference Guide Example in C++: To secure the microphone for exclusive use of your application, you can call the ExclusiveControl() method of the IPowerMicII object: pMicDeviceObject->ExclusiveControl(ul_ID, exclControlSet); Returned Values: None.

  • Page 37: Setprocessid()

    IPowerMicIIEx SetProcessID() Purpose: Method of the IPowerMicII object. Method for connecting process to calling application. The new SetProcessID() method binds the cookie returned by the Advise() method with the process ID of the application that called Advise(). Your client must call this method after calling Advise() in order to receive PowerMic II events.

  • Page 38: Intercepteventsforapplication()

    Microphone SDK API Reference Guide InterceptEventsForApplication() Purpose: Method of the IPowerMicIIEx object. Method to enable a client application to intercept events intended for other applications. Prototype: HRESULT InterceptEventsForApplication([in] ULONG dwCookie, BSTR bstrAppName, [in] BOOL bIntercept); Parameters: dwCookie Unsigned long. Cookie that the Advise() method returns. bstrAppName String containing the name of the application from which events should be intercepted.

  • Page 39: Ipowermiciievents

    _IPowerMicIIEvents _IPowerMicIIEvents Properties ButtonPress() Purpose: Method of the IPowerMicIIEvents object. The framework calls this method when any single button on the PowerMic II has been pressed. Prototype: HRESULT ButtonPress([in] PMII_MICBUTTONS btncode); Parameters: btncode PMII_MICBUTTONS constant or its equivalent numeric value that reflects the button pressed on the PowerMic II.
  • Page 40 Microphone SDK API Reference Guide PMII_MICBUTTONS Equivalent Constant Numeric Value BTN_CUSTOMRIGHT 0x0200 BTN_SCAN 0x0400 Example in Visual Basic: To have your application react when a PowerMic II button has been pressed, your code should include a ButtonPress() method of the IPowerMicIIEvents object. First, you establish the PowerMic II object, then create the method of that object, having it receive the btncode as an argument, the PMII_MICBUTTONS constant from the table above that indicates which button was pressed.
  • Page 41 _IPowerMicIIEvents m_pDlg->m_bTranscribe = TRUE; break; case BTN_TABBACKWARD: m_pDlg->m_bTabBackward = TRUE; break; case BTN_DICTATE: m_pDlg->m_bDictate = TRUE; break; case BTN_TABFORWARD: m_pDlg->m_bTabForward = TRUE; break; case BTN_REWIND: m_pDlg->m_bRewind = TRUE; break; case BTN_FASTFORWARD: m_pDlg->m_bFastForward = TRUE; break; case BTN_STOPPLAY: m_pDlg->m_bStopPlay = TRUE; break;...

  • Page 42: Buttonrelease()

    Microphone SDK API Reference Guide ButtonRelease() Purpose: Method of the IPowerMicIIEvents object. The framework calls this method when a previously pressed button on the PowerMic II has been released. Prototype: HRESULT ButtonRelease([in] PMII_MICBUTTONS btncode); Parameters: btncode tagPMII_MICBUTTONS constant or its equivalent numeric value that reflects the button pressed on the PowerMic II.
  • Page 43 _IPowerMicIIEvents Case USBMGRLib.PMII_MICBUTTONS.BTN_DICTATE DgnMicBtn1.MicState = DNSTools.DgnMicStateConstants.dgnmicOff End Select End Sub Example in C++: To have your application react when a PowerMic II button that has been pressed is released, your code should include a ButtonRelease() method of the IPowerMicIIEvents object. First, you establish the events object, like the CPowerMicSink shown below: CPowerMicSink::CPowerMicSink(void) m_pDlg = NULL;...
  • Page 44 Microphone SDK API Reference Guide break; case BTN_STOPPLAY: m_pDlg->m_bStopPlay = FALSE; break; case BTN_CUSTOMLEFT: m_pDlg->m_bCustomLeft = FALSE; break; case BTN_ENTERSELECT: m_pDlg->m_bEnterSelect = FALSE; break; case BTN_CUSTOMRIGHT: m_pDlg->m_bCustomRight = FALSE; break; case BTN_SCAN: m_pDlg->m_bScan = FALSE; break; m_pDlg->UpdateData( FALSE ); return S_OK; Returned Values: None.

  • Page 45: Connected()

    _IPowerMicIIEvents Connected() Purpose: Method of the IPowerMicIIEvents object. The framework calls this method when a PowerMic II has been connected to the computer running the application. Prototype: HRESULT Connected(); Parameters: None. Example in C++: To have your application react when a PowerMic II microphone is plugged in to the computer running your application, your code should include a Connected() method of the IPowerMicIIEvents object where it takes appropriate action: STDMETHODIMP CPowerMicSink::Connected()

  • Page 46: Removed()

    Microphone SDK API Reference Guide Removed() Purpose: Method of the IPowerMicIIEvents object. The framework calls this method when the PowerMic II has been disconnected from the computer running the application. Prototype: HRESULT Removed(); Parameters: None. Example in C++: To have your application react when a PowerMic II microphone is unplugged from the computer running your application, your code should include a Removed() method of the IPowerMicIIEvents object where it takes appropriate action: STDMETHODIMP CPowerMicSink::Removed()

  • Page 47: Scanstarted()

    _IPowerMicIIEvents ScanStarted() Purpose: Method of the IPowerMicIIEvents object. The framework calls this method when the scan has been started using the PowerMic II microphone. Prototype: HRESULT ScanStarted(void); Parameters: None. Example in C++: To have your application react when a PowerMic II microphone starts scanning a bar code, your application should include a ScanStarted() method of the IPowerMicIIEvents object where it takes appropriate action: STDMETHODIMP CPowerMicSink::ScanStarted()

  • Page 48: Scanfinished()

    Microphone SDK API Reference Guide ScanFinished() Purpose: Method of the IPowerMicIIEvents object. The framework calls this method when the PowerMic II has finished scanning a bar code or scannable text. Prototype: HRESULT ScanFinished([in] BSTR pbstrData, [in] BOOL pbSuccess); Parameters: pbstrData String containing the data scanned.

  • Page 49: Appendix A: Values For Powermic Ii Microphone Buttons

    Appendix A Values for PowerMic II Microphone Buttons in Microphone SDK API This appendix shows information for working with the buttons on the PowerMic II microphone in the Microphone SDK API, indicating: • Name used to refer to each button •...

  • Page 50: Powermic Ii Buttons In Microphone Sdk

    Microphone SDK API Reference PowerMic II Buttons in Microphone SDK btncode Values for ButtonPress(), ButtonRelease()   btncode Microphone Button PMII_MICBUTTONS Value Function MICROPHONE Not applicable. Talk into the PowerMic II microphone. TRANSCRIBE BTN_TRANSCRIBE Press to end current dictation/display transcribed text. Press to position insertion point or select a sentence.
  • Page 51 Appendix A: Values for PowerMic II Microphone Buttons in Microphone SDK API Dictation Tips & Techniques ■ Dictation Preparation — Collect your thoughts and plan your words before speaking. ■ Position the microphone between 2 and 5 inches from your mouth, but not touching. Keep the microphone at a constant distance from your mouth.
  • Page 52 Microphone SDK API Reference...

  • Page 53: Appendix B: Configuration For Microphone Sharing

    Appendix B Configuration for Microphone Sharing This appendix contains information about the configuration file that is needed for applications to share the microphone.

  • Page 54: Configuration For Microphone Sharing

    Microphone SDK API Reference Configuration for Microphone Sharing In order for applications to share the Microphone and have access to the generated events, you must create a configuration file: usbmgr.conf. The configuration file stores the list of applications which can receive the PowerMic II device events.

Table of Contents