Primary Dual Interface for Trace | Protocol Solutions User Documentation

IUsbTrace Dual Interface

IUsbTrace interface is the primary interface for the UsbTrace object. It derives from the ITrace interface that implements the common functionality for all Teledyne LeCroy Analyzers.

ITrace::GetName

C++

HRESULT GetName ( 
[out, retval] BSTR* trace_name );

Retrieves the trace name.

Parameters
trace_name	Name of the trace.

Remarks

This name can be used for presentation purposes. Do not forget to free the string returned by this method call.

Example: WSH

Visual Basic

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

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

Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")

MsgBox "Trace name " & Trace.GetName

Example: C++

C++

IUsbTrace* usb_trace;
	. . . 
_bstr_t bstr_trace_name;
try
  {
    bstr_trace_name = usb_trace->GetName();	
  }

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 str_trace_name[256];
  _tcscpy( str_trace_name, (TCHAR*)( bstr_trace_name) );
  SysFreeString( bstr_trace_name );
::MessageBox( NULL, str_trace_name, _T("Trace name"), MB_OK );

ITrace::ApplyDisplayOptions

C++

HRESULT ApplyDisplayOptions ( 
[in] BSTR do_file_name );

Applies the specified display options to the trace.

Parameters
do_file_name	String providing the full pathname to the display options file.

Return values
ANALYZERCOMERROR_UNABLELOADDO	Unable to load the display options file.

Remarks

Use this method if you want to filter traffic of some type in the recorded or opened trace.

The 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 selecting the Save button.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.USBTracer")
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")
Trace.ApplyDisplayOptions    CurrentDir & "Input\test_do.opt"
Trace.Save                   CurrentDir & "Output\saved_file.usb"

Example: C++

C++

IUsbTrace* usb_trace;
TCHAR file_name[_MAX_PATH];
	. . . 
try
  {
    usb_trace->ApplyDisplayOptions( 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;
}

ITrace::Save

C++

HRESULT Save ( 
[in] BSTR file_name, 
[in, defaultvalue(-1)] long packet_from, 
[in, defaultvalue(-1)] long packet_to );

Saves the trace into a file and allows you to save a range of packets.

Parameters
file_name	String providing the full pathname to file where trace is saved
packet_from	Beginning packet number when you are saving a range of packets. Value –1 means that the first packet of the saved trace would be the first packet of this trace.
packet_to	Ending packet number when you are saving a range of packets. Value –1 means that the last packet of the saved trace would be the last packet of this trace.

Parameters

file_name

String providing the full pathname to file where trace is saved

packet_from

Beginning packet number when you are saving a range of packets.

Value –1 means that the first packet of the saved trace would be the first packet of this trace.

packet_to

Ending packet number when you are saving a range of packets.

Value –1 means that the last packet of the saved trace would be the last packet of this trace.

Return values
ANALYZERCOMERROR_UNABLESAVE	Unable to save trace file.

Remarks

Use this method if you want to save a recorded or opened trace into a file. If display options apply to this trace (see ITrace::ApplyDisplayOptions or IAnalyzer::LoadDisplayOptions), then hidden packets are not saved.

If packet range is specified and it is invalid (for example packet_to is more then last packet number in the trace, or packet_from is less than first packet number in the trace, or packet_from is more than packet_to), then packet range adjusts automatically.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.USBTracer")
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")
Trace.ApplyDisplayOptions    CurrentDir & "Input\test_do.opt"
Trace.Save                   CurrentDir & "Output\saved_file.usb"

Example: C++

C++

IUsbTrace* usb_trace;
TCHAR file_name[_MAX_PATH];
LONG packet_from;
LONG packet_to;
	. . . 
try
  {
    usb_trace->Save( file_name, packet_from, packet_to );
  }
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;
}

ITrace::ExportToText

C++

HRESULT ExportToText ( 
[in] BSTR file_name, 
[in, defaultvalue(-1)] long packet_from, 
[in, defaultvalue(-1)] long packet_to );

Exports the trace into a text file and allows you to export a range of packets.

Parameters
file_name	String providing the full pathname to the file where the trace is exported.
packet_from	Beginning packet number when you are exporting a range of packets. Value –1 means that the first packet of the exported trace would be the first packet of this trace.
packet_to	Ending packet number when you are exporting a range of packets. Value –1 means that the last packet of the exported trace would be the last packet of this trace.

Parameters

file_name

String providing the full pathname to the file where the trace is exported.

packet_from

Beginning packet number when you are exporting a range of packets.

Value –1 means that the first packet of the exported trace would be the first packet of this trace.

packet_to

Ending packet number when you are exporting a range of packets.

Value –1 means that the last packet of the exported trace would be the last packet of this trace.

Return valies
ANALYZERCOMERROR_UNABLESAVE	Unable to export trace file.

Remarks

Use this method if you want to export a recorded or opened trace into a text file. If display options apply to this trace (see ITrace::ApplyDisplayOptions or IAnalyzer::LoadDisplayOptions), then hidden packets are not exported.

If packet range is specified and it is invalid (for example, packet_to is more than last packet number in the trace, or packet_from is less than first packet number in the trace, or packet_from is more than packet_to), then packet range adjusts automatically.

Here is a snippet of an export file for a Bluetooth Trace. A USB Trace file would look similar:

File E:\AnalyzerSw\Chief20\OfficialUTGFiles\SRP.usb.

From Packet #13 to Packet #24.

Packet#

_______|_______________________________________________________________________

13_____| Dir(-->) Suspend( 37.000 ms) Time-stamp(00016.0097 3086) 

_______|_______________________________________________________________________

14_____| Dir(-->) Reset(  3.017 µs) Time-stamp(00016.0393 3090) 

_______|_______________________________________________________________________

15_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(6) CRC5(0x09) 

_______| EOP(266 ns) Time-stamp(00016.0393 3336) 

_______|_______________________________________________________________________

16_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(7) CRC5(0x16) 

_______| EOP(266 ns) Time-stamp(00016.0401 3336) 

_______|_______________________________________________________________________

17_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(8) CRC5(0x06) 

_______| EOP(266 ns) Time-stamp(00016.0409 3336) 

_______|_______________________________________________________________________

18_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(9) CRC5(0x19) 

_______| EOP(266 ns) Time-stamp(00016.0417 3336) 

_______|_______________________________________________________________________

19_____| Dir(-->) F(S) Sync(00000001) OUT(0x87) ADDR(2) ENDP(3) CRC5(0x0C) 

_______| EOP(266 ns) Time-stamp(00016.0417 3536) 

_______|_______________________________________________________________________

20_____| Dir(-->) F(S) Sync(00000001) DATA0(0xC3)-BAD Data(8 bytes) 

_______| CRC16(0xBB29) EOP(266 ns) Time-stamp(00016.0417 3726) 

_______|_______________________________________________________________________

21_____| Dir(<--) F(S) Sync(00000001) ACK(0x4B) EOP(266 ns) 

_______| Time-stamp(00016.0417 4256) 

_______|_______________________________________________________________________

22_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(10) CRC5(0x1B) 

_______| EOP(266 ns) Time-stamp(00016.0425 3336) 

_______|_______________________________________________________________________

23_____| Dir(-->) F(S) Sync(00000001) SOF(0xA5) Frame #(11) CRC5(0x04) 

_______| EOP(266 ns) Time-stamp(00016.0433 3336) 

_______|_______________________________________________________________________

24_____| Dir(-->) Suspend(0 ns) Time-stamp(00016.0457 3466) 

_______|_______________________________________________________________________

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.USBTracer")
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")
Trace.ApplyDisplayOptions    CurrentDir & "Input\test_do.opt"
Trace.ExportToText           CurrentDir & "Output\text_export.txt"

Example: C++

C++

IUsbTrace* usb_trace;
TCHAR file_name[_MAX_PATH];
LONG packet_from;
LONG packet_to;
	. . . 
try
  {
    usb_trace->ExportToText( file_name, packet_from, packet_to );
  }
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;
  }

ITrace::Close

HRESULT Close ( );

Closes the trace.

Remarks

Closes the current trace but does not release the interface pointer. Call the IUnknown::Release method right after this method call. No ITrace method call succeeds after calling the ITrace::Close method.

Currently there is no need to call ITrace::Close directly since IUnknown::Release closes the trace.

ITrace::ReportFileInfo

HRESULT ReportFileInfo ( 
[in] BSTR file_name );

Saves trace information into an HTML file.

Parameters
file_name	String with full pathname to the file where the trace information report will be created.

Return values
ANALYZERCOMERROR_UNABLESAVE	Unable to create trace information report.

Remarks

Stores trace information in specified file. If the file specified in the file_name parameter does not exist, one will be created.

Example: WSH

Visual Basic

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

Example: C++

C++

IUsbTrace* usb_trace;
TCHAR file_name[_MAX_PATH];
. . . 
try
  {
    usb_trace->ReportFileInfo( 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;
  }

ITrace::ReportErrorSummary

C++

HRESULT ReportErrorSummary ( 
[in] BSTR file_name );

Saves trace error summary information into the specified text file.

Parameters
file_name	String. The full pathname to the file where the error summary report is created.

Return values
ANALYZERCOMERROR_UNABLESAVE	Unable to create trace information report.

Remarks

Creates an error summary file if necessary. Stores error summary in specified file. Here is an example of data stored using this method call:

Error report for SRP.usb recording file.

_______|_______________________________________________________________________

Bad PID (0):

_______|_______________________________________________________________________

Bad CRC5 (0):

_______|_______________________________________________________________________

Bad CRC16 (0):

_______|_______________________________________________________________________

Bad Packet Length (0):

_______|_______________________________________________________________________

Bad Stuff Bits (0):

_______|_______________________________________________________________________

Bad EOP (0):

_______|_______________________________________________________________________

Babble Start (0):

_______|_______________________________________________________________________

Babble End (LOA) (0):

_______|_______________________________________________________________________

Bad Frame Length (0):

_______|_______________________________________________________________________

Bad Turnaround/Timeout (0):

_______|_______________________________________________________________________

Bad Data Toggle (1):

_______| 0.20;

_______|_______________________________________________________________________

Bad Frame/uFrame Number (0):

_______|_______________________________________________________________________

Analyzer Internal Error (0):

_______|_______________________________________________________________________

Last Byte Incomplete (0):

_______|_______________________________________________________________________

Example: WSH

Visual Basic

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

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

Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")

Trace.ReportErrorSummary     CurrentDir & "Output\error_summary.txt"

Example: C++

C++

IUsbTrace* usb_trace;
TCHAR file_name[_MAX_PATH];
. . . 
try
  {
    usb_trace->ReportErrorSummary( 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;
  }

ITrace::ReportTrafficSummary

C++

HRESULT ReportTrafficSummary( 
[in] BSTR file_name );

Saves trace traffic summary information into the specified text file.

Parameters
file_name	String. The full pathname to file where traffic summary report is created.

Return values
ANALYZERCOMERROR_UNABLESAVE	Unable to create or save traffic summary report.

Remarks

Creates traffic summary report file, if necessary. Stores traffic summary in the specified file. Here is an example of data stored using the following method call.

Example: WSH

Visual Basic

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

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

Set Trace = Analyzer.MakeRecording (CurrentDir & "Input\test_ro.rec")

Trace.ReportTrafficSummary     CurrentDir & "Output\traffic_summary.txt"

Example: C++

C++

IUsbTrace* usb_trace;
TCHAR file_name[_MAX_PATH];
. . . 
try
  {
    usb_trace->ReportTrafficSummary( 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;
  }

ITrace::GetPacket

HRESULT GetPacket ( 
[in] long packet_number, 
[in, out] VARIANT* packet, 
[out, retval] long* number_of_bits );

Retrieves the raw packet representation.

Parameters
packet_number	Number of the packet to retrieve
packet	Raw packet representation
number_of_bits	Number of bits in raw packet representation

Return values
ANALYZERCOMERROR_INVALIDPACKETNUMBER	Specified packet number is invalid.

Remarks

The packet parameter has VT_ARRAY | VT_VARIANT actual automation type. Each element of this array has VT_UI1 automation type. Since the last element of the array may contain extra data, you need to use the number_of_bits parameter to determine the actual packet data.

Example VBScript:

Visual Basic

<OBJECT ID = Analyzer CLASSID = "clsid:0B179BB3-DC61-11d4-9B71-000102566088">
</OBJECT>
<INPUT TYPE=TEXT NAME="TextPacketNumber">
<P ALIGN=LEFT ID=StatusText></P>
<SCRIPT LANGUAGE="VBScript">
<!--
Function DecToBin(Param, NeedLen)
While Param > 0
  Param = Param/2
If Param - Int(Param) > 0 
Then Res = CStr(1) + Res
Else
Res = CStr(0) + Res
End If
Param = Int(Param)
Wend
DecToBin = Replace( Space(NeedLen - Len(Res)), " ", "0") & Res
End Function
Sub BtnGetPacket_OnClick
On Error Resume Next
Dim Packet
NumberOfBits = (CLng(CurrentTrace.GetPacket (TextPacketNumber.value, Packet))
If Err.Number <> 0 Then
MsgBox "GetPacket:" & Err.Number & ":" & Err.Description
		Else
For Each PacketByte In Packet
PacketStr = PacketStr & DecToBin(PacketByte, 8) & " "
NBytes = NBytes + 1
Next
PacketStr = Left( PacketStr, NumberOfBits )
StatusText.innerText = "Packet ( " & NumberOfBits & " bits ): " & PacketStr
End If
End Sub
-->
</SCRIPT>

Example: C++

C++

IUsbTrace* usb_trace;
LONG packet_number;
. . .
VARIANT packet;
VariantInit( &packet );
long number_of_bits;
try
  {
    number_of_bits = usb_trace->GetPacket( packet_number, &packet );
  }
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;
  }
if ( packet.vt == ( VT_ARRAY | VT_VARIANT) )
  {
    SAFEARRAY* packet_safearray = packet.parray;
    TCHAR packet_message[256];
    TCHAR elem[64];
     _stprintf( packet_message, _T("packet #%ld: "), packet_number );
    for ( long i=0; i<(long)packet_safearray->rgsabound[0].cElements; i++)
      {
        VARIANT var;
        HRESULT hr = SafeArrayGetElement(packet_safearray, &i, &var);
        if (FAILED(hr))
          {
            ::MessageBox( NULL, _T("Error accessing array"), _T("UsbAnalyzer client"), MB_OK );
            return 1;
          }
        if ( var.vt != ( VT_UI1) )
          {
            ::MessageBox( NULL, _T("Array of bytes expected"), _T("UsbAnalyzer client"), MB_OK );
            return 1;
          }
          _stprintf( elem, _T("%02X "), V_UI1(&var) );
            _tcscat( packet_message, elem );
        }
      _stprintf( elem, _T("%d bits"), number_of_bits );
      _tcscat( packet_message, elem );
      ::MessageBox( NULL, packet_message, _T("Raw packet bits"), MB_OK );
  }
    else
      {
         ::MessageBox( NULL, _T("Invalid argument"), _T("UsbAnalyzer client"), MB_OK );
      }

ITrace::GetPacketsCount

C++

HRESULT GetPacketsCount ( 
[out, retval] long* number_of_packets );

Retrieves the total number of packets in the trace.

Parameters
number_of_packets	Points to a long value where the number of packets in the trace is retrieved.

Example: WSH

Visual Basic

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

Example: C++

C++

IUsbTrace* usb_trace;
	. . . 
long number_of_packets;
long trigg_packet_num;
try
  {
    bstr_trace_name = usb_trace->GetName();
    number_of_packets = usb_trace->GetPacketsCount();
    trigg_packet_num = usb_trace->GetTriggerPacketNum();
  }
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 str_trace_name[256];
_tcscpy( str_trace_name, (TCHAR*)( bstr_trace_name) );
SysFreeString( bstr_trace_name );
TCHAR trace_info[256];
_stprintf( trace_info, _T("Trace:'%s', total packets:%ld, trigger packet:%ld"), 
str_trace_name, number_of_packets, trigg_packet_num );
::SetWindowText( m_hwndStatus, trace_info );

ITrace::GetTriggerPacketNum

C++

HRESULT GetTriggerPacketNum ( 
[out, retval] long* packet_number );

Retrieves the number of the trigger packet.

Parameters
packet_number	Points to a long value where the trigger packet number is retrieved.

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")
TriggerPacket = CLng(Trace.GetTriggerPacketNum)
Trace.Save CurrentDir & "Output\trigger_portion.usb", CInt(ErrorPacket)-5, 
CInt(ErrorPacket)+5
Trace.ExportToText CurrentDir & "Output\trigger_portion.txt", CInt(ErrorPacket)-5, 
CInt(ErrorPacket)+5

Example: C++

See example for ITrace::GetPacketsCount.

ITrace::AnalyzerErrors

C++

HRESULT AnalyzerErrors ( 
[in] long error_type, 
[out, retval] IAnalyzerErrors** analyzer_errors );

Retrieves trace file errors.

Parameters
long error_type	Type of the error you want to retrieve. The following values are valid: 0x00000001 - Pid Error 0x00000002 - CRC5 Error 0x00000004 - CRC16 Error 0x00000008 - Packet Length Error 0x00000010 - Stuff Bit Error 0x00000020 – EOP Error 0x00000040 – Babble Start Error 0x00000080 – Babble End Error (LOA) 0x00000100 – Frame Length Error 0x00000200 – Handshake Timeout Error 0x00000400 – Analyzer Internal Error 0x00000800 – Data Toggle Error 0x00001000 – Microframe Error 0x00002000 – Short Byte Error (bits missing)
analyzer_errors	Address of a pointer to the AnalyzerErrors object primary interface.

Parameters

long error_type

Type of the error you want to retrieve. The following values are valid:

0x00000001 - Pid Error
0x00000002 - CRC5 Error
0x00000004 - CRC16 Error
0x00000008 - Packet Length Error
0x00000010 - Stuff Bit Error
0x00000020 – EOP Error
0x00000040 – Babble Start Error
0x00000080 – Babble End Error (LOA)
0x00000100 – Frame Length Error
0x00000200 – Handshake Timeout Error
0x00000400 – Analyzer Internal Error
0x00000800 – Data Toggle Error
0x00001000 – Microframe Error
0x00002000 – Short Byte Error (bits missing)

analyzer_errors

Address of a pointer to the AnalyzerErrors object primary interface.

Return values
ANALYZERCOMERROR_INVALIDERROR	Invalid error type specified

Remarks

The AnalyzerErrors object is created via this method call, if the call is successful.

IUsbTrace2 interface

The IUsbTrace2 interface is the second interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace interface.

IID: 149B95E9-C17D-43b3-AC0D-30419A485058

IUsbTrace2::GotoTime

C++

HRESULT GotoTime ( [in] double time );

Instructs the trace view to jump to the specified timestamp.

Parameters
time	Time (in nanoseconds) to jump.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Analyzer.StartRecording (CurrentDir & "test_ro.rec")
'... Do something.
Set Trace = Analyzer.StopRecordingAndWaitForTrace
Trace.GotoTime( 1000000 ) ' Go to 1 millisecond timestamp.

Example: C++

C++

IUsbTrace2* Usb_trace;
	. . . 
try
  {
    double t = 1000000.0;
    Usb_trace ->GotoTime( t );
  }
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;
  }

IUsbTrace2::GotoUnit

C++

HRESULT GotoUnit ([in] long level, [in] long index );

Instructs the trace view to jump to the specified transaction unit.

Parameters
level	Transaction level. Possible values are: 0 = USB Packets 1 = USB Transactions 2 = USB Split Transactions 3 = USB Transfers 4 = Host WireAdapter Segments 5 = Host WireAdapter Transfers 6 = Device WireAdapter Segments 7 = Device WireAdapter Transfers 8 = PTP Transactions 9 = PTP Objects 10 = PTP Sessions
index	Index of the unit inside the transaction level.

Parameters

level

Transaction level. Possible values are:

0 = USB Packets
1 = USB Transactions
2 = USB Split Transactions
3 = USB Transfers
4 = Host WireAdapter Segments
5 = Host WireAdapter Transfers
6 = Device WireAdapter Segments
7 = Device WireAdapter Transfers
8 = PTP Transactions
9 = PTP Objects
10 = PTP Sessions

index

Index of the unit inside the transaction level.

Return values
ANALYZERCOMERROR_INVALIDPACKETNUMBER	Unable to jump to specified transaction unit. Either the transaction level or transaction index is invalid.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Analyzer.StartRecording (CurrentDir & "test_ro.rec")
'... do something.
Set Trace = Analyzer.StopRecordingAndWaitForTrace
Trace.GotoUnit( 3, 2 ) ' jumps to USB transfer #2

Example: C++

C++

IUsbTrace3* Usb_trace;
	. . . 
try
  {
    int level = 3; // USB Transfers
    int index = 2; 
    Usb_trace ->GotoUnit( 3, 2 );
  }
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;
  }

IUsbTrace2::ExportToCsv

C++

HRESULT ExportToCsv( 
[in] BSTR file_name,
[in] long level, 
[in, defaultvalue(-1)] long unit_from, 
[in, defaultvalue(-1)] long unit_to );

Exports a trace into a text file in CSV format and allows exporting a range of packets.

Parameters
file_name	String providing the full pathname of the trace export file
level	Transaction level. Currently, only the following levels are supported: 0 – Packets 1 – USB Transactions 2 – USB Split Level 3 – USB Transfers 8 – PTP Transactions 9 – PTP Object 10 – PTP Session 11 – SCSI Operation 13 – PTP Group 14 - OBEX
unit_from	Beginning packet number when you are exporting a range of packets. Value –1 makes the first packet of the exported trace be the first packet of the trace.
unit_to	Ending packet number when you are exporting a range of packets. Value –1 makes the last packet of the exported trace be the last packet of the trace.

Return values
ANALYZERCOMERROR_UNABLESAVE	Unable to export trace file.

Remarks

Use this method if you want to export a recorded or opened trace into a text file in CSV format. If display options apply to this trace (see ITrace::ApplyDisplayOptions or IAnalyzer::LoadDisplayOptions), then hidden units would not be exported.

If a unit range is specified and it is invalid (for example, unit_to is more than the last unit number in the trace, or unit_from is less than first unit number in the trace, or unit_from is more then unit_to) then unit range adjusts automatically.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
  ' Specify the real path to the trace file instead of 'C:\test.usb'.
Set Trace = Analyzer.OpenFile ( "C:\test.usb" )
  ' Instructs the USB Protocol Suite application to locate packet # 15
  ' (transaction level 0) in the trace viewer.
Trace.GotoUnit 0, 15
  ' Instructs the USB Protocol Suite trace viewer to jump to the trace unit
  ' with the timestamp close to 6000 ns (6 microsecond).
Trace.GotoTime 6000
  ' Exports USB transactions (from #0 to #10 ) into CSV format.
  ' 1st parameter - file name of the export file
  ' 2nd parameter - transaction level ( 0 - packets, 1 - transactions )
  ' 3rd parameter - unit number to start with
  ' 4th parameter - unit number to end by
Trace.ExportToCsv CurrentDir & "Output\text_csv_export.csv", 1, 0, 10
MsgBox "Done"

Example: C++

C++

IUsbTrace2* usb_trace;
	. . . 
IAnalyzerErrors* analyser_errors;
try
  {
    analyser_errors = usb_trace-> ExportToCsv (_bstr_t( “c:\\test.csv” ), 1, 0 , 10 ) ;
  }
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;
  }
. . . 
analyser_errors->Release();

IUsbTrace2::SaveAs

C++

HRESULT SaveAs ( [in] BSTR file_name );

Saves the trace into a file and makes the current IUsbTrace2 pointer refer to this file.

Parameters
file_name	A string providing the full pathname to the file in which the trace is saved.

Return values
ANALYZERCOMERROR_UNABLESAVE	Unable to save trace file.

Remarks

Use this method if you want to move a recorded or opened trace into a file.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Analyzer.StartRecording (CurrentDir & "Input\test_ro.rec")
  '... Do something.
Set Trace = Analyzer.StopRecordingAndWaitForTrace
Trace.SaveAs CurrentDir & "Output\saved_file.usb"

Example: C++

C++

IUsbTrace2* USB_trace;
TCHAR file_name[_MAX_PATH];
LONG packet_from;
LONG packet_to;
	... 
try
  {
    USB_trace->SaveAs( 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;
  }

IUsbTrace3 interface

The IUsbTrace3 interface is the third interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace2 interface.

IID: 4DA2A987-47B3-4384-BFA8-2052326FBE0E

IUsbTrace3:: GetPowerInfoByTime

C++

HRESULT GetPowerInfoByTime ( 
           [in] double time, 
           [out] VARIANT* voltage, 
           [out] VARIANT* current, 
           [out] VARIANT* power, 
           [out,retval] BOOL* power_info_is_valid );

Returns voltage, current, and power values based on a time in nanoseconds.

Parameters
time	timestamp in nanoseconds
voltage	voltage in microvolts
current	current in microamps
power	power in microwatts

Return values
BOOL	TRUE if power values were recorded at the time.

IUsbTrace3:: GetPowerInfoByPacket

C++

HRESULT GetPowerInfoByPacket ( 
   [in] long packet_number, 
   [out] VARIANT* voltage, 
   [out] VARIANT* current,  
   [out] VARIANT* power, 
   [out,retval] BOOL* power_info_is_valid );

Returns voltage, current, and power values based on a packet number.

Parameters
packet_number	Packet number in the trace file
voltage	voltage in microvolts
current	current in microamps
power	power in microwatts

Return values
BOOL	TRUE if power values were recorded at that packet_number.

IUsbTrace4 interface

The IUsbTrace4 interface is the fourth interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace3 interface.

IID : C7D741F6-D425-417f-B7FC-4DB0FB01804B

IUsbTrace4:: GetFullName

C++

HRESULT GetFullName( [out, retval] BSTR* trace_name )

Returns name of trace file. This means Filename.extension, as in MyTrace.usb. It does NOT include the path.

Parameters
trace_name	Pointer to a string to retrieve the full trace file filename.

IUsbTrace5 interface

The IUsbTrace5 interface is the fifth interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace4 interface.

IID: CAC0F43F-322E-4165-9BB6-E0DBDD95B682

IUsbTrace5::GetUsbPacket

C++

HRESULT GetUsbPacket( 
  [in] long packet_number, 
  [out, retval] IDispatch** usb_packet )

Retrieves a pointer to the specified packet.

Parameters
Packet_number	Number of the packet to retrieve.
Usb_packet	Address of a pointer to the UsbPacket object primary interface.

IusbTrace6 interface

The IUsbTrace6 interface is the sixth interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace5 interface.

IID: A1F83FCC-265A-44E3-837F-42A8C27074C1

IUsbTrace6::IsLevelDecodeFinished

C++

HRESULT IsLevelDecodeFinished( 
   [in] long level_id, 
   [out,retval] BOOL* decode_is_finished )

Retrieves progress status of decoding levels process. If level decoding is finished, returns true.

Parameters
level_id	Desired level to retrieve decoding status like Transaction/Transfer. A value of -1 refers to all levels, in which case the status would be true if all level decodings are finished.
decode_is_finished	Pointer to a Boolean value that specifies the decoding status.

Remarks

After opening traces, decoding process of upper levels starts in background processes or through a function call for higher levels. This decoding is time consuming process, however any other process on desired level like transactions need to check of decoding finish before starting process.

The level ID parameter canbe one of these values:

DECODE_LEVEL_PACKET = 0, // USB_TRA_LEVEL_PACKETS

DECODE_LEVEL_TRANSACTION = 1, // USB_TRA_LEVEL_TRANSACTIONS

DECODE_LEVEL_SPLIT = 2, // USB_TRA_LEVEL_SPLITS

DECODE_LEVEL_TRANSFER = 3, // USB_TRA_LEVEL_TRANSFERS

DECODE_LEVEL_PTP_TRANSACTION = 8, // USB_TRA_LEVEL_PTP_TRANSACTION

DECODE_LEVEL_PTP_OBJECT = 9, // USB_TRA_LEVEL_PTP_OBJECT

DECODE_LEVEL__PTP_SESSION = 10, // USB_TRA_LEVEL_PTP_SESSION

DECODE_LEVEL_SCSI = 11, // USB_TRA_LEVEL_SCSI_OPERATION

DECODE_LEVEL_PTP_GRP = 13, // USB_TRA_LEVEL_PTP_GROUP

IusbTrace6::SetTag

C++

HRESULT SetTag( [in] int tag)

Specify an optional unique id for the trace. This id could be used as identifier of trace in trace related events when user works with multiple traces at same time. See the _ITraceEvents interface for further detail.

Parameters
tag	An optional unique identifier of a trace.

IusbTrace6::GetTag

C++

HRESULT GetTag( [out, retval] int* tag)

Retrieves the unique identifier of a trace that was previously specified by the SetTag method.

Parameters
tag	An optional unique identifier of a trace.

IUsbTrace7 Interface

The IUsbTrace7 interface is an additional interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace6 interface.

IID: F3260A83-8F86-4356-81DC-D9B880E1293E

IUsbTrace7::GetPacketEx

C++

HRESULT GetPacketEx ( [in] hyper packet_number, [in, out] VARIANT* packet, [out, retval] long* number_of_bits )

Retrieves a raw packet in the PACKETFORMAT_BYTES format. It accepts a 64-bit packet number. It is an extension of the ITrace::GetPacket method.

Parameters
packet_number	Zero-based number of a packet to retrieve. It is a 64-bit integer.
packet	Raw packet representation.
number_of_bits	Number of bits in the raw packet representation.

Return values
ANALYZERCOMERROR_INVALIDPACKETNUMBER	Specified packet number is invalid

Remarks

Packet parameter has VT_ARRAY | VT_VARIANT actual automation type. Each elements of this array has the VT_UI1 automation type.

IUsbTrace7:: GetPacketsCountEx

C++

HRESULT GetPacketsCountEx ( [out, retval] hyper* number_of_packets )

Retrieves the total number of packets in the trace. The number of packets can be a 64-bit integer. It is an extension of the ITrace::GetPacketsCount method.

Parameters
number_of_packets	Total number of packets in the trace

IUsbTrace7:: GetTriggerPacketNumEx

C++

HRESULT GetTriggerPacketNumEx ( [out, retval] hyper* packet_number )

Retrieves the trigger packet number. The trigger packet number can be a 64-bit integer. It is an extension of the ITrace::GetTriggerPacketNum method.

Parameters
packet_number	Zero-based number of the packet where the trigger occurred.

IUsbTrace7:: GetUsbPacketEx

C++

HRESULT GetUsbPacketEx ( [in] hyper packet_number, [out, retval] IDispatch** packet )

Retrieves the interface for packet within a trace. It accepts a 64-bit packet number. It is an extension of the IUsbTrace5::GetUsbPacket method.

Parameters
packet_number	Zero-based number of the packet to retrieve. It is a 64-bit integer.
packet	Address of a pointer to the UsbPacket object interface.

IUsbTrace8 Interface

The IUsbTrace8 interface is an additional interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace6 interface.

IID: 5B40CDDA-6FEE-4B81-9307-3D1512D70947

IUsbTrace8::GetFullPathAndName

C++

HRESULT GetFullPathAndName( [out, retval] BSTR* trace_name )

Returns name of trace path and filename with extension. Example: C:\Stuff\MyTrace.usb

If you only want the filename, use IUsbTrace4::GetFullName.

Parameters
trace_name	A pointer to a string to retrieve the full trace file path and filename.

IUsbTrace10 interface

The IUsbTrace10 interface is an additional interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace9 interface.

IID : AC4DC05E-3B20-4233-BDE6-F92B3A185B28

IUsbTrace10::ExportTransactionsWithPacketsToCsv

C++

HRESULT ExportTransactionsWithPacketsToCsv ( 
  [in] BSTR file_name,
  [in, defaultvalue(-1)] long, 
  [in, defaultvalue(-1)] long unit_to );

Exports the USB Transactions and packets level of the trace into a text file in CSV format and allows exporting a range of packets.

Parameters
file_name	A string providing the full pathname of the trace export file.
unit_from	The starting packet number when you are exporting a range of packets. Value –1 makes the first packet of the exported trace be the first packet of the trace.
unit_to	The ending packet number when you are exporting a range of packets. Value –1 makes the last packet of the exported trace be the last packet of the trace.

Return values
ANALYZERCOMERROR_UNABLESAVE	Unable to export trace file.

Remarks

If a unit range is specified and it is invalid (for example, unit_to is more than the last unit number in the trace, or unit_from is less than first unit number in the trace, or unit_from is more than unit_to) then unit range adjusts automatically.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
  ' Specify the real path to the trace file instead of 'C:\test.usb'.
Set Trace = Analyzer.OpenFile ( "C:\test.usb" )
  ' Instructs the USB Protocol Suite application to locate packet # 15
  ' (transaction level 0) in the trace viewer.
Trace.GotoUnit 0, 15
  ' Instructs the USB Protocol Suite trace viewer to jump to the trace unit
  ' with the timestamp close to 6000 ns (6 microsecond).
Trace.GotoTime 6000
  ' Exports USB transactions with packets (from #0 to #10 ) into CSV format.
  ' 1st parameter - file name of the export file
  ' 2rd parameter - unit number to start with
  ' 3th parameter - unit number to end by
Trace.ExportTransactionsWithPacketsToCsv CurrentDir &"Output\text_csv_export.csv", 0, 10
MsgBox "Done"

Example: C++

C++

IUsbTrace2* usb_trace;
	. . . 
IAnalyzerErrors* analyser_errors;
try
  {
    analyser_errors = usb_trace-> ExportTransactionsWithPacketsToCsv (_bstr_t( “c:\\test.csv” ), 0 , 10 );
  }
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;
  }
. . . 
analyser_errors->Release();

IUsbTrace11 interface

The IUsbTrace11 interface is an additional interface for the UsbTrace object. It inherits and extends some trace-related functionality exposed via the IUsbTrace10 interface.

IID: F1ED8DB5-2EC6-4fa0-8F8B-D645A1FA4A85

IusbTrace11::SaveTraceAs

C++

HRESULT SaveTraceAs ([ in ] BSTR file_name, [ in, defaultvalue( -1 ) ] long packet_from, [ in, defaultvalue( -1 ) ] long packet_to, [in, defaultvalue( 0 )] BOOL exclude_hidden_packets );

Saves the specified range of packets into a new Trace file.

Parameters
file_name	String providing the full path name to the file in which the trace is saved.
packet_from	The index of the first packet as a starting point for save as.
packet_to	The index of the last packet as an end point for save as.
exclude_hidden_packets	A Boolean to include or exclude hidden packets during save as.

Return values
ANALYZERCOMERROR_UNABLESAVE	Unable to save trace file

Remarks

Provide to save specific range of packets in a new trace file.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.UsbTracer")
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Analyzer.StartRecording (CurrentDir & "Input\test_ro.rec")
  '... Do something.
Set Trace = Analyzer.StopRecordingAndWaitForTrace
Trace.SaveTraceAs CurrentDir & "Output\saved_file.usb", 0, 100, 1

Example: C++

C++

IUsbTrace11* USB_trace;
TCHAR file_name[_MAX_PATH];
LONG packet_from = 0;
LONG packet_to = 100;
BOOL exclude_hidden_packets = 1; 
	... 
try
  {
    USB_trace->SaveTraceAs(file_name, packet_from, packet_to, exclude_hidden_packets);
  }
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;
  }

IusbTrace11::ExportUSBTransferData

C++

HRESULT ExportUSBTransferData( [in] long addr, [in] long endp, [in] long direction, [in] long level_from, [in] long unit_from, [in] long level_to, [in] long unit_to, [in] BSTR file_name, [in] BOOL file_type_binary, [in] long size_kb );

Exports USB Transfers data into a text or binary file.

Parameters
addr	Specifies Device Address
endp	Specifies Endpoint Number
direction	The direction of endpoint (1= Either, 2 = Out, and 3 = IN)
level_from	levels (0 = Packet, 1 = Transaction, 3 = Transfer)
unit_from	The index of the first packet as a start point for export.
level_to	levels (0 = Packet, 1 = Transaction, 3 = Transfer)
unit_to	The index of the last packet as an end point for export.
filename	String providing the full path name of the output file.
file_type_binary	The output file format (0 = Text, 1 = Binary)
size_kb	Maximum file size if using binary as output format.

Return values
ANALYZERCOMERROR_UNABLESAVE	Unable to save trace file.
ANALYZERCOMERROR_INVALIDTRACEHANDLE	Returned value depends on the step of process

Example: WSH

Visual Basic

Const DATDIR_NONE   = 0
Const DATDIR_EITHER = 1
Const DATDIR_OUT    = 2
Const DATDIR_IN     = 3
Const USB_TRA_LEVEL_PACKETS      = 0
Const USB_TRA_LEVEL_TRANSACTIONS = 1
Const USB_TRA_LEVEL_TRANSFERS    = 3
Dim address          : address           = 2
Dim endpoint         : endpoint          = 1
Dim direction        : direction         = DATDIR_OUT
Dim packet_level_from: packet_level_from = USB_TRA_LEVEL_TRANSFERS
Dim from_packet      : from_packet       = 0
Dim packet_level_to  : packet_level_to   = USB_TRA_LEVEL_TRANSFERS
Dim to_packet        : to_packet         = 200
Dim file_path        : file_path         = D:\data.txt"
Dim file_type        : file_type         = 0
Dim size_kb          : size_kb           = 0
Set Analyzer = WScript.CreateObject("CATC.UsbTracer")
CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\"))
Analyzer.StartRecording (CurrentDir & "Input\test_ro.rec")
  '... Do something.
Set Trace = Analyzer.StopRecordingAndWaitForTrace
Trace.ExportUSBTransferData ddress, endpoint, direction, packet_level_from,from_packet, packet_level_to, to_packet, file_path, file_type, size_kb

IUsbTrace12 interface

IUsbTrace12::ExportUSB4TunneledProtocolTraffic

C++

HRESULT ExportUSB4TunneledProtocolTraffic( 
  [in] BSTR output_file_path,
  [in] EUSB4TunneledProtocol protocol)

Exports tunneled USB4 traffic of the specified protocol to file format of native application that corresponds the specified protocol.

Parameters

output_file_path

Specifies the path (with file name) of the output file

protocol

Specifies tunneled protocol:

TUN_PCIE	Tunneled PCIe
TUN_DP	Tunneled Display Port Main Link
TUN_DP_AUX	Tunneled Display Port AUX
TUN_USB3	Tunneled USB3

IUsbTrace13 interface

IUsbTrace13::ExportVisibleTraList

C++

HRESULT ExportVisibleTraList ( [in] BSTR file_path )

Exports visible transactions to JSON format.

Parameters
file_path	Specifies the path (with file name) of the output JSON file.

IUsbTrace14 interface

IUsbTrace14:: LoadDecodingSettings

C++

HRESULT LoadDecodingSettings([in] BSTR file_path)

Load the DecodingSettings from the saved xml file.

Parameters
file_path	Specifies a saved xml path (with file name) of the Decoding Settings.

Remarks

The saved decoding settings file should be corelated with the trace. For example, one (or more) entries of the HopId in the xml file, should match the hopId(s) of the trace file, in order to get overridden.
Level decoding must be finished before calling this api. (For more infromation, refer to IUsbTrace6::IsLevelDecodeFinished)
Currently this is supported for USB4 trace only.

Example: WSH

Visual Basic

TraceName   = "D:\Some trace files\CapturedTrace.usb"
xmlPath     = "D:\Some trace files\DecSettings.xml"
ExportPath  = "D:\Some trace files\CapturedTrace_Exported.usb"
Set Analyzer = WScript.CreateObject("CATC.UsbTracer")
Set Trace    = Analyzer.OpenFile( TraceName )
do while True
if  Trace.IsLevelDecodeFinished(-1) 
Then exit do loop
Trace.LoadDecodingSettings(xmlPath)
Trace.ExportUSB4TunneledProtocolTraffic(ExportPath, 3) 'TUN_USB3

_ITraceEvents interface

The _IUsbEvents interface provides an event interface over trace files objects. This interface is used to through some events from trace analysis to client application. Be noted that this interface is not independent object and sink object in client code [who implements the events methods] should bind to existing trace object to notified by events from trace.

IID: 81C4C56A-AB57-4402-AD11-7D49F7CF450E

ITraceEvents::OnLevelDecodeFinished

C++

HRESULT OnLevelDecodeFinished( 
  [in] int levelId,
  [in] int tag )

This event notifies the client when decoding of any levels in applications like transaction/split/transfer is finished. Client code may start some other process on this level data after receiving the finish decoding event.

Parameters
level_id	Specifies the level at which the decoding process is finished
tag	Specified the unique of trace that was previously set by SetTag.

Remarks

For more detailed information about level IDs, see IUsbTrace6::IsLevelDecodeFinished.

IUsbVerificationScript Interface

The IUsbVerificationScript interface is the seventh interface for the UsbTrace object. It exposes the trace functionality for running verification scripts. It derives from the IVerificationScript interface, which implements the common functionality for running Teledyne LeCroy PSG verification scripts over recorded traces. This interface is not dual, so scripting languages cannot use it directly, though some or all of its methods are exposed to script languages through the primary UsbTrace automation interface.

IID: F1ED8DB5-2EC6-4fa0-8F8B-D645A1FA4A85

Remarks

Verification scripts are special scripts written using Teledyne LeCroy PSG Script Language (CSL), which can be “run” over the recorded trace to “verify” the trace for some verification conditions or to extract more advanced information from the trace. Such scripts utilize a special feature of the USB Protocol Suite application called the “Verification Script Engine”. This feature must be enabled for you to run verification scripts.

(For more information, refer to the USB Protocol Suite User Manual and the USB Protocol Suite VSEngine Manual.)

IUsbVerificationScript::RunVerificationScript

C++

HRESULT RunVerificationScript ( [in] BSTR verification_script, 
[out, retval] VS_RESULT *pResult);

Runs verification script over the recorded trace.

Parameters

verification_script

Name or full path of the verification script to run

pResult

Address of a variable in which to keep the result of verification.

VS_RESULT is an enumeration type that can have these possible meanings:

enum VS_RESULT

{

UNKNOWN = -5,

LICENSE_FAIL = -4, // License for decoding traffic is unavailable.

PARSE_ERROR = -3, // VSE parser encountered an error.

SCRIPT_RUNNING = -2, // Verification script is running.

SCRIPT_NOT_FOUND = -1, // Verification script with the specified name was // not found.

FAILED = 0, // Verification failed.

PASSED = 1, // Verification passed.

DONE = 2, // Verification is done, don’t care about result.

PASSED_WARNING = 3, // Verification passed, but a warning should be issued.

NOT_APPLICABLE = 4, // Verification was not applicable.

PASSED_WITH_NOTE = 5 // Verification passed, and a note should be displayed.

};

Return values
S_OK	If the verification script executed successfully.

Remarks

The name of the verification script is the name of the verification script file (*.vse) without the file extension. For example, for verification script file test.vse, the test name is test. Refer to the Teledyne LeCroy UWB Script Verification Engine Manual for details.

If a full path is specified (such as C:\test.vse), VSE uses it, instead of searching for the script by name in the \Scripts\VFScripts application subfolder.

Example: C++

C++

// In this example, use wrapper functions provided by #import directive.
IUsbTrace* trace;
	. . . 
IUsbVerificationScript* vscript = NULL;
if (SUCCEEDED (trace->QueryInterface( IID_IUsbVerificationScript, (void**)&vscript))
  {
    try
      {
        VS_RESULT result = vscript ->RunVerificationScript("Test1");
	    if(result == PASSED)
	    {
          ::MessageBox( NULL, "Test verification 1 is passed !!!", "UsbAnalyzer client", MB_OK );
	    }
      }
  	catch (_com_error& er)
      {
        if (er.Description().length() > 0)
          ::MessageBox(NULL, er.Description(),  "UsbAnalyzer client", MB_OK);
        else
          ::MessageBox(NULL, er.ErrorMessage(), "UsbAnalyzer client", MB_OK);
        return 1;
      }
  }
else
  {
    ::MessageBox(NULL, "Unable to get IUsbVerificationScript interface !!!",
    _T("UsbAnalyzer client"), MB_OK);
    return 1 ;
  }
	. . .

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.USBTracer")
Set Trace    = Analyzer.OpenFile("C:\Some trace files\some_trace.usb")
Dim Result
Result = Trace.RunVerificationScript("Test1")
If Result = 1 Then
		Msgbox "PASSED"
Else
		Msgbox "FAILED"
End If
MsgBox("Done")

IUsbVerificationScript::GetVScriptEngine

C++

HRESULT GetVScriptEngine( [in] BSTR script_name, 
[out, retval] IVScriptEngine** pVSEngine );

Retrieves a verification script engine object.

Parameters
script_name	String providing the full pathname of the verification script to initialize the script verification engine.
pVSEngine	Address of a pointer to the VScriptEngine object primary interface.

Return values
S_OK	If verification script engine object was successfully retrieved.

Remarks

The name of the verification script is the name of the verification script file (*.vse). See remark to RunVerificationScript for details.

Example: C++

C++

// In this example, use wrapper functions provided by #import directive.
IusbTrace* Usb_trace;
	. . . 
IUsbVerificationScript* Usb_vscript = NULL;
Usb_trace->QueryInterface(IID_ IUsbVerificationScript, (void**)&Usb_vscript))
	assert(Usb_vscript != NULL);
IVScriptEngine* Usb_vsengine = NULL;
Usb_vsengine = Usb_vscript -> GetVScriptEngine(ScriptName);
VS_RESULT result = Usb_vsengine ->RunVScript();
if(result == PASSED)
{
  ::MessageBox( NULL, "Test verification 1 is passed !!!", "UsbAnalyzer client", MB_OK );
}
	. . .

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.USBTracer")
Set Trace    = Analyzer.OpenFile("C:\Some trace files\some_trace.usb")
Dim Result
	Set VSEngine = Trace.GetVScriptEngine(ScriptName)
	Result = VSEngine.RunVScript
If Result = 1 Then
    		Msgbox "PASSED"
Else
    		Msgbox "FAILED"
End If
MsgBox( "Done" )

IUsbVerificationScript::AddComments

C++

HRESULT AddComments([in] BSTR comment);

Add a comment to the trace file. The value provided here is appended to the Comment field, which is found in the Trace Information window.

Parameters
comment	Comment string

Remarks

The available space for comments is 127 characters.

Example: WSH

Visual Basic

Set Analyzer = WScript.CreateObject("CATC.USBTracer")
Set Trace    = Analyzer.OpenFile("C:\Some trace files\some_trace.usb")
Trace.AddComments("Recorded by James on the Rocinante")
MsgBox("Done")