Programmer Manual
BPA100 Series
Bluetooth Protocol Analyzer
Software Version 2.3
Application Programming Interface
071-1129-00
This document supports software version 2.3 and
above.
www.tektronix.com
Copyright © Tektronix, Inc. All rights reserved. Licensed software products
are owned by Tektronix or its suppliers and are protec ted by United States
copyright laws and international treaty provisions.
Use, duplication, or disclosure by the Government is subject to restrictions as
set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and
Computer Software clause at DFARS 252.227-7013, or subparagraphs (c)(1)
and (2) of the Commercial Computer Software -- Restricted Rights clause at
FAR 52.227-19, as applicable.
Tektronix products are covered by U.S. and foreign patents, issued and
pending. Information in this publication supercedes that in all pre viously
published material. Specifications and price change privileges reserved.
Tektronix, Inc., P.O. Box 500, Beaverton, OR 97077
TEKTRONIX and TEK are registered trademarks of Tektronix, Inc.
Bluetooth is a trademark of Telefonaktiebolaget L M Ericsson, Sweden
HARDWARE WARRANTY
Tektronix warrants that the products that it manufactures and sells will be free from defects
in materials and workmanship for a period of three (3) years from the date of shipment. If a
product proves defective during this warranty period, Tektronix, at its option, either will
repair the defective product without charge for parts and labor, or will provide a
replacement in exchange for the defective product.
In order to obtain service under this warranty, Customer must notify Tektronix of the
defect before the expiration of the warranty period and make suitable arrangements for the
performance of service. Customer shall be responsible for packaging and shipping the
defective product to the service center designated by Tektronix, with shipping charges
prepaid. Tektronix shall pay for the return of the product to Customer if the shipment is to
a location within the country in which the Tektronix service center is located. Customer
shall be responsible for paying all shipping charges, duties, taxes, and any other charges for
products returned to any other locations.
This warranty shall not apply to any defect, failure or damage caused by improper use or
improper or inadequate maintenance and care. Tektronix shall not be obligated to furnish
service under this warranty a) to repair damage resulting from attempts by personnel other
than Tektronix representatives to install, repair or service the product; b) to repair damage
resulting from improper use or connection to incompatible equipment; c) to repair any
damage or malfunction caused by the use of non-Tektronix supplies; or d) to service a
product that has been modified or integrated with other products when the effect of such
modification or integration increases the time or difficulty of servicing the product.
THIS WARRANTY IS GIVEN BY TEKTRONIX IN LIEU OF ANY OTHER
WARRANTIES, EXPRESS OR IMPLIED. TEKTRONIX AND ITS VENDORS
DISCLAIM ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE. TEKTRONIX’ RESPONSIBILITY
TO REPAIR OR REPLACE DEFECTIVE PRODUCTS IS THE SOLE AND
EXCLUSIVE REMEDY PROVIDED TO THE CUSTOMER FOR BREACH OF
THIS WARRANTY. TEKTRONIX AND ITS VENDORS WILL NOT BE LIABLE
FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES IRRESPECTIVE OF WHETHER TEKTRONIX OR THE VENDOR
HAS ADVANCE NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.
SOFTWARE WARRANTY
Tektronix warrants that the media on which this software product is furnished and the
encoding of the programs on the media will be free from defects in materials and
workmanship for a period of three (3) months from date of shipment. If a medium or
encoding proves defective during the warranty period, Tektronix will provide a
replacement in exchange for the defective medium. Except as to the media on which this
software product is furnished, this software product is provided “as is” without warranty of
any kind, either express or implied. Tektronix does not warrant that the functions contained
in this software product will meet Customer’s requirements or that the operation of the
programs will be uninterrupted or error-free.
In order to obtain service under this warranty, Customer must notify Tektronix of the
defect before the expiration of the warranty period. If Tektronix is unable to provide a
replacement that is free from defects in materials and workmanship within a reasonable
time thereafter, Customer may terminate the license for this software product and return
this software product and any associated materials for credit or refund.
THIS WARRANTY IS GIVEN BY TEKTRONIX IN LIEU OF ANY OTHER
WARRANTIES, EXPRESS OR IMPLIED. TEKTRONIX AND ITS VENDORS
DISCLAIM ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE. TEKTRONIX’ RESPONSIBILITY
TO REPLACE DEFECTIVE MEDIA OR REFUND CUSTOMER’SPAYMENTIS
THE SOLE AND EXCLUSIVE REMEDY PROVIDED TO THE CUSTOMER
FOR BREACH OF THIS WARRANTY. TEKTRONIX AND ITS VENDORS WILL
NOT BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES IRRESPECTIVE OF WHETHER TEKTRONIX
OR THE VENDOR HAS ADVANCE NOTICE OF THE POSSIBILITY OF SUCH
DAMAGES.
Table of Contents
Preface ix............................................
Related Manuals ix....................................
Contacting Tektronix x.................................
Getting Started
Introduction 1--1.......................................
General Characteristic 1--2................................
Software Requirements 1--3...............................
Objects and Interfaces 1--5...............................
Overview 1--5..........................................
Setting Up the API
Running a Client Application on the Server Machine 2--2.......
Running a Client Application across the Network 2--3..........
Setting up the API on the Server Machine 2--3................
Setting up the Client Machine on Windows 2000/NT 2--19.......
Setting up a Client Machine on Windows 98 2--37..............
Setting up a Client Machine on Windows 95 2--46..............
Setting up the Client Machine on Other Platforms 2--54..........
Connecting to the Protocol Analyzer Server 2--55...............
Disconnecting from the Protocol Analyzer Server 2--55..........
Programming Examples
Microsoft Visual Basic Client Using Dispatch Interfaces 3--2.....
Microsoft Visual Basic Client Using VTABLE Interfaces 3--3....
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
i
Table of Contents
Status and Events
Error Handling 4--1......................................
Server Message Boxes 4--2................................
Syntax and Commands
Command Groups 5--1..................................
BPAAplication Commands 5--1............................
BPASystem Commands 5--2...............................
BPASystemEvents Commands 5--4.........................
BPAAnalyzer Commands 5--5.............................
BPAHCISimple Commands 5--6............................
BPAHCISimpleEvents Command 5--6.......................
Command Descriptions 5--7..............................
IBPAApplication::ShowWindow 5--7........................
IBPAApplication::GetVersion 5--9..........................
IBPAApplication::GetBDAddress 5--11.......................
IBPAApplication::GetAnalyzer 5-- 12.........................
IBPAApplication::GetSystem 5--13..........................
IBPAApplication::GetHCISimple 5--14.......................
IBPASystem::Start 5--15...................................
IBPASystem::Stop 5--17...................................
IBPASystem::Pause 5--19..................................
IBPASystem::Resume 5--20................................
IBPASystem::GetDeviceStatus 5--22.........................
IBPASystem::GetSessionInfo 5-- 24..........................
IBPASystem::SetHoppingMode 5--26........................
IBPASystem::GetHoppingMode 5--28........................
IBPASystem::SetCorrelation 5--30...........................
IBPASystem::GetCorrelation 5--31...........................
IBPASystem::SetResync 5--32..............................
IBPASystem::GetResync 5--33..............................
IBPASystem::SetDataWhitening 5--34........................
IBPASystem::GetDataWhitening 5--36.......................
IBPASystem::SetAcquisitionMode 5--37......................
IBPASystem::GetAcquisitionMode 5--39......................
IBPASystem::SetAcquisitionDefault 5--41.....................
IBPASystem::SetLowLevelTrigger 5--42......................
IBPASystem::GetLowLevelTrigger 5--43.....................
ii
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Table of Contents
IBPASystem::ActivateLowLevelTrigger 5--44.................
IBPASystem::SetHighLevelTrigger 5--46.....................
IBPASystem::GetHighLevelTrigger 5--47.....................
IBPASystem::ActivateHighLevelTrigger 5--48.................
IBPASystem::SetErrorPacketGeneration 5--49.................
IBPASystem::GetErrorPacketGeneration 5--50.................
IBPASystem::ActivateErrorPacketGeneration 5--51.............
IBPASystem::SetDataFilter 5--53............................
IBPASystem::GetDataFilter 5--55............................
IBPASystem::ActivateDataFilter 5--57........................
IBPASystem::SetDecryptionSettings 5--59.....................
IBPASystem::GetDecryptionSettings 5--62....................
IBPASystem::ActivateDecryption 5--64.......................
IBPASystem::SetDecryptionDefault 5--65.....................
IBPASystem::DoDeviceDiscovery 5--66......................
IBPASystem::GetDeviceDiscoveryStatus 5--67.................
IBPASystem::GetDeviceList 5--69...........................
IBPASystemEvents::OnStateChange 5--71.....................
IBPASystemEvents::OnTriggerIn 5--72.......................
IBPASystemEvents::OnTriggerOut 5--73......................
IBPAAnalyzer::Open 5--74.................................
IBPAAnalyzer::Close 5--76.................................
IBPAAnalyzer::GetPacketCount 5--77........................
IBPAAnalyzer::GetPacket 5--79.............................
IBPAAnalyzer::GetPrevPacketNumber 5--82...................
IBPAAnalyzer::GetNextPacketNumber 5--85..................
IBPAAnalyzer::GetPacketInfo 5--88..........................
IBPAAnalyzer::Export 5--92................................
IBPAAnalyzer::GetAcquisitionReport 5--95...................
IBPAAnalyzer::SetL2CAPConnectionProperties 5--97...........
IBPAAnalyzer::GetL2CAPConnectionProperties 5--99...........
IBPAAnalyzer::SetRFCOMMServerChannel 5--101..............
IBPAAnalyzer::GetRFCOMMServerChannel 5--103..............
IBPAHCISimple::Send 5--105...............................
IBPAHCISimple::Get 5-- 106................................
IBPAHCISimpleEvents::HCIEvent 5--107......................
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
iii
Table of Contents
Appendices
Appendix A: Other Issues with DCOM A--1.................
Glossary and Index
iv
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
List of Figures
Figure 1--1: Controlling BPA100 Series
Bluetooth Protocol Analyzer 1--1.......................
Figure 1--2: Object hierarchy 1--6.........................
Table of Contents
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
v
Table of Contents
List of Tables
Table i: Related manuals xi............................
Table 5--1: BPAAplication commands 5 --1..................
Table 5--2: BPASystem commands 5--2....................
Table 5--3: BPASystemEvents commands 5--4..............
Table 5--4: BPAAnalyzer commands 5--4..................
Table 5--5: BPAHCISimple commands 5--6................
Table 5--6: BPAHCISimpleEvents commands 5--6...........
Table 5 --7: IBPAApplication::ShowWindow Show
values 5--7.........................................
Table 5 --8: IBPAApplication::ShowWindow Returns 5--7.....
Table 5 --9: IBPAApplication::GetVersion Sybsystem
values 5--9.........................................
Table 5 --10: IBPAApplication::GetVersion Returns 5--9......
Table 5--11: IBPAApplication::GetBDAddress Returns 5--11...
Table 5--12: IBPAApplication::GetAnalyzer Returns 5--12.....
Table 5--13: IBPAApplication::GetSystem Returns 5--13......
Table 5 --14: IBPAApplication::GetHCISimple Returns 5--14...
Table 5--15: IBPASystem::Start Returns 5--15...............
Table 5--16: IBPASystem::Stop Returns 5--17................
Table 5--17: IBPASystem::Pause Returns 5--19...............
Table 5--18: IBPASystem::Resume Returns 5--20.............
Table 5--19: IBPASystem::GetDevic eStatus State Values 5--22..
Table 5--20: IBPASystem::GetDevic eStatus Returns 5--22.....
Table 5--21: IBPASystem::GetSessionInfo SessionInf
Type Values 5-- 24.....................................
vi
Table 5--22: IBPASystem::GetSessionInfo Returns 5--24.......
Table 5--23: IBPASystem::SetHoppingMode P attern
Val ue s 5 -- 2 6..........................................
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Table of Contents
Table 5--24: IBPASystem::SetHoppingMode P attern
Frequency 5--26......................................
Table 5--25: IBPASystem::SetHoppingMode Returns 5--27.....
Table 5--26: IBPASystem::GetHoppingMode Pattern
Val ue s 5 -- 2 8..........................................
Table 5--27: IBPASystem::GetHoppingMode Pattern
Frequency 5--28......................................
Table 5--28: IBPASystem::GetHoppingMode Returns 5--29....
Table 5--29: IBPASystem::SetCorrelation Re turns 5--30.......
Table 5--30: IBPASystem::GetCorrelati o n Returns 5--31......
Table 5--31: IBPASystem::SetResync Returns 5--32...........
Table 5--32: IBPASystem::GetResync Returns 5--33..........
Table 5--33: IBPASystem::SetDataWhitening Whitening
Val ue s 5 -- 3 4.........................................
Table 5--34: IBPASystem::SetDataWhitening Returns 5--34....
Table 5--35: IBPASystem::GetDataWhitening Whitening
Val ue s 5 -- 3 6.........................................
Table 5--36: IBPASystem::GetDataWhitening Returns 5--36...
Table 5--37: IBPASystem::SetAcquisitionMode Connect
Val ue s 5 -- 3 7.........................................
Table 5--38: IBPASystem::SetAcquisitionMode SyncOption
Val ue s 5 -- 3 7..........................................
Table 5--39: IBPASystem::SetAcquisitionMode Returns 5--38..
Table 5--40: IBPASystem::GetAcquisitionMode Connect
Val ue s 5 -- 3 9.........................................
Table 5--41: IBPASystem::GetAcquisitionMode
SyncOption Values 5--39...............................
Table 5--42: IBPASystem::GetAcquisitionMode Returns 5--40..
Table 5--43: IBPASystem::SetAcquisitionDefault Returns 5--41.
Table 5--44: IBPASystem::SetLowLevelTrigger Returns 5--42..
Table 5--45: IBPASystem::GetLowLevelTrigger Returns 5--43..
Table 5--46: IBPASystem::ActivateLowLevelTrigger
Enable Values 5--44...................................
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
vii
Table of Contents
Table 5--47: IBPASystem::ActivateLowLevelTrigger
Returns 5--44........................................
Table 5--48: IBPASystem::SetHighLevelTrigger Returns 5--46..
Table 5--49: IBPASystem::SetHighLevelTrigger Returns 5--47..
Table 5--50: IBPASystem::ActivateHi ghLe velTrigger
Enable Values 5--48......................................
Table 5--51: IBPASystem::ActivateHi ghLe velTrigger
Returns 5--48........................................
Table 5--52: IBPASystem::SetErrorPacketGeneration
Returns 5--49........................................
Table 5--53: IBPASystem::GetErrorPacketGeneration
Returns 5--50........................................
Table 5--54: IBPASystem::ActivateErrorPacketGeneration
Enable Values 5--51...................................
Table 5--55: IBPASystem::ActivateErrorPacketGeneration
Returns 5--51........................................
Table 5--56: IBPASystem::SetDataFilter Values 5--53.........
Table 5--57: IBPASystem::SetDataFilter Returns 5--53........
Table 5--58: IBPASystem::SetDataFilter Values 5--55.........
Table 5--59: IBPASystem::SetDataFilter Returns 5--55........
Table 5--60: IBPASystem::ActivateDataFilter Values 5--57.....
Table 5--61: IBPASystem::ActivateDataFilter Returns 5--57....
Table 5--62: IBPASystem::SetDecryptionSettings Type
Val ue s 5 -- 5 9..........................................
Table 5--63: IBPASystem::SetDecryptionSettings Session
Val ue s 5 -- 5 9..........................................
Table 5--64: IBPASystem::SetDecryptionSettings
Returns 5--60........................................
viii
Table 5--65: IBPASystem::GetDecr yptionSetti ngs Type
Val ue s 5 -- 6 2..........................................
Table 5--66: IBPASystem::GetDecr yptionSetti ngs Session
Val ue s 5 -- 6 2..........................................
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Table of Contents
Table 5--67: IBPASystem::GetDecr yptionSettings
Returns 5--63........................................
Table 5--68: IBPASystem::ActivateDecryption Enable
Val ue s 5 -- 6 4..........................................
Table 5--69: IBPASystem::ActivateDecryption Returns 5--64...
Table 5--70: IBPASystem::SetDecryptionDefault Returns 5--65.
Table 5--71: IBPASystem::DoDeviceDiscovery Returns 5--66...
Table 5--72: IBPASystem:GetDevic eDiscoveryStatus
Status Values 5--67....................................
Table 5--73: IBPASystem::GetDevic eDiscoveryStatus
Returns 5--67........................................
Table 5--74: IBPASystem::GetDevic eList Returns 5--69.......
Table 5--75: IBPASystemEvents::OnStateChange State
Val ue s 5 -- 7 1..........................................
Table 5--76: IBPASystemEvents::OnStateChange
Returns 5--71........................................
Table 5--77: IBPASystemEvents::OnT riggerIn Returns 5--72...
Table 5--78: IBPASystemEvents::OnT riggerOut Returns 5--73.
Table 5--79: IBPAAnalyzer::O pe n Returns 5--74.............
Table 5--80: IBPAAnalyzer::Close Returns 5--76.............
Table 5 --81: IBPAAnalyzer::GetPacketCount PacketType
Val ue s 5 -- 7 7..........................................
Table 5--82: IBPAAnalyzer::G etPacketCount Returns 5--78....
Table 5 --83: IBPAAnalyzer::GetPacket PacketType
Val ue s 5 -- 7 9..........................................
Table 5--84: IBPAAnalyzer::G etPacket Returns 5--80.........
Table 5 --85: IBPAAnalyzer::GetPrevPacketNumber
PacketType Values 5--82...............................
Table 5--86: IBPAAnalyzer::G etPrevPacketNumber
Returns 5--83........................................
Table 5 --87: IBPAAnalyzer::GetNextPacketNumber
PacketType Values 5--85...............................
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
ix
Table of Contents
Table 5--88: IBPAAnalyzer::G etNextPacketNumber
Returns 5--86........................................
Table 5 --89: IBPAAnalyzer::GetPacketInfo PacketType
Val ue s 5 -- 8 8..........................................
Table 5--90: IBPAAnalyzer::G etPacketInfo InfoType
Val ue s 5 -- 8 9..........................................
Table 5--91: IBPAAnalyzer::GetPacketInfo Radix Values 5--90.
Table 5--92: IBPAAnalyzer::G etPacketInfo Returns 5--90.....
Table 5--93: IBPAAnalyzer::Export FileType Values 5--92.....
Table 5--94: IBPAAnalyzer::Export ProtocolType Values 5--92.
Table 5--95: IBPAAnalyzer::Export Returns 5--93............
Table 5--96: IBPAAnalyzer::G etAcquisitionReport
Returns 5--95........................................
Table 5--97: IBPAAnalyzer::SetL2CAPConnectionProperties
Type values 5--97.....................................
Table 5--98: IBPAAnalyzer::SetL2CAPConnectionProperties
Returns 5--98........................................
Table 5--99: IBPAAnalyzer::GetL2CAPConnectionProperties
Type values 5--99.....................................
Table 5--100: IBPAAnalyzer::GetL2CAPConnectionProperties
Returns 5--100........................................
Table 5--101: IBPAAnalyzer::SetRFCOMMServerChannel
Type Values 5--101.....................................
Table 5--102: IBPAAnalyzer::SetRFCOMMServerChannel
Returns 5--101........................................
Table 5--103: IBPAAnalyzer::GetRFCOMMServerChannel
Type Values 5--103.....................................
Table 5--104: IBPAAnalyzer::GetRFCOMMServerChannel
Returns 5--103........................................
Table 5--105: IBPAHCISimple::Send Returns 5--105...........
Table 5--106: IBPAHCISimple::Get Returns 5--106............
Table 5--107: IBPAHCISimpleEvents::HCIEvent
Returns 5--107........................................
x
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Preface
This is the Programmer Manual for the BPA100 Series Bluetooth
Protocol Analyzer. This manual provides information about the
application programming interface of the BPA100 Series Bluetooth
Protocol Analyzer.
Related Manuals
Table i: Related manuals
Language Type Part number
English
Chinese
Japanese
English BPA100 Series Bluetooth Proto-
English BPA100 Series Bluetooth Proto-
BPA100 Series Bluetooth Protocol Analyzer Installation Manual
col Analyzer Software Version
2.3 User Manual
col Analyzer Software Version
2.3 Application Programming
Interfacer Manual
071-1121-00
071-1128-00
071-1129-00
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
xi
Preface
Contacting Tektronix
Phone 1-800-833-9200*
Address Tektronix, Inc.
Department or name (if known)
14200 SW Karl Braun Drive
P.O. Box 500
Beaverton, OR 97077
USA
Web site www.tektronix.com
Sales
support
Service support
Technical
support
* This phone number is toll free in North America. After office
hours, please leave a voice m ail message.
Outside North America, contact a Tektronix sales office or
distributor; see the Tektronix web site for a list of offices.
1-800-833-9200, select option 1*
1-800-833-9200, select option 2*
Email: techsupport@tektronix.com
1-800-833-9200, select option 3*
6:00 a.m. -- 5:00 p.m. Pacific time
xii
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Getting Started
Introduction
The Application Programming Interface (API) of the BPA100 Series
Bluetooth Protocol Analyzer is based on the Microsoft Component
Object Model (COM). The API allows you to control the protocol
analyzer with a user program on the Server or Remote Client.
Figure 1--1 depicts various ways the protocol analyzer can be
controlled.
Figure 1- 1: Controlling BPA100 Series Bluetooth Protocol Analyzer
Protocol analyzer Server: Computer where Tektronix Bluetooth
Protocol Analyzer device is connected and Tektronix Bluetooth
Protocol Analyzer application is installed.
Remote Clients: Computer that tries to connect to the Tektronix
Bluetooth Protocol Analyzer device connected to the Protocol
analyzer Server.
The Protocol analyzer application is called the server and the user
program is called the client.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
1- 1
Introduction
The following three cases are shown in Figure 1--1:
H Case 1 shows the user program running on the server and
H Case 2 shows the user program running on another computer and
H Case 3 shows the user program running on a UNIX workstation
The user program can be written in any language or programming
environment that supports the Microsoft Component Obje ct Model
(COM). Some examples are Visual C++, Visual Basic, and LabView.
communicating with the Protocol analyzer application using
Microsoft COM.
communicating with the Protocol analyzer using Microsoft
DCOM (Distributed COM).
and communicating with the Protocol analyzer application using
DCOM provided by a third party vendor.
General Characteristic
The following is a list of the general characteristics of the API:
H API is consistent with programming interfaces exported by othe r
Windows applications.
H All interfaces exported by the server are dual interfaces, which
supports static and dynamic binding.
H The Protocol analyzer application must be initialized before a
client tries to connect. This includes dismissing any errors that
occur at startup time.
NOTE. If a client attempts to connect before the appl ication is
initialized, an error message appears indicating access is denied.
H A client either launches a session automatically or connects to an
existing session of the server, if there is one.
H You must launch the serve r before t he remote client can connect
because Microsoft Windows 98 does not allow a client running
on a remote host to launch a session on the serve r automatically.
1- 2
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Introduction
H Clients hide the server’s window using the programming
interface. If the window is displayed, you can directly interact
with the server and the stat us bar of the main window displays
the connection status.
H The Protocol analyzer server continues to run after a client has
disconnected. The serve r window is always visible even when
clients are not connected.
H API operates within the main thread of the application.
H API supports multiple clients. Ensure that the clients do not
interfere with one another.
H There is no provision for an API client to block other clients.
Software Requirements
API is supported by Tektronix Bluetooth Protocol Analyzer V2.2.1
or higher. If you have an older version of the Tektronix Bluetooth
Protocol Analyzer application, you must upgrade to a recent version.
You can download the new version of t he Tektronix Bluetooth
Protocol Analyzer application from the Tektronix Web site:
http://www.tektronix.com/bpa_support.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
1- 3
Introduction
1- 4
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Objects and Interfaces
Overview
The application programming interface for the Protocol analyzer
consists of the following objects:
H BPAApplication. You can create a BPAApplication object to
connect to the application and obtain a reference to additional
objects. The BPAApplication object exports a single interface
called IBPAApplication.
H BPASystem. The BPASystem object provides methods for
controlling most of the functionality in the Tektronix BluetoothProtocol Analyzer GUI. The BPASystem object exports a single
interface called IBPASystem.
H BPASystemEvents. The BPASystemEvents object provides
methods for capturing events fired by the BPA application. The
BPASystemEvents object exports a single interface called
IBPASystemEvents.
H BPAAnalyzer. The BPAAnalyzer object provides methods for
analyzing the log file provided by the Protocol analyzer
Analyzer. The BPAAnalyzer object exports a single interface
called IBPAAnalyzer.
H BPAHCISimple. The BPAHCISimple object provides methods
for sending or receiving HCI command. The BPAHCISimple
object exports a single interface called IBPAHCISimple.
H BPAHCISimpleEvents. The BPAHCISimpleEvents object
provides methods for capturing events fired by the Protocol
analyzer hardware. The BPAHCISimpleEvents object exports a
single interface called IBPAHCISimpleEvents.
By default, all methods are synchronous and return the values after
completing an operation.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
1- 5
Objects and Interfaces
The object hierarchy is depicted by Figure 1--2.
Figure 1- 2: Object hierarchy
1- 6
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting up the API
Setting Up the API
In the following procedures, <install directory> refers to the
directory where the API client application has been installed on your
client machine. The install directory is C:\Program Files\Tektronix
Bluetooth Protocol Analyzer by default.
The type library to be used with the API is BPA100.tlb. After you
finish the following setup procedure, this file is located in C:\Pro-
gram Files\ Tektronix Bluetooth Protocol Analyzer\System\API
and in the <install directory>\System\API on your API client.
You have two methods of using the API with your client application:
H You can run the cli ent application locally on the server where
your Protocol Analyzer application is running. No special
setup is required once the Protocol Analyzer application is
installed. The following section, Running a client appl ication
on the server machine, shows how you c an run a client
application on the server.
H You can run your client application rem otely across the
network. In this case, both the server and the remote client
require special setup procedures. Refer to the section,
Running a Client Application across the Network, on
page 2--3.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 1
Setting Up the API
Running a Client Application on the Server Machine
If you are running a client application on the Server, no special set up
is required if the Tektronix Bluetooth Protocol Analyzer applicati on
has already been installed. You can just run the client application
that you have created.
To verify that a client application can conne ct to the Protocol
Analyzer Server, do the following steps:
1. Start the Protocol Analyzer application on the computer where
the Protocol Analyzer device is connected.
2. Run testclient.exe from <install directory>\Samples\API
Samples\VC++\test client.
2- 2
3. Click the connect button to check whether the client appli cation
connects to the Protocol Analyzer Server.
4. Click Exit.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
Running a Client Application across the Network
If you want to run the client application remotely across the network,
you must set up the API on the server machine and the client
machine. Use the following procedures as appropriate:
H Setting up the API on the Server Machine page 2--3
H Setting up the Client Machine on Windows 2000/NT page 2--20
H Setting up the Client Machine on Windows 98 page 2--37
H Setting up the Client Machine on Windows 95 page 2--46
H Setting up the Client Application on Other
Platforms page 2--54
Setting up the API on the Server Machine
Follow these steps to set up the API on the server:
1. Install and configure TCP/IP.
NOTE. If you have difficulty in configuring the network setup, contact
your system administrator.
2. Select the appropriate access type. You may choose share-level
access (page 2 --4) or user-level access (page 2--12) to the server
as provided by Microsoft Windows.
NOTE. For the API to work with share-level access, authentication is
turned off and any COM client application can call in to a COM
server running on the server.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 3
Setting Up the API
Share-Level Access
Follow these steps to set up the server to be shared among different
users on a network:
1. Click Start> Run. The Run dialog box appears.
2. Type dcomcnfg in the Open field and click OK. The Distributed
COM configuration properties box appears.
2- 4
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 5
Setting Up the API
3. Click the Default Properties tab.
2- 6
4. Select None in the Default Authentication Level drop down list.
5. Click the Applications tab and select the Tektronix Bluetooth
Protocol Analyzer Application in the Applications list.
a. Click the Properties button to display the Tektronix BPA
Application Properties window as shown in the following
figure.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
b. Select None in Authentication Level drop down list.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 7
Setting Up the API
c. Click the Location tab.
2- 8
d. Ensure that Run application on this computer check box is
selected.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
e. Click the Security tab.
Setting Up the API
f. Select the Use custom access permissions check box.
H Click Edit to open Registry Value Permissions window.
H Click Add to displa y Add Users and Groups window.
H Select Eve ryone in the Names list.
H Click Add andthenclickOK.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 9
Setting Up the API
g. Select the Use custom launch permissions check box.
H Click Edit to open Registry Value Permissions window.
H Click Add to displa y Add Users and Groups window.
H Select Eve ryone in the Names list.
H Click Add andthenclickOK.
h. Click the Identity tab.
2- 10
i. Select Theinteractiveusercheck box.
j. Click Apply andthenclickOK.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
6. Exit the Protocol Analyzer application and restart. Do not
attempt to ma ke any connections before restarting the Protocol
Analyzer application.
This completes the Protocol Analyzer Server setup for operation
with a remote client application using share-level access.
NOTE. You can switch between user-level access and share-level
access later by repeating the procedure starting from step 2 of
Setting up the API on the Server Machine on page 2--3.
Next, you need to set up the cli ent application t o connect to the
Protocol Analyzer Server. Select the appropriate setup:
H Setting up the Client Machine on Windows 2000/NT,see
page 2--20
H Setting up the Client Machine on Windows 98, seepage2--37
H Setting up the Client Machine on Windows 95, seepage2--46
H Setting up the Client Application on Other Platforms, see
page 2--54
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 11
Setting Up the API
User-level access
The default network setup for the Protocol Analyzer under Windows
is compatible with clients operating with user-level access. With
these settings, the client machine and server must be logged in to the
same account and domain t o make a connection. If this is too
restrictive, use share-level access (see page 2--4) or talk to your
network administrator.
To set up the Protocol Analyzer Server for user-level access (default
settings), follow these steps:
1. Click Start > Run. T he Run dia log box appears.
2. Type dcomcnfg in the Open field and click OK. The Distributed
COM configuration properties box appears.
2- 12
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 13
Setting Up the API
3. Click the Default Properties tab.
2- 14
4. Select Connect in the Default Authentication Level drop down
list.
5. Click the Applications tab and select the Tektronix Bluetooth
Protocol Analyzer Application in the Applications list.
a. Click the Properties button to display the Tektronix BPA
Application Properties window as shown in the following
figure.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
b. Select Default in Authentication Level drop down list.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 15
Setting Up the API
c. Click the Location tab.
2- 16
d. Ensure that the Run application on this computer check
box is selected.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
e. Click the Security tab.
Setting Up the API
f. Follow these steps:
H Select Use default access permissions check box.
H Select Use default launch permissions check box.
H Select Use default configuration permissions check box.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 17
Setting Up the API
g. Click the Identity tab.
2- 18
h. Select The launching user check box.
i. Click Apply andthenclickOK.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
6. Exit the Protocol Analyzer application, and restart. Do not
attempt to ma ke any connections before restarting the Protocol
Analyzer application.
This completes the setup of the Protocol Analyzer Server for
operation with a remote client application using user-level access or
Windows 2000/NT user authentication.
NOTE. You can switch between user-level access and share-level
access later by repeating the procedure starting from step 2 of
Setting up the API on the Server machine on page 2-- 3.
Next, you need to set up the cli ent application t o connect to the
Protocol Analyzer Server. Select the appropriate setup:
H Setting up the Client Machine on Windows 2000/NT,see
page 2--20
H Setting up the Client Machine on Windows 98, seepage2--37
H Setting up the Client Machine on Windows 95, seepage2--46
H Setting up the Client Application on Other Platforms, see
page 2--54
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 19
Setting Up the API
Setting up the Client Machine on Windows 2000/NT
After you set up the Protocol Analyzer Server, you must set up the
client application using the following procedure:
1. Install and configure TCP/IP.
2. Load the Tektronix Bluetooth Protocol Analyzer application
software CD.
3. Double-click on API client SW\Disk1\Setup.exe.
4. Select the appropriate access type, share-level access (page 2--20)
or user-level access (page 2--29). You must set up the client
application to match the access level you chose for the Protocol
Analyzer Server:
NOTE. You can switch between user-level access and share-level
access later by repeating the procedure from Step 4 onwards.
Share-level Access for Windows 2000/NT
To set up a client a pplication to access a Protocol Analyzer server
that is set up for share-level access, do the following procedure:
NOTE. You must have administrative permissions on your computer.
1. Click Start > Run. T he Run dia log box appears.
2- 20
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
2. Type dcomcnfg in the Open field and click OK. The Distributed
COM configuration properties box appears.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 21
Setting Up the API
3. Click the Default Properties tab.
2- 22
4. Select None in the Default Authentication Level drop down list.
5. Click the Applications tab and select the Tektronix Bluetooth
Protocol Analyzer Application in the Applications list.
a. Click the Properties button to display the Tektronix BPA
Application Properties window as shown in the following
figure.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
b. Select None in Authentication Level drop down list.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 23
Setting Up the API
c. Click the Location tab.
2- 24
d. Clear the Run application on this compute r check box.
e. Select the Run application on the following computer
check box and type the name of the Protocol Analyzer
Server in the adjacent field.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
f. Click the Security tab.
Setting Up the API
g. Select the Use custom access permissions check box.
H Click Edit to open Registry Value Permissions window.
H Click Add to open Add Users and Groups window.
H Select Eve ryone in the Names list.
H Click Add andthenclickOK.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 25
Setting Up the API
h. Select the Use custom launch permissions check box.
H Click Edit to open Registry Value Permissions window.
H Click Add to open Add Users and Groups window.
H Select Eve ryone in the Names list.
H Click Add andthenclickOK.
2- 26
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
i. Click the Identity tab.
Setting Up the API
j. Select The Interactive user check box.
k. Click Apply andthenclickOK.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 27
Setting Up the API
6. To verify that the setup is complete:
H Run <install directory>\Samples\API Samples\VC++\test
client\testclient.exe on the client.
H Click the connect button to check if the client application can
connect to the Protocol Analyzer Server.
This completes the set up of the Protoc ol Analyzer Server and the
client machine for running your client application across the
network.
2- 28
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
User-Level Access for Windows 2000/NT
The default network settings are compatible with clients operating
with user-level access. With these settings, the client machine and
server must be logged in to the same account and domain to make a
connection. If this is too restrictive, use share-l evel access
(page 2--20) or talk to your network administrator.
To set up a client application to access a Protocol Analyzer server
that is setup for user-level access, do the following procedure:
1. Click Start > Run. T he Run dia log box appears.
2. Type dcomcnfg in the Open field and click OK. The Distributed
COM configuration properties box appears.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 29
Setting Up the API
2- 30
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
3. Click the Default Properties tab.
Setting Up the API
4. Select Connect in the Default Authentication Level drop down
list.
5. Click the Applications tab and select the Tektronix Bluetooth
Protocol Analyzer Application in the Applications list.
a. Click the Properties button to display the Tektronix BPA
Application Properties window as shown in the following
figure.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 31
Setting Up the API
2- 32
b. Select Default in Authentication Level drop down list.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
c. Click the Location tab.
Setting Up the API
d. Clear the Runapplicationonthiscomputercheck box.
e. Select the Run application on the following computer
check box and type the name of the Protocol Analyzer
Server in the adjacent field.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 33
Setting Up the API
f. Click the Security tab.
2- 34
g. Follow these steps.
H Select Use default access permissions check box.
H Select Use default launch permissions check box.
H Select Use default configuration permissions check box.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
h. Click the Identity tab.
Setting Up the API
i. Select The launching user check box.
j. Click Apply andthenclickOK.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 35
Setting Up the API
6. To verify that the setup is complete:
H On the client machine, run testclient.exe from the directory
<install directory>\Samples\API Samples\VC++\test client\.
The Tektronix Test API client applic ation window appears.
H Click the Connect button to check if the client application can
connect to the Protocol Analyzer Server.
This completes the setup of the Protocol Analyzer Server and the
client machine for running your client application across the
network.
2- 36
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting up the Client Machine on Windows 98
After you set up the Protocol Analyzer Server, you must set up the
client application using the following procedure:
1. Install and configure TCP/IP.
2. Load the Tektronix Bluetooth Protocol Analyzer application
software CD.
3. Double-click on API client SW\Disk1\Setup.exe.
4. Download and install the following from the Microsoft Web site.
Restart the computer after each of these installations.
H Distributed COM (DCOM) for Windows 98 (DCOM 98,
version 1.1)
Setting Up the API
H dcomcnfg (DCOM configuration utility)
NOTE. The dcomcnfg utility runs only if user-level access is enabled.
See step 5.
5. Select the appropriate access type, share-level access (page 2--37)
or user-level access (page 2--41). You must set up the client
application to match the access level you chose for the Protocol
Analyzer Server.
NOTE. You can switch between user-level access and share-level
access later by repeating the procedure from Step 5 onwards.
Share-Level Access for Windows 98
To set up a client application to access a Protocol Analyzer server
that is setup for share-level access, do the following procedure:
1. Click Start> Settings> Control Panel to open the Control Panel
window.
2. Double-click Network to open the Network window as shown in
the following figure.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 37
Setting Up the API
2- 38
3. Click the Access Control tab.
4. Select the Share-level access control check box.
5. Click OK.
NOTE. If prompted, i nsert the Windows 98 disk or provide a file path
to the stored Windows 98 files.
6. The System Settings Change dialog box appears. Click Ye s .
7. Restart the client machine.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
8. Go to the directory <install directory>\System\API and run
Share level Access Client.reg. A dialog box appears, indicating
successful registration. Click OK.
9. Restart the client machine.
10. Click Start > Run.
11. Either locate the regedit file using Browse or type regedit.
12. Click the following registry key: HKEY_CLASSES_ROOT\AppID\{141DF06A--04FA--11d6--B2DC--00062912F3D2}
13. Click Edit>New>StringValue, add a named value --
RemoteServerName.
14. Click the new value -- RemoteServerName and select Edit >
Modify. The Edit String dia log box appears.
15. Enter the computer name of the Protocol Analyzer Server. This is
the name used to identify the Protocol Analyzer Server on the
network. Click OK.
16. To verify that the setup is complete:
H On the client machine, run testclient.exe from the directory
<install directory>\Samples\API Samples\VC++\test client\.
The Tektronix Test API client applic ation window appears.
H Click the connect button to check if the client application can
connect to the Protocol Analyzer Server.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 39
Setting Up the API
This completes the setup of the Protocol Analyzer Server and the
client application for running a client application across the network.
NOTE. You can switch between user-level access and share-level
access later by repeating the procedure from step 2 of Setting up the
Client Machine on Windows 98 on page 2--37.
2- 40
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
User-Level Access for Windows 98
To set up a client application to access a Protocol Analyzer server
that is setup for user-level access, do the following procedure:
1. Click Start > Settings > Control Panel to open the Control
Panel Window.
2. Double-click Network to display the Network window.
3. Click the Access Controltab.
4. Select the User-level access control check box.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 41
Setting Up the API
5. In the Obtain list of users and groups from field, type the name of
the domain to validate user access.
6. Click OK.
7. Restart the client machine.
8. Go to the directory <install directory>\System\API and run User
level Access Client.reg.
9. Restart the client machine.
10. Click Start > Run.
11. Either locate the dcomcnfg file using Browse or type dcomcnfg.
12. Click OK. The Distributed COM Configuration Properties
window appears as shown in the following figure.
2- 42
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
13. Double-click Tektronix BPA Application in the Applications
tab.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 43
Setting Up the API
14. Click the Location tab.
H Clear the Run application on this computer check box.
H Select the Run application on the following computer check
box and type the name of the Protoc ol Analyzer Server in the
adjacent field.
2- 44
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
15. To verify that the setup is complete:
H On the client machine, run testclient.exe from the directory
<install directory>\Samples\API Samples\VC++\test client\.
The Tektronix Test API client applic ation window appears.
H Click the connect button to check if the client application can
connect to the Protocol Analyzer Server. (The first time you
connect, it may take a few minutes.)
This completes the setup of the Protocol Analyzer Server and the
client machine for running a client application across the network.
NOTE. You can switch between user-level and share-level access
later by repeating the procedure from step 2 of Setting up the Client
Machine on Windows 98 on page 2--37.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 45
Setting Up the API
Setting up the Client Machine on Windows 95
After you set up the Protocol Analyzer Server, you must set up the
client application using the following procedure:
1. Install and configure TCP/IP.
2. Load the Tektronix Bluetooth Protocol Analyzer software CD.
3. Double-click API client SW\Disk1\Setup.exe.
4. Download and install the following from the Microsoft Web site.
Restart the computer after each of these installations.
H Distributed COM (DCOM) for Windows 95 (DCOM 95,
version 1.1)
H dcomcnfg (DCOM configuration utility)
NOTE. The dcomcnfg utility runs only if user-level access is enabled.
See step 5.
5. Select the appropriate access type, share-level access (page 2--47)
or user-level access (page 2--49). You must set up the client
application to match the access level you chose for the Protocol
Analyzer Server.
NOTE. You can switch between user-level access and share-level
access later by repeating the procedure from Step 2 onwards.
2- 46
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
Share-Level Access for Windows 95
To set up a client application to access a Protocol Analyzer server
that is setup for share-level access, do the following procedure:
1. Click Start > Settings > Control Panel to open the Control
Panel window.
2. Double-click Network to open the Network window.
3. Click the Access Control tab.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 47
Setting Up the API
NOTE. If prompted, i nsert the Windows 95 disk or provide a file path
to the stored Windows 95 files.
4. Select the Share-level access control check box.
5. Click OK.
6. The System Settings Change dialog box appears. Click Ye s .
7. Restart the client machine.
8. Go to the directory <install directory>\System\API and run Share
level Access Client.reg. A dialog box appears, indicating
successful registration. Click OK.
9. Restart the client machine.
10. Click Start > Run.
11. Either locate the re gedit file using Browse or type regedit.
12. Click the following registry key: HKEY_CLASSES_ROOT\Ap-
pID\{141DF06A--04FA--11d6--B2DC --00062912F3D2}
13. Click Edit>New>StringValue, add a named value -RemoteServerName.
14. Click the new value -- RemoteServerName and select
Edit > Modify. The Edit String dialog box appears.
15. Enter the computer name of the Protocol Analyzer Server. This is
the name used to identify the Protocol Analyzer Server on the
network. Click OK.
To verify that the setup is complete:
H On the client machine, run testclient.exe from the directory
<install directory>\Samples\API Samples\VC++\test client\. The
Tektronix Test API client application window appears.
2- 48
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
H Click the connect button to check if the client application can
connect to the Protocol Analyzer Server.
This completes the setup of the Protocol Analyzer Server and the
client application for running your client application across the
network.
NOTE. You can switch between user-level access and share-level
access later by uninstalling the Tektronix API client application and
DCOM 95 using the Windows Control Panel and repeating the
procedure from step 2 of Setting up the Client Machine on
Windows 95 on page 2--46.
User-Level Access for Windows 95
To set up a client application to access a Protocol Analyzer server
that is set up for user-level access, do the following procedure:
1. Click Start > Settings > Control Panel to open the Control
Panel window.
2. Double-click Network to open the Network window.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 49
Setting Up the API
3. Click the Access Control tab.
2- 50
4. Select User-level access control check box.
5. In the Obtain list of users and groups from field, type the name of
the domain to validate user access.
6. Click OK.
7. Restart the client machine.
8. Go to the directory <install directory>\System\API and run User
level Access Client.reg.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
9. Restart the client machine.
10. Click Start > Run.
11. Either locate the dcomcnfg file using Browse or type dcomcnfg.
12. Click OK. The Distributed COM Configuration Properties
window appears as shown in the following figure.
13. Double-click Tektronix BPA Application in the Applications
tab.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 51
Setting Up the API
14. Click the Location tab.
H Clear the Run application on this computer check box.
H Select the Run application on the following computer check
box and type the name of the Protoc ol Analyzer Server in the
adjacent field.
2- 52
15. To verify that the setup is complete:
H Run <install directory>\Samples\API Samples\VC++\test
client\testclient.exe on the client.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Setting Up the API
H Click the connect button to see if the client application can
connect to the Protocol Analyzer Server. (The first time you
connect, it may take a few minutes.)
This completes the set up of the Protoc ol Analyzer Server and the
client machine for running a client application across the network.
NOTE. You can switch between user-level access and share-level
access later by repeating the procedure from step 2 of Setting up the
Client Machine on Windows 95 on page 2--46.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 53
Setting Up the API
Setting up the Client application on Other Platforms
If the client application requires the type library, you can generate it
on your platform using BPA100.idl in <install directory>\System\API\src.
Follow these steps:
1. Ensure that DCOM is working on your platform.
2. Merge <install directory>\System\API\Client.reg into your
registry.
3. Merge <install directory>\System\API\Share--level Access
Client.reg or User--level Access Client .reg into your registry,
depending on the type of access control you chose for the
Protocol Analyzer Server.
4. Add a string value named RemoteServerName to the key
HKEY_CLASSES_ROOT\AppID\{141DF06A--04FA--11d6--B2DC --00062912F3D2}
5. Enter the computer name of the Protocol Analyzer Server as this
string value. This is the na me used to identify the Protocol
Analyzer Server on the network.
This completes the set up of the protocol analyzer for operating with
a remote client application using a platform other than Windows.
2- 54
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Connecting to the Protocol Analyzer Server
Client applications connect to the Protocol Analyzer Server by
creating a BPAApplication Object. For example, in Microsoft Visual
Basic:
Example
’Establish Connection to BPA
Dim App As Object
Set App = CreateObject(”BPA100.BPAApplication”)
Once the Application Object is created, the client application can
call methods on it to get refere nces to BPASystem and BPAAnalyzer
Objects.
Setting Up the API
Disconnecting from the Protocol Analyzer Server
A client application connected to the Protoc ol Analyzer Server can
disconnect by removing the reference to the BPAApplication Object.
For example, in Microsoft Visual Basic:
Example
’Disconnect from BPA.
Set App = Nothing
References to any BPASystem or BPAModule Objects that were
obtained must also be removed.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
2- 55
Setting Up the API
2- 56
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Programming Examples
Programming Examples
The Protocol Analyzer Server exports dual interfaces with both
dispatch and vtable interface characteristics.The dispat ch dual
interface uses run time (dynamic) binding to resolve method calls.
This type of interface is useful in interpretive and scripting
environments, where you cannot use header files and type libraries
for static binding.The vtable dual interface uses static binding to
resolve method calls using header files and type libraries.
For more information, see these examples on the pages to follow:
H Microsoft Visual Basic Client Using Dispatch Interfaces
H Microsoft Visual Basic Client Using VTABLE Interfaces
NOTE. You can use the dispatch dual interface for additional code
examples on specific methods.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
3- 1
Programming Examples
Microsoft Visual Basic Client Using Dispatch Interfaces
Dim Application As Object
DimSystemAsObject
Private Sub Form_Load()
’Create the COM interfaces required
Set Application = CreateObject(”BPA100.BPAApplication”)
Set System= Application.GetSystem
End Sub
Private Sub StartLogButton_Click()
’Start Acquisition
System.Start (”C:\API Log File.tbpa”)
End Sub
Private Sub StopLogButton_Click()
’Stop Acquisition
System.Stop
End Sub
3- 2
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Programming Examples
Microsoft Visual Basic Client Using VTABLE Interfaces
Dim Application As BPAApplication
DimSystemAsBPASystem
Private Sub Form_Load()
’Create the COM interfaces required
Set Application = New BPA100.BPAApplication
Set System = Application.GetSystem
End Sub
Private Sub StartLogButton_Click()
’Start Acquisition
System.Start (”C:\API Log File.tbpa”)
End Sub
Private Sub StopLogButton_Click()
’Stop Acquisition
System.Stop
End Sub
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
3- 3
Programming Examples
3- 4
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Status and Events
Status and Events
All methods in al l interfaces of API return an HRESULT (or
SCODE). Refer to BPAErrors.h for possible error codes.
Additional error information is communicated as follows:
H Objects that use the dispatch portion of the dual interface can use
the exception information argument of the Invoke method.
H Objects that use the Vtable portion of the dual interface can use
error objects. When an HRESULT indicates an error, the client
can call the standard function GetErrorInfo() to get more detailed
information about the error.
H When a method returns an error, output arguments are undefined
and should not be used.
Refer to the sample programs for examples on handling errors.
Error Handling
The API returns HRESULT (or SCODE) for all interface methods.
Refer to the file “bpaerrors.h” in <install directory>\System\API\Src\bpaerrors.h> for possible error codes.
Additional error information is communicated as follows:
H Objects that use the dispatch dual interface can use the exception
information argument of the IDispatch::Invoke method.
H Objects that use the vtabl e dual interface can use error objects.
When an HRESULT indicates an error, the client can call the
standard function GetErrorInfo() for deta iled information a bout
the error.
H When a method returns an error, output arguments are undefined
and should not be used.
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
4- 1
Status and Events
Server Message Boxes
In the Protocol Analyzer graphical user interface, there are instances
where you are asked to confirm a particular operation. For example,
once the acquisition is stopped in log file mode, you are asked
whether to open the current log file.
Since it is not possible to ask questions through the API, the
application always proceeds with the original operation as though the
questions were never asked. In the previous example, the load
operation proceeds without asking any confirmation.
Modal message boxes that are norm ally displayed in the Protocol
Analyzer user interface will not be displayed when a cli ent is
connected to the server.
4- 2
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Syntax and Commands
Command Groups
This section lists the commands organized by functional group. The
Command Descriptions section, starting on page 5--7, lists all
commands alphabetically.
The BPA100 Series application programming interface conforms to
Tektronix standard code s and format s excepts where noted.
BP AAplication Commands
BPAApplication commands connect to the application and obtain a
reference to additional objects. The BPAApplication object exports a
single interface called IBPAApplication.
Table 5- 1: BPAAplication commands
Header Description
ShowWindow Shows/hides the BPA100 Series Server’s
main window
GetVersion Retrieves the current version of the
specified subsystem
GetBDAddress Retrieves the address of the attached
BPA100 Series device
GetAnalyzer Returns the interface pointer for the
BPAAnalyzer object
GetSystem Returns the interface pointer for the
BPASystem object
GetHCISimple Returns the interface pointer for the
BPAHCISimple object
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
5- 1
Command Groups
BPASystem Commands
BPASystem commands control most of the functionality in the
BPA100 Bluetooth Protocol Analyzer GUI. The BPASystem object
exports a single interface called the IBPASystem.
Table 5- 2: BPASystem commands
Header Description
Start Sets the analyzer to start mode
Stop Sets the analyzer to stop mode
Pause Pauses logging of the acquired data
Resume Resumes logging of packet data from the
current Protocol Analyzer session
GetDeviceStatus Retrieves the sync status of the device
GetSessionInfo Gets the session information for the current
log session
SetHoppingMode Sets the BPA100 Series hopping mode
GetHoppingMode Gets the current settings of the hopping
mode
SetCorrelation Sets correlation settings for the acquisition
GetCorrelation Gets correlation value from the acquisition
setup
SetResync Sets resync settings for the acquisition
GetResync Gets resync values from the acquisition
setup
SetDataWhitening Sets the data whitening flag for acquisitions
GetDataWhitening Gets the data whitening information from
the acquisitions settings
5- 2
SetAcquisitionMode Configures the logging mode of the BPA100
Series
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Command Groups
Table 5- 2: BPASystem commands (Cont.)
Header Description
GetAcquisitionMode Gets the current settings of the logging
mode in the acquisition settings
SetAcquistionDefault Sets the acquisition settings to factory
default values
SetLowLevelTrigger Sets the low level trigger values from a file
GetLowLevelTrigger Saves the current low level trigger values to
the specified file
ActivateLowLevelTrigger Activates or deactivates the current
low-level trigger setup
SetHighLevelTrigger Sets the high-level trigger values from a file
GetHighLevelTrigger Saves the current high-level trigger values
onto the specified file
ActivateHighLevelTrigger Activates or deactivates the current
high-level trigger setup
SetErrorPacketGeneration Sets the error packet values from a file
GetErrorPacketGeneration Saves the current error packet generated
values to the specified file
ActivateErrorPacketGeneration Activates or deactivates the current error
packet generation setup
SetDataFilter Sets baseband data filter
GetDataFilter Retrieves the current baseband data filter
settings
ActivateDataFilter Activates or deactivates the current
baseband data filter setup
SetDecryptionSettings Sets the decryption settings to specified
values
GetDecryptionSettings Gets the current decryption settings
ActivateDecryption Activates or deactivates decryption
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
5- 3
Command Groups
Table 5- 2: BPASystem commands (Cont.)
Header Description
SetDecryptionDefault Sets the decryption settings to factory
DoDeviceDiscovery Searches for neighbouring Bluetooth
GetDeviceDiscoveryStatus Returns the device discovery operation
GetDevicesList Returns the list of devices found during
default values
devices
status
device discovery
BPASystemEvents Commands
BPASystemEvents commands capture events fired by the BPA
application.
Table 5- 3: BPASystemEvents commands
Header Description
OnStateChange This event is invoked whenever the BPA100
OnTriggetIn This event is invoked whenever the Trigger
OnTriggerOut This event is invoked whenever the Trigger
changes state
In port is asserted
Out port is asserted
5- 4
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
BPAAnalyzer Commands
BPAAnalyzer commands analyze a log file c aptured by the BPA100
Series.
Table 5- 4: BPAAnalyzer commands
Header Description
Open Opens the log file
Close Closes the log file
GetPacketCount Retrieves the number of packets in the
GetPacket Retrieves the specified packet for a given
Command Groups
specified protocol layer
protocol layer
GetPacketInfo Retrieves the decoded information of a
specified packet depending on the specified
information type
GetPrevPacketNumner Searches for the packet previous to the
specified packet and type in the Baseband
layer and returns the index of the matching
packet
GetNextPacketNumner Searches for the packet next to the
specified packet and type in the Baseband
layer and returns the index of the matching
packet
Export Exports the specified protocol layer’s
packets of the current log file to a CSV or
TXT or WAV file given beginning and ending
packet number
GetAcquisitionReport Gets the acquisition report that was created
for the log file
SetL2CAPConnectionProperties Assigns the L2CAP connection property
type for a given packet
GetL2CAPConnectionProperties Retrieves the current L2CAP connection
property assignment for a given pac
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
5- 5
Command Groups
Table 5- 4: BPAAnalyzer commands (Cont.)
Header Description
SetRFCOMMServerChannel Assigns the RFCOMM server channel
GetRFCOMMServerChannel Retrieves the RFCOMM server channel
BPAHCISimple Commands
BPAHCISimple commands send or receive HCI commands.
Table 5- 5: BPAHCISimple commands
assignments for a specified packet.
assignments for a specified packet
Header Description
Send Sends an HCI message
Get Gets the last received HCI event message
BPAHCISimpleEvents Command
BPAHCISimpleEvents command captures events fired by the
BPA100 Series hardware.
Table 5- 6: BPAHCISimpleEvents commands
Header Description
HCIEvent Captures events whenever the BPA100
receives an HCI event from the hardware
5- 6
BPA100 Series Bluetooth Protocol Anal yzer Programmer Manual
Loading...