Primary Dual Interface for Analyzer | Protocol Solutions User Documentation

IUsbAnalyzer Dual Interface

IUsbAnalyzer interface is the primary interface for the UsbAnalyzer object. It derives from the IAnalyzer interface that implements the common functionality for all Teledyne LeCroy Analyzers.

Class ID: 136D64A4-3CD5-4b41-974A-C7039E3FC292

App ID: CATC.USBTracer

COM server: UsbSuite.exe

IUsbAnalyzer IID: C37E7603-E3E5-48b4-8F79-080DBB543F0C

IAnalyzer::GetVersion

C++

HRESULT GetVersion ( 
[in] EAnalyzerVersionType version_type, 
[out, retval] WORD* analyzer_version );

Retrieves the current version of the specified subsystem.

Parameters
version_type	Subsystem whose version is requested. EAnalyzerVersionType enumerator has the following values: ANALYZERVERSION_SOFTWARE ( 0 ) Software ANALYZERVERSION_BUSENGINE ( 1 ) Bus engine ANALYZERVERSION_FIRMWARE ( 2 ) Firmware
analyzer_version	Current version of subsystem requested. Value is encoded in BCD. Example: 0x0312 would mean version 3.12

Parameters

version_type

Subsystem whose version is requested. EAnalyzerVersionType enumerator has the following values:

ANALYZERVERSION_SOFTWARE ( 0 ) Software

ANALYZERVERSION_BUSENGINE ( 1 ) Bus engine

ANALYZERVERSION_FIRMWARE ( 2 ) Firmware

analyzer_version

Current version of subsystem requested.

Value is encoded in BCD.

Example: 0x0312 would mean version 3.12

Return values
ANALYZERCOMERROR_INVALIDVERSIONTYPE	Specified version type is invalid.
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	Analyzer device is not connected.

Example: WSH

Visual Basic

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))

Set Analyzer = WScript.CreateObject("CATC.USBTracer")

SwVersion = CLng(Analyzer.GetVersion(0))

SwOutput = ((SwVersion And &HFF00) / 256) & "." & String(2 - Len(SwVersion And &HFF), "0") & (SwVersion And &HFF)

BEVersion = CLng(Analyzer.GetVersion(1))

BEOutput = ((BEVersion And &HFF00) / 256) & "." & String(2 - Len(BEVersion And &HFF), "0") & (BEVersion And &HFF)

FwVersion = CLng(Analyzer.GetVersion(2))

FwOutput = ((FwVersion And &HFF00) / 256) & "." & String(2 - Len(FwVersion And &HFF), "0") & (FwVersion And &HFF)

MsgBox "Software: " & SwOutput & VbCrLf & "BusEngine: " & BEOutput & VbCrLf & 

"Firmware: " & FwOutput

Example: C++

C++

HRESULT      hr;

IUsbAnalyzer*   poUsbAnalyzer;

// create UsbAnalyzer object

if ( FAILED( CoCreateInstance(
   CLSID_UsbAdvisor,
NULL, CLSCTX_SERVER,
IID_IUsbAnalyzer,
 (LPVOID *)&poUsbAnalyzer ) )

return;

WORD sw_version;

try
{
sw_version = poUsbAnalyzer ->GetVersion( ANALYZERVERSION_SOFTWARE );
}

catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(),  _T("UsbAnalyzer client"), MB_OK );

else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1;
}

TCHAR buffer[20];

_stprintf( buffer, _T("Software version:%X.%02X"), // BCD, so Hex value -> Decimal value

HIBYTE(sw_version), 

LOBYTE(sw_version) );

IAnalyzer::GetSerialNumber

C++

HRESULT GetSerialNumber ( 
 [out, retval] WORD* serial_number );

Retrieves the serial number of the Analyzer device.

Return values
ANALYZERCOMERROR_INVALIDVERSIONTYPE	Specified version type is invalid.
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	Analyzer device is not connected.

Example: WSH

Visual Basic

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Set Analyzer = WScript.CreateObject("CATC.USBTracer")
MsgBox "Serial number: " & CLng(Analyzer.GetSerialNumber())

Example: C++

C++

HRESULT         hr;
IUsbAnalyzer*   poUsbAnalyzer;

// create UsbAnalyzer object
if ( FAILED( CoCreateInstance(
                CLSID_UsbAdvisor,
                NULL, CLSCTX_SERVER,
                IID_IUsbAnalyzer,
                (LPVOID *)&poUsbAnalyzer ) )
		return;
WORD serial_number;

try
{
serial_number = poUsbAnalyzer ->GetSerialNumber();
}

catch ( _com_error& er)
{

if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(),  _T("UsbAnalyzer client"), MB_OK );

else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1;

}

TCHAR buffer[20];
_stprintf( buffer, _T("Serial number: %X"), 
HIBYTE(serial_number), 
LOBYTE(serial_number) );

IAnalyzer::OpenFile

C++

HRESULT OpenFile ( 
[in] BSTR file_name, 
[out, retval] IDispatch** trace );

Opens a trace file.

Parameters
file_name	String providing the full pathname to the trace file
trace	Address of a pointer to the UsbTrace object primary interface

Return values
ANALYZERCOMERROR_UNABLEOPENFILE	Unable to open file.
ANALYZERCOMERROR_WRONGCALL	Error when trying to access the opened trace when it is being released and destroyed.

Remarks

UsbTrace object is created via this method call, if call was successful.

In rare cases, the method may return ANALYZERCOMERROR_WRONGCALL error. This may happen when client code is trying to open an already opened trace file, while it is being released and destroyed. Subsequent method calls will reopen the trace file.

Example: WSH

Visual Basic

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Set Analyzer = WScript.CreateObject("CATC.USBTracer")
Set Trace = Analyzer.OpenFile (CurrentDir & "Input\errors.usb")

Example: C++

C++

HRESULT         hr;
IUsbAnalyzer*   poUsbAnalyzer;

// create UsbAnalyzer object
if ( FAILED( CoCreateInstance(
                CLSID_UsbAdvisor,
                NULL, CLSCTX_SERVER,
                IID_IUsbAnalyzer,
                (LPVOID *)&poUsbAnalyzer ) )
		return;

// open trace file
IDispatch* trace;
try
{
trace = poUsbAnalyzer->OpenFile( m_szRecFileName );
}

catch ( _com_error& er)
{

if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(),  _T("UsbAnalyzer client"), MB_OK );

else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1;
}

// query for VTBL interface
IUsbTrace* usb_trace;
 	hr = trace->QueryInterface( IID_IUsbTrace, (LPVOID *)&usb_trace );
trace->Release();

if( FAILED(hr) )
	return;

IAnalyzer::StartGeneration

C++

HRESULT StartGeneration ( 
[in] BSTR gen_file_name, 
[in] long gen_mode, 
[in] long loop_count );

Starts USB 2.0 traffic generation from the file.

Parameters
gen_file_name	String providing the full pathname to the generation file. If a valid name, the file is opened after any pre-existing Generation File is closed in accordance with the behavior set forth by Bit 31 in the gen_mode parameter. If NULL string, it just closes any existing Generation File.
gen_mode	Generation mode: Bit 0: 0 = bitstream; 1 = IntelliFrame Bit 31: 0 = Load gen_file_name only if: Different than pre-existing Generation Filename OR The gen_file_name file is already loaded but has been changed since the time it was loaded OR The generation mode (bit 0) is different than the previous invocation. Leaving this bit set to 0 allows a file to be generated repeatedly without having to be re-parsed or downloaded to the Analyzer hardware, saving time. 1 = Reload gen_file_name unconditionally.
loop_count	Number of times to repeat: -1 = loop forever 1 through 16381 executes generation file that number of times.

Parameters

gen_file_name

String providing the full pathname to the generation file. If a valid name, the file is opened after any pre-existing Generation File is closed in accordance with the behavior set forth by Bit 31 in the gen_mode parameter. If NULL string, it just closes any existing Generation File.

gen_mode

Generation mode:

Bit 0: 0 = bitstream; 1 = IntelliFrame

Bit 31: 0 = Load gen_file_name only if:

Different than pre-existing Generation Filename OR

The gen_file_name file is already loaded but has been changed since the time it was loaded OR
The generation mode (bit 0) is different than the previous invocation. Leaving this bit set to 0 allows a file to be generated repeatedly without having to be re-parsed or downloaded to the Analyzer hardware, saving time.

1 = Reload gen_file_name unconditionally.

loop_count

Number of times to repeat:

-1 = loop forever

1 through 16381 executes generation file that number of times.

Return values
ANALYZERCOMERROR_UNABLEOPENFILE	Unable to open file
ANALYZERCOMERROR_UNABLESTARTGENERATION	Unable to start generation (USB 3.0 generation is running, invalid state, or other)
E_INVALIDARG

Remarks

Used to load a .utg file and begin generating traffic.

IAnalyzer::StopGeneration

C++

HRESULT StopGeneration ( );

Stops any current USB 2.0 generation in progress.

Return values
ANALYZERCOMERROR_UNABLESTARTGENERATION	Unable to stop generation (invalid state, etc.)

Remarks

Stop any current traffic generation.

IAnalyzer::StartRecording

C++

HRESULT StartRecording ( 
[in] BSTR ro_file_name );

Starts recording with specified recording options.

Parameters
ro_file_name	String providing the full pathname to the recording options file. If the parameter is omitted, then recording starts with the default recording options. To start recording without applying any recording options, pass “DO_NOT_CHANGE_RECORDING_OPTIONS”.

Parameters

ro_file_name

String providing the full pathname to the recording options file.

If the parameter is omitted, then recording starts with the default recording options. To start recording without applying any recording options, pass “DO_NOT_CHANGE_RECORDING_OPTIONS”.

Return values
ANALYZERCOMERROR_EVENTSINKNOTINSTANTIATED	Event sink was not instantiated.
ANALYZERCOMERROR_UNABLESTARTRECORDING	Unable to start recording.

Remarks

After recording starts, this function returns. The Analyzer continues recording until it is finished or until a StopRecording method call is performed. During the recording, the events are sent to the event sink.

The recording options file is the file with extension .rec created by the USB Protocol Suite application. You can create such a file by selecting Setup > Recording Options from the USB Protocol Suite application menu, changing the recording options in the dialog, and clicking Save.

Example: VBScript

Visual Basic

<OBJECT 
RUNAT=Server
ID = Analyzer 
CLASSID = "clsid:0B179BB3-DC61-11d4-9B71-000102566088" 
>
</OBJECT>

<INPUT TYPE=TEXT   VALUE="" NAME="TextRecOptions">
<SCRIPT LANGUAGE="VBScript">
<!--
Sub BtnStartRecording_OnClick
		On Error Resume Next
  		Analyzer.StartRecording TextRecOptions.value
  		If Err.Number <> 0 Then
    			MsgBox Err.Number & ":" & Err.Description
  		End If
End Sub
-->
</SCRIPT>

Example: C++

C++

IUsbAnalyzer* usb_analyzer;
BSTR         ro_file_name;
. . . 

try
{
usb_analyzer->StartRecording( ro_file_name )
}

catch ( _com_error& er)
{
if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(),  _T("UsbAnalyzer client"), MB_OK );

else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1;
}

IAnalyzer::StopRecording

C++

HRESULT StopRecording ( 
[in] BOOL abort_upload );

Stops a recording started by the StartRecording method.

Parameters
abort_upload	TRUE, if caller wants to abort upload, no trace file is created. FALSE, if you want to upload the recorded trace.

Parameters

abort_upload

TRUE, if caller wants to abort upload, no trace file is created.

FALSE, if you want to upload the recorded trace.

Return values
ANALYZERCOMERROR_EVENTSINKNOTINSTANTIATED	Event sink was not instantiated.
ANALYZERCOMERROR_UNABLESTOPRECORDING	Error stopping recording.

Remarks

Stops recording started by the StartRecording method. The event is issued when recording is actually stopped if the parameter of method call was FALSE.

Example: VBScript

Visual Basic

<OBJECT
RUNAT=Server
ID = Analyzer 
CLASSID = "clsid:0B179BB3-DC61-11d4-9B71-000102566088" 
>
</OBJECT>

<SCRIPT LANGUAGE="VBScript">
<!--
Sub BtnStopRecording_OnClick
		On Error Resume Next
		Analyzer.StopRecording True
		If Err.Number <> 0 Then
			MsgBox Err.Number & ":" & Err.Description
		End If
End Sub
-->
</SCRIPT>

Example: C++

C++

IUsbAnalyzer* usb_analyzer;
. . . 

try
{
usb_analyzer->StopRecording( FALSE )
}

catch ( _com_error& er)
{

if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(),  _T("UsbAnalyzer client"), MB_OK );

else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1;
}

IAnalyzer::MakeRecording

C++

HRESULT MakeRecording ( 
[in] BSTR ro_file_name, 
[out, retval] IDispatch** trace );

Makes a recording with the specified recording options file.

Parameters
ro_file_name	String providing the full pathname to recording options file. If the parameter is omitted, then recording starts with the default recording options.
trace	Address of a pointer to the UsbTrace object primary interface

Remarks

This method acts like StartRecording method but does not return until recording is completed.

UsbTrace object is created via this method call, if call was successful.

Example: WSH

Visual Basic

CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Set Analyzer = WScript.CreateObject("CATC.USBTracer")
Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")

Example: C++

C++

IDispatch* trace;
IUsbAnalyzer* usb_analyzer;
BSTR       ro_file_name;
HRESULT    hr;
. . . 

try
{
trace = usb_analyzer->MakeRecording( ro_file_name )
}

catch ( _com_error& er)
{

if (er.Description().length() > 0)
::MessageBox( NULL, er.Description(),  _T("UsbAnalyzer client"), MB_OK );

else
::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1;
}

// query for VTBL interface
IUsbTrace* usb_trace;
	hr = trace->QueryInterface( IID_IUsbTrace, (LPVOID *)&usb_trace );

trace->Release();

IAnalyzer::LoadDisplayOptions

C++

HRESULT LoadDisplayOptions ( 
[in] BSTR do_file_name );

Loads display options that apply for traces opened or recorded later.

Parameters
do_file_name	String providing the full pathname to display options file

Return values
ANALYZERCOMERROR_UNABLELOADDO	Unable to load display options file.

Remarks

Use this method if you want to filter traffic of some type. The display options loaded by this method call apply only on trace files opened or recorded after this call.

Display options file is the file with extension .opt created by the USB Protocol Suite application. You can create such a file by selecting Setup > Display Options… from the USB Protocol Suite application menu, changing the display options in the dialog, and clicking Save.

Example

See ITrace::ApplyDisplayOptions.

IAnalyzer::GetRecordingOptions

C++

HRESULT GetRecordingOptions ( 
[out, retval] IDispatch** recording_options );

Retrieves the primary interface for access to recording options.

Parameters
recording_options	Address of a pointer to the UsbRecOptions object primary interface

Remarks

UsbRecOptions object is created via this method call, if call was successful.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.USBTracer")
Set RecOptions = Analyzer.GetRecordingOptions

Example: C++

C++

IUsbAnalyzerPtr poUsbAnalyzer;

// Create UsbAnalyzer object.
if( FAILED( poUsbAnalyzer.CreateInstance( CLSID_UsbAdvisor ) ) )
     return;

// Get recording options
IDispatchPtr       rec_opt;
IUsbRecOptions Ptr usb_rec_opt;

try
{
     rec_opt = poUsbAnalyzer->GetRecordingOptions(); 
     usb_rec_opt = rec_opt; // Query for IUsbRecOptions interface

     // Use IUsbRecOptions methods

     ...

}

catch (_com_error& er)
{
     if (er.Description().length() > 0)
          ::MessageBox( NULL, er.Description(), _T("UsbAnalyzer client"), MB_OK );

     else
          ::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

     return 1;
}

IUsbAnalyzer::StopRecordingAndWaitForTrace

C++

HRESULT StopRecordingAndWaitForTrace
    ( [out, retval] IDispatch** trace );

Stops recording started by the StartRecording method and returns the pointer to the trace object created.

Parameters
trace	Address of a pointer to the UsbTrace object primary interface

Return values
ANALYZERCOMERROR_UNABLESTOPRECORDING	Error when stopping recording
ANALYZERCOMERROR_WRONGCALL	Error when trying to access trace when it is being destroyed.

Remarks

This method stops recording started by the StartRecording method and does not return until the recording is uploaded and a trace object related to this recording is created. In contrast, for StopRecording, no event is issued when recording is stopped by this method.

In rare cases, the method may return ANALYZERCOMERROR_WRONGCALL error. This may happen when recording stopped by itself (for example, because buffer is full), and the method call occurs when the recorded trace is being released and destroyed. Subsequent method calls will reopen the recorded trace. To avoid this issue, use a recording-buffer size that is big enough, so that the method call will occur when recording is still in progress and recording buffer is not full.

Example: WSH

Visual Basic

' Extract the script name.
ScriptName = Right(WScript.ScriptFullName, Len(WScript.ScriptFullName) - 
InstrRev(WScript.ScriptFullName, "\") ) 
Set Analyzer = WScript.CreateObject( "CATC.UsbTracer" )
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))

' In the code below, we perform four sequential recordings and
' save the traces recorded in the current folder.

For I = 1 To 4
    'Tell the CATC UWB analyzer to start recording.
    Analyzer.StartRecording ( CurrentDir & "Input\test_ro.rec" )

    ' Imitation of some activity - just sleep for 3 seconds.
    ' Some real traffic generation code might be put here.

    WScript.Sleep 3000    

    ' Tell the analyzer to stop recording and give the trace acquired. 

    Set Trace = Analyzer.StopRecordingAndWaitForTrace
   

    ' Save the trace in the current folder.

    Trace.Save CurrentDir & "Output\usb_seqrec_data" & CStr(I) & ".usb"

Next

Set Trace = Nothing

'Release the analyzer.

Set Analyzer = Nothing

MsgBox "Sequential recordings are completed." & String(2, 13) & "Look for recorded traces in the folder : "  &  CurrentDir & "Output", 64, ScriptName

Example: C++

(Raw code without using type library. All error handling is omitted for simplicity)

C++

IUsbAnalyzer* pAnalyzer = NULL; 

// Create UsbAnalyzer object.

if ( FAILED( CoCreateInstance( CLSID_UsbAdvisor, NULL, CLSCTX_SERVER, 

IID_IUsbAnalyzer, (LPVOID *)&pAnalyzer ) )

		return;

BSTR ro_file_name = SysAllocString( L"test_ro.rec" );

BSTR bstr_trace_name;

IDispatch* trace = NULL;

for( int i = 0; i < 4; i++ )

{

if( FAILED( pAnalyzer ->StartRecording( ro_file_name ) )

return;  // Error handling and resources releasing should be done.

       // Fake generation.

       Sleep(3000); 

       if( FAILED( Analyzer->StopRecordingAndWaitForTrace( &trace ) ) ) 

return;  // Error handling and resources releasing  should be done.

IUsbTrace2* usbTrace = NULL;

	// Query for IUsbTrace2 interface.

if( FAILED( trace->QueryInterface( IID_IUsbTrace2, (LPVOID*)usbTrace ) ) )

return; // Error handling and resources releasing should be done.

       OLECHAR trace_name[_MAX_PATH];

       swprintf ( trace_name, "test_data%u.usb", i );

       SysAllocString( bstr_trace_name );

       // Save the trace recorded to the current folder

       usbTrace->Save( bstr_trace_name );

       // Release the trace object.

       trace->Release();

       usbTrace->Release();

       SysFreeString( bstr_trace_name ); // Free BSTR.

}

pAnalyzer->Release();          // Release the analyzer object.

SysFreeString( ro_file_name ); // Free BSTR.


Example: C++: (Microsoft® Example: C++ specific, using type library. All error handling is omitted for simplicity.)

IUsbAnalyzerPtr   pAnalyzer = NULL;

pAnalyzer.CreateInstance( __uuidof(UsbAdvisor) );

if( !pAnalyzer ) return;

IUsbTrace2Ptr trace = NULL;

for( int i = 0; i < 4; i++ )

{

	// Start recording using recording options file 'test_ro.rec' located in 

// the current folder.

               pAnalyzer->StartRecording( _bstr_t("test_ro.rec") );

               // Fake generation: just sleep for 3 seconds.

               Sleep(3000); 

               trace = pAnalyzer->StopRecordingAndWaitForTrace();

               TCHAR trace_name[_MAX_PATH];

               sprintf( trace_name, "test_data%u.uwb", i );

		// Save the trace recorded in the current folder.

               trace->Save( _bstr_t(trace_name) );

               // Release the trace object.

		trace = NULL; 

}

IUsbAnalyzer::ApplicationFolder (property)

C++

HRESULT get_ApplicationFolder( [out, retval] BSTR *app_folder );

Retrieves the full local path to the folder where the USB Protocol Suite application was installed and registered as a COM server.

Parameters
app_folder	Pointer to string variable indicating USB Protocol Suite application folder

Remarks

This property allows client applications to access some important files used by the USB Protocol Suite application, such as recording options, display options, and trace files, in places relative to the USB Protocol Suite application folder. If later the USB Protocol Suite application is re-installed to another location, the client code does not have to be changed to reflect this event.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")

' Open trace file 'some_trace.usb' in the USB Suite folder.

Set Trace = Analyzer.OpenFile( Analyzer.ApplicationFolder & "some_trace.usb" )

' Save opened trace as 'some_trace1.usb' in the USB Suite folder.

Trace.Save Analyzer.ApplicationFolder & "some_trace1.usb"

...

Example: C++

C++

HRESULT  hr;
IUsbAnalyzer* poUsbAnalyzer;

// Create UsbAnalyzer object.

if ( FAILED( CoCreateInstance( CLSID_UsbAdvisor, NULL, CLSCTX_SERVER, 

IID_IUsbAnalyzer, (LPVOID *)&poUsbAnalyzer ) )

		return;

BSTR app_folder;

hr = poUsbAnalyzer->get_ApplicationFolder( &app_folder );

// . . . Do something with app_folder.

SysFreeString( app_folder ); // Free BSTR resources.

poUsbAnalyzer->Release();    // Release analyzer object.

IUsbAnalyzer::ApplicationDataFolder (property)

C++

HRESULT get_ApplicationDataFolder( [out, retval] BSTR *app_folder );

Retrieves the full local path to the folder for user-alterable data, such as scripts, traces, and default options files.

Parameters
app_folder	Pointer to string variable indicating the USB Protocol Suite user-modifiable data folder

Remarks

This property allows client applications to access some important files used by the USB Protocol Suite application, such as recording options, display options, and trace files, in places relative to the USB Protocol Suite application folder, and the C:\Users\Public\Documents\LeCroy folder. If later the USB Protocol Suite application is re-installed to another location, the client code does not have to be changed to reflect this event.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")

' Open trace file 'some_trace.usb' in a user-modiable folder.
Set Trace = Analyzer.OpenFile(Analyzer. Appy licationDataFolder & "some_trace.usb")

' Save opened trace as 'some_trace1.usb' in a user-modiable folder.
Trace.Save Analyzer. ApplicationDataFolder & "some_trace1.usb"

...

Example: C++

C++

HRESULT  hr;

IUsbAnalyzer* poUsbAnalyzer;

// Create UsbAnalyzer object.

if ( FAILED( CoCreateInstance( CLSID_UsbAdvisor, NULL, CLSCTX_SERVER, 

IID_IUsbAnalyzer, (LPVOID *)&poUsbAnalyzer ) )

		return;

BSTR app_folder;

hr = poUsbAnalyzer->get_ApplicationDataFolder( &app_folder );

// . . .  Do something with app_folder.

SysFreeString( app_folder ); // Free BSTR resources.

poUsbAnalyzer->Release();    // Release analyzer object.

IUsbAnalyzer::StartUsb3Generation

C++

HRESULT StartUsb3Generation([in,defaultvalue("")] BSTR gen_file_name);

Starts generating USB traffic.

Parameters
gen_file_name	USB 3.0 Exerciser script file name to execute. If this parameter is an empty string, the last executed script is repeated.

Parameters

gen_file_name

USB 3.0 Exerciser script file name to execute.

If this parameter is an empty string, the last executed script is repeated.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	No Analyzer connected
ANALYZERCOMERROR_UNABLESTARTGENERATION	The Analyzer cannot start for one of the following reasons: Script has compiling error. Analyzer is currently running or paused. Analyzer is currently used by another client. License for trainer device was not purchased. USB 2.0 generation is running.

Return values

ANALYZERCOMERROR_ANALYZERNOTCONNECTED

No Analyzer connected

ANALYZERCOMERROR_UNABLESTARTGENERATION

The Analyzer cannot start for one of the following reasons:

Script has compiling error.
Analyzer is currently running or paused.
Analyzer is currently used by another client.
License for trainer device was not purchased.
USB 2.0 generation is running.

Remarks

This function returns after generation starts. Analyzer continues generating until it finishes or until the StopUsb3Generation or PauseUsb3Generation method call is performed.

During generation, events are sent to the event sink.

The script file should have the file extension “.usb3g”. It can be created by either the USB Protocol Suite text editor or any plain-text editor.

Example: WSH (1)

See Automation\Example: WSH\Usb3Exerciser.vbs

Example: WSH(2)

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the USB 3.0 Voyager Exerciser to start generation.

Analyzer. StartUsb3Generation CurrentDir & " \Input\Usb3ScriptExample.usb3g"

Dim doneGeneration

doneGeneration = 0

' Repeat Generation 49 more times.

For RepeatCount = 1 To 49

Do While doneGeneration = 0

		WScript.Sleep 100

Loop

Analyzer.StartUsb3Generation

DoneGeneration = 0

Next

' Release the analyzer.

WScript.DisconnectObject Analyzer

' WScript.Echo "USBAnalyzer object has been disconnected."

Set Analyzer = Nothing

' WScript.Echo "Quitting WScript..."

WScript.Quit

' Handler of the event fired when recorded trace is created 

' (after recording and uploading).

'

Sub Analyzer_OnStatusReport(ByVal subsystem, ByVal state, ByVal percent_done )

On Error Resume Next

  if state = 400 Then

    doneGeneration = 1

    WScript.Echo "Generation finished"

  End If

End Sub

Example: VBScript

Visual Basic

<OBJECT

RUNAT=Server

ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292"

>

</OBJECT>

...<INPUT TYPE=TEXT   VALUE="" NAME="PathToScript"> ...

...<INPUT TYPE=BUTTON VALUE="" NAME="BtnStartUSB3Generaion"> ...

<SCRIPT LANGUAGE="VBScript">

<!--

Sub BtnStartUSB3Generaion_OnClick

		On Error Resume Next

		Analyzer.StartUsb3Generation PathToScript.value

		If Err.Number <> 0 Then

			MsgBox Err.Number & ":" & Err.Description

		End If

End Sub

-->

</SCRIPT>

Example: C++

C++

IUsbAnalyzerPtr usb_analyzer;

. . . 

try

{

	const char* gen_script_name =   "C:\\Usb3ScriptExample.usb3g";

Usb_analyzer->StartUsb3Generation(_bstr_t( gen_script_name ) );

}

catch (_com_error& er)

{

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(),  _T("USBAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("USBAnalyzer client"), MB_OK );

return 1;

}

IUsbAnalyzer::StopUsb3Generation

C++

HRESULT StopUsb3Generation ();

Stops USB 3.0 generation started by the StartUsb3Generation method.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

Stops generation started by the StartUsb3Generation method. Generation stops if the analyzer is either running or paused, and the analyzer then returns to the idle state.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the CATC USB analyzer to start generation.

Analyzer.StartUsb3Generation "example.usb3g"

WScript.Sleep 3000

' Tell the analyzer to stop recording.

Analyzer.StopUsb3Generation()

Example: VBScript

Visual Basic

<OBJECT

RUNAT=Server

ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292"

>

</OBJECT>

<SCRIPT LANGUAGE="VBScript">

<!--

Sub BtnStopUsb3Generation_OnClick

		On Error Resume Next

		Analyzer.StopUsb3Generation

		If Err.Number <> 0 Then

			MsgBox Err.Number & ":" & Err.Description

		End If

End Sub

-->

</SCRIPT>

Example: C++

C++

IUsbAnalyzerPtr usb_analyzer;

. . . 

try

{

usb_analyzer ->StopUsb3Generation();

}

catch (_com_error& er)

{

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(),  _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1;

}

IUsbAnalyzer::PauseUsb3Generation

C++

HRESULT PauseUsb3Generation ();

Pauses the currently running USB 3.0 generation.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.
ANALYZERCOMERROR_WRONGCALL	Analyzer is not running

Remarks

Pauses the generation started by the StartUsb3Generation method. Generation pauses if the Exerciser is running. However, the pause command cannot immediately pause traffic generation in all cases. During execution of a generation script (.usb3g) file, some Send Packet instructions might be queued in an output FIFO, and then pausing only takes effect after this buffer empties.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the CATC USB analyzer to start generation.

Analyzer.StartUsb3Generation "some_example.usb3g"

WScript.Sleep 3000

' Tell the analyzer to stop recording.

Analyzer.PauseUsb3Generation

Example: VBScript

Visual Basic

<OBJECT

RUNAT=Server

ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292"

>

</OBJECT>

<SCRIPT LANGUAGE="VBScript">

<!--

Sub BtnPauseUsb3Generation_OnClick

		On Error Resume Next

		Analyzer.PauseUsb3Generation

		If Err.Number <> 0 Then

			MsgBox Err.Number & ":" & Err.Description

		End If

End Sub

-->

</SCRIPT>

Example: C++

C++

IUsbAnalyzerPtr usb_analyzer;

. . . 

try

{

usb_analyzer->PauseUsb3Generation();

}

catch (_com_error& er)

{

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(),  _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1;

}

IUsbAnalyzer::ResumeUsb3Generation

C++

HRESULT ResumeUsb3Generation ();

Resumes a pause USB 3.0 generation.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

Resumes the generation paused by the PauseUsb3Generation method. The generation returns to the running state from the paused state.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the CATC USB analyzer to start generation.

Analyzer.StartUsb3Generation "example.Usbg"

WScript.Sleep 3000

' Tell the analyzer to stop recording.

Analyzer.PauseUsb3Generation()

WScript.Sleep 3000

Analyzer.ResumeUsb3Generation()

Example: VBScript

Visual Basic

<OBJECT 

RUNAT=Server

ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292"

>

</OBJECT>

<SCRIPT LANGUAGE="VBScript">

<!--

Sub BtnResumeUsb3Generation_OnClick

		On Error Resume Next

		Analyzer.ResumeUsb3Generation

		If Err.Number <> 0 Then

			MsgBox Err.Number & ":" & Err.Description

		End If

End Sub

-->

</SCRIPT>

Example: C++

C++

IUsb3AnalyzerPtr usb_analyzer;

. . . 

try

{

usb_analyzer->ResumeUsb3Generation();

}

catch (_com_error& er)

{

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(),  _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1;

}

IUsbAnalyzer::UsbUnplugPlug

C++

HRESULT UsbUnplugPlug();

Calling this method causes the V_BUS power between the Host and the Device connected through the Analyzer A and B USB ports to be broken for 1 second, simulating a unplug-plugin cycle. This is the recommended method of creating plug-in scenarios.

IUsbAnalyzer3 interface

The IUsbAnalyzer3 interface is the third interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 1D96A60E-AA3A-45e1-B6D5-C6AA27E65910

IUsbAnalyzer3:: IssueManualTrig

HRESULT IssueManualTrig ();

Issues manual trigger event to cause force trigger in analyzer engine.

Remarks

This method works with recording options where trigger mode is defined as manual trigger.

IUsbAnalyzer4 interface

The IUsbAnalyzer4 interface is the fourth interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: D793E9EE-58EE-4237-9D2A-41DBB61DCDF8

IUsbAnalyzer4::GetRecordingStatus

C++

HRESULT GetRecordingStatus (
[out] VARIANT* is_trigged,
[out] VARIANT* is_done);

This method can be used to poll recording state of analyzer after recording start. The method returns useful running state information like happening trigger condition and recording finish. Use this method to poll the status of recording and go to the next step according to the polling result.

Parameters
is_triggered	Pointer to Boolean variable indicating whether the analyzer is triggered or not.
is_done	Pointer to Boolean variable indicating whether the recording process is finished or not.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

WaitForRecordingStatus can be used instead of this method. That method doesn’t block normal software operation and is the recommended method.

IUsbAnalyzer4::ResetUsb3Trainer

C++

HRESULT ResetUsb3Trainer ([in] int is_device_mode);

Resets and initializes the analyzer unit in either Host trainer or Device trainer mode without running any script.

Parameters
is_device_mode	Specify desired mode: 1 for Device mode, 0 for Host mode.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

IUsbAnalyzer4::IsUsb3GenerationIdle

C++

HRESULT IsUsb3GenerationIdle ([out] VARIANT* gen_idle);

Returns the status of generation process after generation has begun. Use this method to poll the status of generation and go to the next step according to the polling result.

Parameters
gen_idle	Pointer to Boolean variable indicating whether generation is done or not.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

WaitForUsb3GenerationIdle can be used instead of this method. That method doesn’t block software normal operation and is the recommended method.

IUsbAnalyzer4::SwitchV_BUS

C++

HRESULT  SwitchVBus ( [in] long  switch_off);

Switches V_BUS off or on in the USB3 trainer without running a script.

Parameters
switch_off	If “1” switch off V_BUS, other switch on V_BUS

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

IUsbAnalyzer5 interface

The IUsbAnalyzer5 interface is the fifth interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 47CCA8A8-C4AC-4b90-ABD1-16DC2A5351FE

IUsbAnalyzer5::BindUnit (Restricted and Unsupported: Not for Customer Use.)

C++

HRESULT BindUnit ([in] WORD box_sn);

Call this method when the API is used to control multiple analyzer units. After creating any analyzer object (for each unit), you must bind the analyzer object to the desired unit by calling this method.

Note: This method is used by Teledyne LeCroy to enable the USB 3.1 Hub Compliance licensed feature on Voyagers. It is only enabled when that license key is purchased. The use of this method by end customers outside of Hub Compliance is not supported by Teledyne LeCroy.

This method is deprecated in favor of BindUnitEx, which supports units with a longer Serial Number format.

Parameters
box_sn	Specifies target UNIT serial number.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.
ANALYZERCOMERROR_UNABLESTARTRECORDING	Multiple Unit Automation License is not available

Remarks

Method will fail if it is not licensed.

IUsbAnalyzer5::MergeTraceFiles

C++

HRESULT MergeTraceFiles   (
[in] BSTR file_name_1, 
[in] BSTR file_name_2, 
[in] BSTR output_file_name)

The method is used for merging two trace files in one trace.

Parameters
file_name_1	String parameter specifies first input file path
file_name_2	String parameter specifies second input file path
output_file_name	String parameter specifies output file path

Return values
ANALYZERCOMERROR_UNABLETOMERGEFILES	Unable to merge files; check file paths and make sure they are not open

IUsbAnalyzer6 interface

The IUsbAnalyzer6 interface is the sixth interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 866DA1BD-9AD4-4627-A32A-C0F229684300

IUsbAnalyzer6::WaitForUsb3GenerationIdle

C++

HRESULT WaitForUsb3GenerationIdle (
[in] long wait_time_milisec,
[out] VARIANT* spent_time_milisec, 
[out] VARIANT* is_done);

This method replaces IsUsb3GenerationIdle. The method polls internally for generation running and returns when generation finishes. The method will return if specified the timeout is passed and generation is still running to prevent hangs/block conditions.

Parameters
wait_time_milisec	Specifies timeout for waiting before return in milliseconds
spent_time_milisec	Pointer to long value which returns spent time in this method
is_done	Pointer to Boolean value indicating generation done or timeout happened

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

IUsbAnalyzer6::WaitForRecordingStatus

C++

HRESULT WaitForUsb3GenerationIdle (
[in] long wait_time_milisec, 
[in] long desired_status, 
[out] VARIANT* spent_time_milisec, 
[out] VARIANT* is_done);

This method replaces GetRecordingStatus. The method polls internally for analyzer running and returns when the analyzer reaches its desired state(s). The method will return if the specified timeout is passed and the analyzer has not reached its desired state(s).

Parameters
wait_time_milisec	Specifies timeout for waiting before return in milliseconds
desired_state	Specify desired analyzer state(s) (see remarks) to return from method
spent_time_milisec	Pointer to long value which returns spent time in this method
is_done	Pointer to Boolean value indicating desired state has been reached or timeout happened

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

State value can be a combination of the following values:

RSTAT_DONE: 0x4000
RSTAT_TRIGGERED: 0x2000
RSTAT_WAITING_FOR_SYNC_REC: 0x1000

IUsbAnalyzer7 interface

The IUsbAnalyzer7 interface is the seventh interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 13D7A1C9-6753-42A5-BFE0-6F55FB0C0FA4

IUsbAnalyzer7::GetLicensedCapability

C++

HRESULT GetLicensedCapability( 
[in] BSTR feature_title, 
[out, retval] BOOL* is_licensed)

The method identifies the license availability of any feature in any connected USBAnalyzer device. This method helps API users to change or limit their own software functionality according to the licensed features of the connected unit.

Parameters
feature_title	Specifies the feature name in a string. The list of available features can be found in the license dialog in Teledyne LeCroy’s USB Protocol Suite application.
is_licensed	Pointer to Boolean value indicates whether the feature is available or not.

Return values
E_INVALIDARG	feature_name parameter is not a valid feature title

Remarks

If there is no connected device, the is_licensed parameter returns false for any feature. Therefore, it is required that you check the device connection before any license check to get a valid result.

If there is more than one device, the API should call the BindUnit() method to bind the object to a specific device before calling this method, otherwise the methods returns the minimum license from all connected devices.

IUsbAnalyzer8 interface

The IUsbAnalyzer8 interface is the eightth interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 3A362B48-4222-403A-9B65-CED0E0A59DE8

IUsbAnalyzer8::GetHardwareInfo

C++

HRESULT GetHardwareInfo ( 
 [out, retval] int* info)

The method returns the product hardware type. The UsbAnalyzer software and automation API is capable of working with different types of USB analyzer hardware. However, because some capabilities are different between different products and analyzer hardware, API users may use this method to find what analyzer hardware is connected.

Parameters
info	Pointer to int value indicates the analyzer hardware type. The value enumeration is: TARGETANALZYER_5K = 0, TARGETANALZYER_2500 = 1, TARGETANALZYER_2500H = 2, TARGETANALZYER_ADVISOR = 3, TARGETANALZYER_MOBILE_HS = 4, TARGETANALZYER_MOBILE_T2 = 5, // The above analyzers are no longer supported TARGETANALZYER_VOYAGER = 6, TARGETANALZYER_ADVISOR_T3 = 7, TARGETANALZYER_VOYAGER_M3X = 8, TARGETANALZYER_VOYAGER_M310 = 9, TARGETANALZYER_reserved = 10, TARGETANALZYER_MERCURY_T2 = 11, TARGETANALZYER_ reserved2 = 12, TARGETANALZYER_VOYAGER_M310C = 13, TARGETANALZYER_MERCURY_T2C = 14, TARGETANALZYER_MERCURY_T2P = 15, TARGETANALZYER_VOYAGER_M310P = 16, TARGETANALZYER_VOYAGER_M4X = 17, TARGETANALZYER_VOYAGER_M310E = 18, TARGETANALZYER_VOYAGER_M480X = 19, TARGETANALZYER_VOYAGER_M4120 = 20

Parameters

info

Pointer to int value indicates the analyzer hardware type.

The value enumeration is:

TARGETANALZYER_5K = 0,

TARGETANALZYER_2500 = 1,

TARGETANALZYER_2500H = 2,

TARGETANALZYER_ADVISOR = 3,

TARGETANALZYER_MOBILE_HS = 4,

TARGETANALZYER_MOBILE_T2 = 5,

// The above analyzers are no longer supported

TARGETANALZYER_VOYAGER = 6,

TARGETANALZYER_ADVISOR_T3 = 7,

TARGETANALZYER_VOYAGER_M3X = 8,

TARGETANALZYER_VOYAGER_M310 = 9,

TARGETANALZYER_reserved = 10,

TARGETANALZYER_MERCURY_T2 = 11,

TARGETANALZYER_ reserved2 = 12,

TARGETANALZYER_VOYAGER_M310C = 13,

TARGETANALZYER_MERCURY_T2C = 14,

TARGETANALZYER_MERCURY_T2P = 15,

TARGETANALZYER_VOYAGER_M310P = 16,

TARGETANALZYER_VOYAGER_M4X = 17,

TARGETANALZYER_VOYAGER_M310E = 18,

TARGETANALZYER_VOYAGER_M480X = 19,

TARGETANALZYER_VOYAGER_M4120 = 20

Return values
ANALYZERCOMERROR_INVALIDVERSIONTYPE	If there is no connected unit, or more than one unit connected, or the connected hardware could not be identified.

Remarks

If there is no connected device, the method returns an error.

If there is more than one device, the API should call the BindUnit() method to bind the object to a specific device before calling this method, otherwise the methods returns an error.

IUsbAnalyzer8::IsSupportSSP

C++

HRESULT IsSupportSSP ( 
 [out, retval] BOOL* is_support)

The method returns whether the product supports USB3.1 SSP protocol or not. This includes both analyzer/exerciser engines. In addition to supporting SSP protocol by product, specific licenses should be included to be able to work with SSP protocol engines.

Parameters
is_support	Pointer to Boolean value that indicates SSP support.

Return values
ANALYZERCOMERROR_INVALIDVERSIONTYPE	If there is no connected unit, or more than one unit connected, or the connected hardware could not be identified.

Remarks

If there is no connected device, the method returns an error.

If there is more than one device, the API should call the BindUnit() method to bind the object to a specific device before calling this method, otherwise the methods returns an error.

IusbAnalyzer9 interface

The IUsbAnalyzer9 interface is the 9th interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 38024874-326B-4C5E-A5A1-820B0311E7DF

IusbAnalyzer9::ApplyRecordingOptions

C++

HRESULT ApplyRecordingOptions 
           ( [in] BSTR ro_file_name );

This method applies recording option settings before start recording/exerciser. This method is another alternative to passing recording options through StartRecording() method and is used in scenarios that analyzer hardware needs some other initializations like CrossSync settings before recording start.

Parameters
ro_file_name	reference to desired recording option path.

Return values
ANALYZERCOMERROR_UNABLESTARTRECORDING	If loading recording option fails for any reason.

IusbAnalyzer10 interface

The IUsbAnalyzer10 interface is the 10th interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: B00652D4-B649-42AB-BCFF-13123DA33A00

IUsbAnalyzer10::SetPersistentDecoding

C++

HRESULT SetPersistentDecoding ( [in] BOOL enable )

USB protocol analyzer provides capability to keep all decoding information persistent, so it would boost performance of opening files in next tries. This capality is off by default in calling OpenFile for opening trace files, but API users could use this new API method to enable/disable this functionality.

Parameters
enable	A Boolean value that specifies the persistent decoding state.

Remarks

By enabling this capability, each file keeps some extra decoding information besides the trace file in the .tmp folder. This increases hard disk space usage for each trace, so users need to consider that.

IUsbAnalyzer10::GetPersistentDecoding

C++

HRESULT GetPersistentDecoding ( [out, retval] BOOL* is_enabled )

Parameters
is_enabled	A pointer to a Boolean value that returns the persistent decoding state.

IUsbAnalyzer11 interface

The IUsbAnalyzer11 interface is the 11th interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 0D79B6FE-B74D-4441-804C-BFCB345EC736

IUsbAnalyzer11::StartPDGeneration

C++

HRESULT StartPDGeneration ([in, defaultvalue("")] BSTR gen_file_name);

Starts generating Power Delivery traffic.

Parameters

gen_file_name

Power Delivery generation script file name to execute.

If this parameter is an empty string, the last executed script is repeated.

Return values

ANALYZERCOMERROR_ANALYZERNOTCONNECTED

No Analyzer connected

ANALYZERCOMERROR_UNABLESTARTGENERATION

Analyzer cannot start for one of the following reasons:

Script has compiling error.

Analyzer is currently running or paused.

Analyzer is currently used by another client.

License for trainer device was not purchased.

Remarks

This function returns after PD generation starts. Analyzer continues generating until it finishes or until the StopPDGeneration method is called.

The script file should have the file extension “.updg”. Either the USB Protocol Suite text editor or any plain-text editor can create it.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the PD Exerciser to start generation.

Analyzer.StartPDGeneration "C:\\PDScriptExample.updg"

Dim doneGeneration

doneGeneration = 0

' Repeat Generation 49 more times.

For RepeatCount = 1 To 49

Do While doneGeneration = 0

		WScript.Sleep 100

Loop

Analyzer.StartPDGeneration

DoneGeneration = 0

Next

' Release the analyzer.

WScript.DisconnectObject Analyzer

' WScript.Echo "USBAnalyzer object has been disconnected."

Set Analyzer = Nothing

' WScript.Echo "Quitting WScript..."

WScript.Quit

' Handler of the event fired when recorded trace is created 

' (after recording and uploading).

'

Sub Analyzer_OnStatusReport(ByVal subsystem, ByVal state, ByVal percent_done )

On Error Resume Next

  if state = 400 Then

    doneGeneration = 1

    WScript.Echo "Generation finished"

  End If

End Sub

Example: VBScript

Visual Basic

<OBJECT

RUNAT=Server

ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292"

>

</OBJECT>

...<INPUT TYPE=TEXT   VALUE="" NAME="PathToScript"> ...

...<INPUT TYPE=BUTTON VALUE="" NAME="BtnStartPDGeneraion"> ...

<SCRIPT LANGUAGE="VBScript">

<!--

Sub BtnStartPDGeneraion_OnClick

		On Error Resume Next

		Analyzer.StartPDGeneration PathToScript.value

		If Err.Number <> 0 Then

			MsgBox Err.Number & ":" & Err.Description

		End If

End Sub

-->

</SCRIPT>

Example: C++:

IUsbAnalyzerPtr usb_analyzer;

. . . 

try

{

	const char* gen_script_name = "C:\\PDScriptExample.updg";

Usb_analyzer->StartPDGeneration(_bstr_t( gen_script_name ) );

}

catch (_com_error& er)

{

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(),  _T("USBAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("USBAnalyzer client"), MB_OK );

return 1;

}

IUsbAnalyzer11::StopPDGeneration

C++

HRESULT StopPDGeneration();

Stops Power Delivery generation started by the StartPDGeneration method.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

Stops generation started by the StartPDGeneration method. Generation stops if the analyzer is either running or paused, and the analyzer then returns to the idle state.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the PD Exerciser to start generation.

Analyzer.StartPDGeneration "example.updg"

WScript.Sleep 3000

' Tell the analyzer to stop recording.

Analyzer.StopPDGeneration()

Example: VBScript

Visual Basic

<OBJECT

RUNAT=Server

ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292"

>

</OBJECT>

<SCRIPT LANGUAGE="VBScript">

<!--

Sub BtnStopUsb3Generation_OnClick

		On Error Resume Next

		Analyzer.StopPDGeneration

		If Err.Number <> 0 Then

			MsgBox Err.Number & ":" & Err.Description

		End If

End Sub

-->

</SCRIPT>

Example: C++

C++

IUsbAnalyzerPtr usb_analyzer;

. . . 

try

{

usb_analyzer ->StopPDGeneration();

}

catch (_com_error& er)

{

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(),  _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1;

}

UsbAnalyzer11::IsPDGenerationIdle

C++

HRESULT IsPDGenerationIdle ([out] VARIANT* gen_idle);

This method can be used to poll Power Delivery generation state after starting generation. The method returns status of generation process. User can use this method to poll the status of generation and go to the next step according to the polling result.

Parameters
gen_idle	Pointer to a Boolean variable indicating whether generation is done or not.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	not connected

Remarks

WaitForPDGenerationIdle can be used instead of this method. That method doesn’t block software normal operation and is the recommended method.

IUsbAnalyzer11::ResumePDGeneration

C++

HRESULT  ResumePDGeneration ();

Resumes the PD generation paused internally by generation script commands.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

The generation returns to the running state from the paused state after calling this method. Note that pausing Power Delivery generation is possible only by generation script. For more information, refer to the USB Power Delivery Exerciser Manual.

IUsbAnalyzer11::WaitForPDGenerationIdle

C++

HRESULT WaitForPDGenerationIdle (
[in] long wait_time_milisec,
[out] VARIANT* spent_time_milisec, 
[out] VARIANT* is_done);

The method polls internally for Power Delivery generation running and returns when generation finishes. Method will return if specified timeout is passed and generation is still running to prevent hangs/block conditions.

Parameters

wait_time_milisec

Specifies timeout for waiting before return in milliseconds

spent_time_milisec

Pointer to long value that returns spent time in this method

is_done

Pointer to long value indicating as follows:

0: Timeout happened.

Non-Zero: The passed argument to the PD_Stop( ret_val ) function in the PD-Exerciser script. A call to PD_Stop() without any arguments returns 256.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

IUsbAnalyzer12 interface

The IUsbAnalyzer12 interface is the 12th interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 475A317C-E69B-4CE1-8562-02F46F554BE3

IUsbAnalyzer12:: WaitForPDGenerationPause

C++

HRESULT WaitForPDGenerationPause (
[in] long wait_time_milisec,
[out] VARIANT* spent_time_milisec, 
[out] VARIANT* is_done);

The method polls internally for Power Delivery generation running and returns when generation is in Paused state. The method will return if specified timeout elapsed and generation is still paused to prevent hangs/block conditions.

Parameters
wait_time_milisec	Specifies timeout for waiting before return in milliseconds
spent_time_milisec	Pointer to long value that returns spent time in this method
is_done	Pointer to a Boolean value indicating generation is done or timeout happened.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

Use this method if you want client to have an opportunity to do some actions when generation is in paused state. You can use ResumePDGeneration to resume generation subsequently.

IUsbAnalyzer13 interface

The IUsbAnalyzer13 interface is the 13th interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 1EFE4CB0-F231-4994-A61B-6E89BB8F39CD

IUsbAnalyzer13::WaitForPDGenerationPauseTag

C++

HRESULT WaitForPDGenerationPauseTag (
[in] long wait_time_milisec,
[out] VARIANT* spent_time_milisec, 
[in] VARIANT* tag,
[out] VARIANT* is_done);

The method polls internally for Power Delivery generation running and returns when generation is in paused state. Returned tag is the assigned number to the current paused state. The method will return if the specified timeout elapsed and generation is still paused to prevent hangs/block conditions.

Parameters
wait_time_milisec	Specifies timeout for waiting before return in milliseconds
spent_time_milisec	Pointer to long value that returns spent time in this method
tag	Pointer to long value that returns corresponding tag of the current pause state.
is_done	Pointer to Boolean value indicating whether generation paused or timeout happened.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

Use this method if you want the client to have an opportunity to do some actions when generation is in paused state. To use this method, the generation script should assign different tags to each pause state so that client can differentiate between paused states. You can use ResumePDGeneration to resume generation subsequently.

IUsbAnalyzer16 interface

The IUsbAnalyzer16 interface is the 16th interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 6DA5368A-AC86-44BE-810A-914829BA3B5C

IUsbAnalyzer16::StartUSB4Generation

C++

HRESULT StartUSB4Generation ([in, defaultvalue("")] BSTR gen_file_name);

Starts generating USB4 traffic.

Parameters

gen_file_name

The name of the USB4 generation script file to execute.

If this parameter is an empty string, the last executed script is repeated.

Return values

ANALYZERCOMERROR_ANALYZERNOTCONNECTED

The Analyzer is not connected.

ANALYZERCOMERROR_UNABLESTARTGENERATION

The Analyzer cannot start for one of the following reasons:

Script has compiling error.

Analyzer is currently running or paused.

Analyzer is currently used by another client.

License for trainer device was not purchased.

Remarks

This function returns after USB4 generation starts. Analyzer continues generating until it finishes or until the StopUSB4Generation method is called.

The script file should have the file extension “.usb4g”. Either the USB Protocol Suite text editor or any plain-text editor can create it.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the USB4 Exerciser to start generation.

Analyzer.StartUSB4Generation "C:\\USB4ScriptExample.usb4g"

Dim doneGeneration

doneGeneration = 0

' Repeat Generation 49 more times.

For RepeatCount = 1 To 49

Do While doneGeneration = 0

		WScript.Sleep 100

Loop

Analyzer.StartUSB4Generation

DoneGeneration = 0

Next

' Release the analyzer.

WScript.DisconnectObject Analyzer

' WScript.Echo "USBAnalyzer object has been disconnected."

Set Analyzer = Nothing

' WScript.Echo "Quitting WScript..."

WScript.Quit

' Handler of the event fired when recorded trace is created 

' (after recording and uploading).

'

Sub Analyzer_OnStatusReport(ByVal subsystem, ByVal state, ByVal percent_done )

On Error Resume Next

  if state = 400 Then

    doneGeneration = 1

    WScript.Echo "Generation finished"

  End If

End Sub

Example: VBScript

Visual Basic

<OBJECT

RUNAT=Server

ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292"

>

</OBJECT>

...<INPUT TYPE=TEXT   VALUE="" NAME="PathToScript"> ...

...<INPUT TYPE=BUTTON VALUE="" NAME="BtnStartUSB4Generaion"> ...

<SCRIPT LANGUAGE="VBScript">

<!--

Sub BtnStartUSB4Generaion_OnClick

		On Error Resume Next

		Analyzer.StartUSB4Generation PathToScript.value

		If Err.Number <> 0 Then

			MsgBox Err.Number & ":" & Err.Description

		End If

End Sub

-->

</SCRIPT>

Example: C++

C++

IUsbAnalyzerPtr usb_analyzer;

. . . 

try

{

	const char* gen_script_name = "C:\\USB4ScriptExample.usb4g";

Usb_analyzer->StartUSB4Generation(_bstr_t( gen_script_name ) );

}

catch (_com_error& er)

{

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(),  _T("USBAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("USBAnalyzer client"), MB_OK );

return 1;

}

IUsbAnalyzer16::StopUSB4Generation

C++

HRESULT StopUSB4Generation();

Stops USB4 generation started by the StartUSB4Generation method.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

Stops generation started by the StartUSB4Generation method. Generation stops if the analyzer is either running or paused, and the analyzer then returns to the idle state.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Tell the USB4 Exerciser to start generation.

Analyzer.StartUSB4Generation "example.usub4g"

WScript.Sleep 3000

' Tell the analyzer to stop recording.

Analyzer.StopUSB4Generation()

Example: VBScript

Visual Basic

<OBJECT

RUNAT=Server

ID = Analyzer

CLASSID = "clsid:136D64A4-3CD5-4b41-974A-C7039E3FC292"

>

</OBJECT>

<SCRIPT LANGUAGE="VBScript">

<!--

Sub BtnStopUsb4Generation_OnClick

		On Error Resume Next

		Analyzer.StopUSB4Generation

		If Err.Number <> 0 Then

			MsgBox Err.Number & ":" & Err.Description

		End If

End Sub

-->

</SCRIPT>

Example: C++

C++

IUsbAnalyzerPtr usb_analyzer;

. . . 

try

{

usb_analyzer ->StopUSB4Generation();

}

catch (_com_error& er)

{

if (er.Description().length() > 0)

::MessageBox( NULL, er.Description(),  _T("UsbAnalyzer client"), MB_OK );

else

::MessageBox( NULL, er.ErrorMessage(), _T("UsbAnalyzer client"), MB_OK );

return 1;

}

IUsbAnalyzer16::ResumeUSB4Generation

HRESULT  ResumeUSB4Generation ();

Resumes the USB4 generation paused internally by generation script commands.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

The generation returns to the running state from the paused state after calling this function. Note that pausing USB4 generation is possible only by generation script commands. For more information, refer to the USB4 Exerciser Manual.

IUsbAnalyzer16::WaitForUSB4GenerationIdle

C++

HRESULT WaitForUSB4GenerationIdle (
[in] long wait_time_milisec,
[out] VARIANT* spent_time_milisec, 
[out] VARIANT* is_done);

Polls internally for USB4 generation running and returns when generation finishes. Method will return if specified timeout is passed and generation is still running to prevent hangs/block conditions.

Parameters

wait_time_milisec

Specifies timeout for waiting before return in milliseconds

spent_time_milisec

Pointer to long value that returns spent time in this method

is_done

Pointer to a Boolean value indicating generation is done or timeout happened

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

IUsbAnalyzer16::WaitForUSB4GenerationPauseTag

C++

HRESULT WaitForUSB4GenerationPauseTag (
[in] long wait_time_milisec,
[out] VARIANT* spent_time_milisec, 
[in] VARIANT* tag,
[out] VARIANT* is_done);

Polls internally for USB4 generation running and returns when generation is in paused state. Returned tag is the assigned number to the current paused state. The function will return if the specified timeout elapsed and generation is still paused to prevent hangs/block conditions.

Parameters
wait_time_milisec	Specifies timeout for waiting before return in milliseconds.
spent_time_milisec	Pointer to long value that returns spent time in this method.
is_done	Pointer to a Boolean value indicating generation is done or timeout happened.
tag	Pointer to long value that returns corresponding tag of the current pause state.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.

Remarks

Use this method if you want a client to have an opportunity to do some actions when generation is in paused state. A generation script can assign different tag to each pause state so that the client can differentiate between paused states. Use ResumeUSB4Generation to resume generation.

UsbAnalyzer17 interface

The IUsbAnalyzer17 interface is the 17th interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: D6A8DC56-7503-11EC-90D6-0242AC120003

IUsbAnalyzer17::GetConnectedAnalyzersSN

C++

HRESULT GetConnectedAnalyzersSN (
[out, retval] SAFEARRAY(VARIANT)* serial_numbers);

Returns serial numbers of all connected devices.

Parameters
serial_numbers	Serial numbers array for all connected devices.

Remarks

You can use this method to check the availability of a desired Analyzer.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

' Get serial numbers of all connected devices and store them in an array

Dim array_sn

array_sn = Analyzer.GetConnectedAnalyzersSN

' If no Analyzer is connected, check for any connected device every 1 sec

While UBound(array_sn) < 0

    WScript.Sleep 1000

    array_sn = Analyzer.GetConnectedAnalyzersSN

Wend

' Display all serial numbers in the array

For i = 0 To UBound(array_sn)

    MsgBox array_sn(i)

Next

WScript.DisconnectObject Analyzer

Set Analyzer = Nothing

WScript.Quit

UsbAnalyzer18 interface

The IUsbAnalyzer18 interface is the 18th interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: D037764C-93E5-435D-A06E-208C8B8337D9

IUsbAnalyzer18::IsRestartRequired

C++

HRESULT IsRestartRequired (
[in] int functionality, [out] VARIANT* restart);

Checks whether the analyzer must be restarted in order to use a specified functionality.

Parameters

functionality

Analyzer functionality to be queried:

2 – USB4/TBT3 recording

4 – USB3 recording

restart

Pointer to a Boolean value indicating whether analyzer restart is required.

Remarks

This method is usually used in conjunction with RestartAnalyzer. On a Voyager M4x, the restart flag shall return True when the indicated functionality differs from what was previously selected in the Recording Options.

Example

See RestartAnalyzer.

IUsbAnalyzer18::RestartAnalyzer

C++

HRESULT RestartAnalyzer (
[in, defaultvalue(-1)] int functionality);

Initiates an analyzer restart sequence to enable a specified functionality.

Parameters

functionality

Specifies desired analyzer functionality:

1 – Force analyzer restart

2 – Restart analyzer and enable USB4/TBT3 recording

4 – Restart analyzer and enable USB3 recording

Remarks

You can use this method to automatically restart the analyzer. On a Voyager M4x, M480x, or M4120, the unit will boot up with the specified BE loaded and ready to capture.

Example: WSH

C++

' Analyzer Device Functionalities

Const DF_USB4_ANALYZER = 2

Const DF_USB3_ANALYZER = 4

Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

'

' Ensure USB4 BusEngine is loaded and initialized

'

' Restart flag will be set to True if the current BE is USB3

Dim Restart

Analyzer.IsRestartRequired DF_USB4_ANALYZER, Restart

	

If Restart Then

    ' Restart analyzer with USB4 set as desire functionality

    Analyzer.RestartAnalyzer DF_USB4_ANALYZER

    

    ' We need to recreate the Analyzer object after the Restart

    WScript.DisconnectObject Analyzer

    Set Analyzer = WScript.CreateObject("CATC.UsbTracer", "Analyzer_")

End If

'

' Continue with USB4 Analyzer API call

' eg. Analyzer.StartUSB4Generation

. . . 

WScript.Quit

UsbAnalyzer20 interface

The IUsbAnalyzer20 interface is the 20th interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 2bc88cb6-61a4-11ee-8c99-0242ac120002

IUsbAnalyzer20::ImportSimPass

C++

HRESULT ImportSimPass(
[in, defaultvalue("")] BSTR simpass_file_name)

Imports the SimPass file.

Parameters
simpass_file_name	Absolute address for the SimPass file.

Example: VBScript

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.USBTracer")

Analyzer.ImportSimPass ("C:\SimPass\test.simpass")

WScript.DisconnectObject Analyzer

Set Analyzer = Nothing

WScript.Quit

UsbAnalyzer21 interface

The IUsbAnalyzer21 interface is the 21st interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: e40558b9-bddc-40cf-b755-2a6fe025b775

IUsbAnalyzer21::OpenUserFile

C++

HRESULT OpenUserFile(
[in] BSTR file_name, 
[in] UINT mode, 
[out, retval] LONGLONG* handle)

This function Opens a file with a specified name and mode. It returns a handle that can be used for subsequent file operations.

Note: The maximum number of files that can be open at the same time is 10.

Parameters

file_name

Specifies the name of the file to be opened. It can be:

A name without a path, in which case the file will be located in the application's current directory.
A relative path, relative to the application's data directory.
- An absolute path, specifying the exact location of the file.

mode

This parameter specifies the mode in which the file should be opened. The mode can be a combination of the following constants:

Constant	Value	Description
ReadOnly	0x0001	The file is open for reading.
WriteOnly	0x0002	The file is open for writing. The file is truncated unless combined with ReadOnly, Append, or NewOnly.
ReadWrite	0x0003	The file is open for both reading and writing. This combines ReadOnly (0x0001) and WriteOnly (0x0002).
Append	0x0004	The file is opened in append mode, so all data is written to the end of the file.
Truncate	0x0008	If possible, the file is truncated before it is opened. All earlier contents of the file are lost.
Text	0x0010	When reading, end-of-line terminators are translated to '\n'. When writing, end-of-line terminators are translated to the local encoding (e.g., '\r\n' for Win32).
Unbuffered	0x0020	Any buffer in the device is bypassed.
NewOnly	0x0040	The operation fails if the file already exists. The file is created and opened only if it does not exist. This mode implies WriteOnly but can be combined with ReadWrite.
ExistingOnly	0x0080	The operation fails if the file does not exist. This flag must be specified alongside ReadOnly, WriteOnly, or ReadWrite. Using this flag with ReadOnly alone is redundant, as ReadOnly already fails when the file does not exist.

handle

This is an output parameter that returns a handle to the opened file. The handle is a unique identifier that can be used in subsequent file operations.

Example: VBScript

Visual Basic

' Create an instance of the COM object

Dim Analyzer

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")

' Define the file path and mode

Dim filePath, fileMode, fileHandle, writeContent, filePos, readContent, readLen

filePath = "C:\Users\Public\Public Documents\sample_file.txt"

fileMode = &H10 Or &H03 ' text mode 0x10 | ReadWrite 0x03

' Open the file

fileHandle = Analyzer.OpenUserFile(filePath, fileMode)

' Write to the file 

writeContent = "This is a message from a COM client. Unusual chars @#$%^&*()!!~~"

Analyzer.WriteUserFile fileHandle, writeContent 

' Seek the file 

filePos = 0

Analyzer.SeekUserFile fileHandle, filePos

' Read from the file

readLen = 100 ' up to 100 chars

Analyzer.ReadUserFile fileHandle, readLen, readContent 

msgbox readContent

Analyzer.CloseUserFile(fileHandle)

Set Analyzer = Nothing

WScript.Quit

IUsbAnalyzer21::CloseUserFile

HRESULT CloseUserFile(
[in] LONGLONG handle)

This function closes a file previously opened by the OpenUserFile function.

Parameters
handle	The unique identifier assigned by the OpenUserFile API. It identifies the file to be closed.

Example: VBScript

Visual Basic

' Create an instance of the COM object

Dim Analyzer

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")

' Define the file path and mode

Dim filePath, fileMode, fileHandle, writeContent, filePos, readContent, readLen

filePath = "C:\Users\Public\Public Documents\sample_file.txt"

fileMode = &H10 Or &H03 ' text mode 0x10 | ReadWrite 0x03

' Open the file

fileHandle = Analyzer.OpenUserFile(filePath, fileMode)

' Write to the file 

writeContent = "This is a message from a COM client. Unusual chars @#$%^&*()!!~~"

Analyzer.WriteUserFile fileHandle, writeContent 

Analyzer.CloseUserFile(fileHandle)

Set Analyzer = Nothing

WScript.Quit

IUsbAnalyzer21::SeekUserFile

HRESULT SeekUserFile (
[in] LONGLONG handle, 
[in] LONGLONG pos)

This function sets the current file position.

Seeking beyond the end of the file: If the position is beyond the end of the file, then SeekUserFile will not immediately extend the file. If a write is performed at this position, then the file will be extended. The content of the file between the previous end of the file and the newly written data is UNDEFINED and varies between platforms and file systems.

Parameters

handle

The unique identifier assigned by the OpenUserFile API.

pos

Specifies the position in the file to be set as the current position.

If pos = -1, the pos will be set to the end of the file.
The initial position is 0 when the file is opened.

Example: VBScript

Visual Basic

' Create an instance of the COM object

Dim Analyzer

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")

' Define the file path and mode

Dim filePath, fileMode, fileHandle, writeContent, filePos, readContent, readLen

filePath = "C:\Users\Public\Public Documents\sample_file.txt"

fileMode = &H10 Or &H03 ' text mode 0x10 | ReadWrite 0x03

' Open the file

fileHandle = Analyzer.OpenUserFile(filePath, fileMode)

' Seek the file 

filePos = 0

Analyzer.SeekUserFile fileHandle, filePos

' Read from the file

readLen = 100 ' up to 100 chars

Analyzer.ReadUserFile fileHandle, readLen, readContent 

msgbox readContent

Analyzer.CloseUserFile(fileHandle)

Set Analyzer = Nothing

WScript.Quit

IUsbAnalyzer21::GetUserFileSize

C++

HRESULT GetUserFileSize(
[in] LONGLONG handle, 
[out, retval] LONGLONG* size)

This function retrieves the size of the file.

Parameters
handle	The unique identifier assigned by the OpenUserFile API.
size	An output parameter that returns the size of the file in bytes. If the file is closed, the size returned will not reflect the actual size of the device.

Example: VBScript

Visual Basic

' Create an instance of the COM object

Dim Analyzer

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")

' Define the file path and mode

Dim filePath, fileMode, fileHandle, fileSize

filePath = "C:\Users\Public\Public Documents\sample_file.txt"

fileMode = &H01 ' ReadOnly 0x01

' Open the file

fileHandle = Analyzer.OpenUserFile(filePath, fileMode)

' Read the file size

fileSize = Analyzer. GetUserFileSize(fileHandle) 

msgbox fileSize

Analyzer.CloseUserFile(fileHandle)

Set Analyzer = Nothing

WScript.Quit

IUsbAnalyzer21::WriteUserFile

C++

HRESULT WriteUserFile(
[in] LONGLONG handle, 
[in] VARIANT content)

This function writes data to the file at the current file position. The data is flushed to the file immediately after the call.

Parameters

handle

The unique identifier assigned by the OpenUserFile API. It identifies the file where the data will be written.

content

Specifies the content to be written to the file. The type of content depends on the mode in which the file was opened. If the file is opened in text mode, the content should be a BSTR. Otherwise, the content should be a SAFEARRAY.

The SAFEARRAY elements type should be VT_UI1.

Example: VBScript

Visual Basic

' Create an instance of the COM object

Dim Analyzer

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")

' Define the file path and mode

Dim filePath, fileMode, fileHandle, writeContent, filePos, readContent, readLen

filePath = "C:\Users\Public\Public Documents\sample_file.txt"

fileMode = &H10 Or &H03 ' text mode 0x10 | ReadWrite 0x03

' Open the file

fileHandle = Analyzer.OpenUserFile(filePath, fileMode)

' Write to the file 

writeContent = "This is a message from a COM client. Unusual chars @#$%^&*()!!~~"

Analyzer.WriteUserFile fileHandle, writeContent 

' Seek the file 

filePos = 0

Analyzer.SeekUserFile fileHandle, filePos

' Read from the file

readLen = 100 ' up to 100 chars

Analyzer.ReadUserFile fileHandle, readLen, readContent 

msgbox readContent

Analyzer.CloseUserFile(fileHandle)

Set Analyzer = Nothing

WScript.Quit

IUsbAnalyzer21::ReadUserFile

C++

HRESULT ReadUserFile(
[in] LONGLONG handle, 
[in] LONGLONG len, 
[out] VARIANT* content)

This function reads data from the current file position for a given length.

Parameters

handle

The unique identifier assigned by the OpenUserFile API. It identifies the file from which data will be read.

len

Specifies the number of bytes to read. Reads up to len bytes from the device and returns the read data.

content

an output parameter that points to a VARIANT where the read content will be stored. The type of content depends on the mode in which the file was opened:

If the file is opened in text mode, the content will be a BSTR.
Otherwise, the content will be a SAFEARRAY.

Example: VBScript

Visual Basic

' Create an instance of the COM object

Dim Analyzer

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")

' Define the file path and mode

Dim filePath, fileMode, fileHandle, writeContent, filePos, readContent, readLen

filePath = "C:\Users\Public\Public Documents\sample_file.txt"

fileMode = &H10 Or &H03 ' text mode 0x10 | ReadWrite 0x03

' Open the file

fileHandle = Analyzer.OpenUserFile(filePath, fileMode)

' Write to the file 

writeContent = "This is a message from a COM client. Unusual chars @#$%^&*()!!~~"

Analyzer.WriteUserFile fileHandle, writeContent 

' Seek the file 

filePos = 0

Analyzer.SeekUserFile fileHandle, filePos

' Read from the file

readLen = 100 ' up to 100 chars

Analyzer.ReadUserFile fileHandle, readLen, readContent 

msgbox readContent

Analyzer.CloseUserFile(fileHandle)

Set Analyzer = Nothing

WScript.Quit

UsbAnalyzer22 interface

The IUsbAnalyzer22 interface is the 22nd interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: 32077e1a-1b90-4dc8-9eda-7fcf258d99f8

IUsbAnalyzer22::CreateUserFolder

C++

HRESULT CreateUserFolder(
[in] BSTR full_path,
[out, retval] BOOL* success)

This function creates a directory and all its parents if needed.

Parameters
full_path	The full valid path to the directory that will be created. Make sure that you have the right permissions for creating the directory.
success	Returns true on success and false otherwise.

Example: Python

Python

import os

import datetime

import win32com.client

com  = win32com.client.Dispatch("CATC.UsbTracer")

try:

    full_path = r"C:\0Test\1Test"

    

    print(f"Creating: {full_path}")

    success = com.CreateUserFolder(full_path)

    print(f"success: {success}")

except Exception as error:

    print(error)

IUsbAnalyzer23 interface

The IUsbAnalyzer23 interface is the 23rd interface for the UsbAnalyzer object. It inherits and extends some analyzer-related functionality exposed via the IUsbAnalyzer interface.

IID: D9A228D9-B063-45CA-8F11-AB17815714C8

IUsbAnalyzer23::BindUnitEx (Restricted and Unsupported: Not for Customer Use.)

C++

HRESULT BindUnitEx ([in] VARIANT* box_sn);

Note: This method is used by Teledyne LeCroy to enable the USB 3.1 Hub Compliance licensed feature on Voyager units. It is only enabled when that license key is purchased. The use of this method by end customers outside of Hub Compliance is not supported by Teledyne LeCroy.

Parameters
box_sn	Specifies target UNIT serial number.

Return values
ANALYZERCOMERROR_ANALYZERNOTCONNECTED	The Analyzer is not connected.
ANALYZERCOMERROR_UNABLESTARTRECORDING	Multiple Unit Automation License is not available

Remarks

Method will fail if it is not licensed.

IUsbAnalyzer Dual Interface

IAnalyzer::GetVersion

Example: WSH

Example: C++

IAnalyzer::GetSerialNumber

Example: WSH

Example: C++

IAnalyzer::OpenFile

Remarks

Example: WSH

Example: C++

IAnalyzer::StartGeneration

Remarks

IAnalyzer::StopGeneration

Remarks

IAnalyzer::StartRecording

Remarks

Example: VBScript

Example: C++

IAnalyzer::StopRecording

Remarks

Example: VBScript

Example: C++

IAnalyzer::MakeRecording

Remarks

Example: WSH

Example: C++

IAnalyzer::LoadDisplayOptions

Remarks

Example

IAnalyzer::GetRecordingOptions

Remarks

Example: WSH

Example: C++

IUsbAnalyzer::StopRecordingAndWaitForTrace

Remarks

Example: WSH

Example: C++

IUsbAnalyzer::ApplicationFolder (property)

Remarks

Example: WSH

Example: C++

IUsbAnalyzer::ApplicationDataFolder (property)

Remarks

Example: WSH

Example: C++

IUsbAnalyzer::StartUsb3Generation

Remarks

Example: WSH (1)

Example: WSH(2)

Example: VBScript

Example: C++

IUsbAnalyzer::StopUsb3Generation

Remarks

Example: WSH

Example: VBScript

Example: C++

IUsbAnalyzer::PauseUsb3Generation

Remarks

Example: WSH

Example: VBScript

Example: C++

IUsbAnalyzer::ResumeUsb3Generation

Remarks

Example: WSH

Example: VBScript

Example: C++

IUsbAnalyzer::UsbUnplugPlug

IUsbAnalyzer3 interface

IUsbAnalyzer3:: IssueManualTrig

Remarks

IUsbAnalyzer4 interface

IUsbAnalyzer4::GetRecordingStatus

Remarks

IUsbAnalyzer4::ResetUsb3Trainer

IUsbAnalyzer4::IsUsb3GenerationIdle

Remarks

IUsbAnalyzer4::SwitchVBUS

IUsbAnalyzer5 interface

IUsbAnalyzer5::BindUnit (Restricted and Unsupported: Not for Customer Use.)

IUsbAnalyzer4::SwitchV_BUS