Manual

ManualsBrandsTeledyne LeCroy ManualsSoftwareFireInspector Automation Application Programming Interface

2403 Walsh Avenue, Santa Clara, CA 95051-1302 Tel: +1/408.727.6600 Fax: +1/408.727.6622

Version 1.0

January 11, 2002

FireInspector

™

Automation

Application Programming Interface

User’s Manual

Summary of content (92 pages)

PAGE 1
2403 Walsh Avenue, Santa Clara, CA 95051-1302 Tel: +1/408.727.6600 Fax: +1/408.727.6622 FireInspector™ Automation Application Programming Interface User’s Manual Version 1.
PAGE 2
CATC FireInspector Automation User’s Manual Version 1.0 Document Disclaimer The information contained in this document has been carefully checked and is believed to be reliable. However, no responsibility can be assumed for inaccuracies that may not have been detected. CATC reserves the right to revise the information presented in this document without notice or penalty.
PAGE 3
CATC FireInspector Automation User’s Manual Version 1.0 TABLE OF CONTENTS Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Setting Up Automation for Local Use . . . . . . . . . . . . . . . . . . . . . . 1 Setting Up Automation for Remote Use. . . . . . . . . . . . . . . .
PAGE 4
CATC FireInspector Automation User’s Manual Version 1.0 IRecOptions::SetPostTriggerPercentage. . . . . . . . . . . . . . 54 IRecOptions::SetTriggerBeep. . . . . . . . . . . . . . . . . . . . . . 55 IRecOptions::SetDataTruncate . . . . . . . . . . . . . . . . . . . . . 56 IRecOptions::SetSaveExternalSignals . . . . . . . . . . . . . . . 57 IRecOptions::SetTraceFileName . . . . . . . . . . . . . . . . . . . 58 IRecOptions:: SetFilterPolarity. . . . . . . . . . . . . . . . . . . . . 59 IRecOptions::Reset .
PAGE 5
CATC FireInspector Automation User’s Manual Version 1.0 1. Introduction FireInspector Automation is an Application Programming Interface (API) that allows users to create scripts or programs of FireInspector commands and run these scripts or programs locally or remotely over a network. The name Automation is derived from the goal of allowing engineers to automate test procedures.
PAGE 6
CATC FireInspector Automation User’s Manual Version 1.0 1.3 Setting Up Automation for Remote Use If you intend to run automation remotely over a network, you will need to perform DCOM configuration. These steps are described in Appendix A on page 73.
PAGE 7
FireInspector Automation User’s Manual CATC Version 1.0 2. FireInspector Automation API This chapter describes the commands in the FireInspector Automation API. 2.
PAGE 8
FireInspector Automation User’s Manual CATC Version 1.0 2.2 Command Descriptions The following descriptions are organized into five sections that correspond to the interfaces listed in the table on the previous page.
PAGE 9
FireInspector Automation User’s Manual CATC Version 1.0 2.3 Primary Dual Interface for Analyzer The IFwAnalyzer interface derives from IAnalyzer interface and is the primary interface for the FwAnalyzer object. The IAnalyzer interface implements the common functionality for all CATC analyzers. Class ID: 0B179BC1-DC61-11D4-9B71-000102566088 App ID: CATC.
PAGE 10
FireInspector Automation User’s Manual CATC Version 1.0 2.3.1 IAnalyzer::GetVersion Retrieves the current version of specified subsystem.
PAGE 11
CATC FireInspector Automation User’s Manual Version 1.0 ANALYZERVERSION_SOFTWARE ); } catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox(NULL, er.Description(), _T("FwAnalyzer client") , MB_OK ); else ::MessageBox(NULL, er.ErrorMessage(), _T("FwAnalyzer client"), MB_OK ); return 1; } TCHAR buffer[20]; _stprintf( buffer, _T("Software version:%X.
PAGE 12
FireInspector Automation User’s Manual CATC Version 1.0 2.3.2 IAnalyzer::GetSerialNumber Retrieves serial number of analyzer device. Syntax HRESULT GetSerialNumber ( [out, retval] WORD* serial_number ); Parameters Return values • ANALYZERCOMERROR_INVALIDVERSIONTYPE – specified version type is invalid • ANALYZERCOMERROR_ANALYZERNOTCONNECTED – analyzer device is not connected Remarks Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.
PAGE 13
CATC FireInspector Automation User’s Manual TCHAR buffer[20]; _stprintf( buffer, _T("Serial number: %X"), HIBYTE(serial_number), LOBYTE(serial_number) ); 9 Version 1.
PAGE 14
FireInspector Automation User’s Manual CATC Version 1.0 2.3.3 IAnalyzer::OpenFile Opens trace file. Syntax HRESULT OpenFile ( [in] BSTR file_name, [out, retval] IDispatch** trace ); Parameters • file_name – string providing the full pathname to trace file • trace – address of a pointer to the FwTrace object primary interface Return values • ANALYZERCOMERROR_UNABLEOPENFILE – unable to open file Remarks FwTrace object is created via this method call, if call was successful.
PAGE 15
FireInspector Automation User’s Manual CATC Version 1.
PAGE 16
FireInspector Automation User’s Manual CATC Version 1.0 2.3.4 IAnalyzer::StartGeneration Starts traffic generation from the file. Syntax HRESULT StartGeneration ( [in] BSTR gen_file_name, [in] short gen_mode ); Parameters • gen_file_name – string providing the full pathname to generation file • gen_mode – generation mode: 0 – plays generation file once, 1 – plays generation file in the loop Return values • E_NOTIMPL Remarks Not implemented yet.
PAGE 17
FireInspector Automation User’s Manual CATC 2.3.5 IAnalyzer::StopGeneration Stops generation. Syntax HRESULT StopGeneration ( ); Parameters Return values • E_NOTIMPL Remarks Not implemented yet. Example 13 Version 1.
PAGE 18
FireInspector Automation User’s Manual CATC Version 1.0 2.3.6 IAnalyzer::StartRecording Starts recording with specified recording options.
PAGE 19
FireInspector Automation User’s Manual CATC Version 1.0 . . . try { fw_analyzer->StartRecording( ro_file_name ) } catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("FwAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.
PAGE 20
FireInspector Automation User’s Manual CATC Version 1.0 2.3.7 IAnalyzer::StopRecording Stops recording started by StartRecording method.
PAGE 21
FireInspector Automation User’s Manual CATC Version 1.0 { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("FwAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.
PAGE 22
FireInspector Automation User’s Manual CATC Version 1.0 2.3.8 IAnalyzer::MakeRecording Makes recording with specified recording options file.
PAGE 23
FireInspector Automation User’s Manual CATC Version 1.0 ::MessageBox( NULL, er.
PAGE 24
FireInspector Automation User’s Manual CATC Version 1.0 2.3.9 IAnalyzer::LoadDisplayOptions Loads display options that will apply for trace opened or recorded later. Syntax HRESULT LoadDisplayOptions ( [in] BSTR do_file_name ); 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.
PAGE 25
FireInspector Automation User’s Manual CATC Version 1.0 2.3.10 IAnalyzer::GetRecordingOptions Retrieves primary interface for access to recording options. Syntax HRESULT GetRecordingOptions ( [out, retval] IDispatch** recording_options ); Parameters • recording_options – address of a pointer to the FwRecOptions object primary interface Return values Remarks FwRecOptions object is created via this method call, if call was successful. Example WSH: Set Analyzer = WScript.CreateObject("CATC.
PAGE 26
CATC FireInspector Automation User’s Manual Version 1.
PAGE 27
FireInspector Automation User’s Manual CATC Version 1.0 2.3.11 IFwAnalyzer::EnableConfigROM Sets config ROM that the FireInspector will return to either the default config ROM or to the minimal config ROM. Syntax HRESULT EnableConfigROM ( [in] BOOL bEnable ); Parameters • bEnable – boolean flag that specifies which config ROM FireInspector should return • When bEnable is FALSE, the default config ROM will be disabled and the minimal config ROM will be used instead.
PAGE 28
FireInspector Automation User’s Manual CATC Version 1.0 2.3.12 IFwAnalyzer::LoadConfigROM Loads the config ROM specified by filename and enables it. Syntax HRESULT LoadConfigROM ( [in] BSTR filename ); Parameters • BSTR filename – filename of saved config ROM to be displayed Return values • NOERROR – success • E_FAIL – an error is encountered Remarks Example WSH: C++: IFwAnalyzer* fw_analyzer; ...
PAGE 29
FireInspector Automation User’s Manual CATC Version 1.0 2.3.13 IFwAnalyzer::RetrieveTree Performs a bus reset with a type specified in reset_type and gap count specified in gap_count, then retrieves and displays the topology tree in the FireInspector application. Syntax HRESULT RetrieveTree ( short reset_type, short gap_count ); Parameters • gap_count – can be in the range 0 - 63.
PAGE 30
CATC FireInspector Automation User’s Manual Version 1.0 2.4 Primary Dual Interface for Trace IFwTrace interface is the primary interface for FwTrace object. It derives from ITrace interface that implements the common functionality for all CATC analyzers.
PAGE 31
FireInspector Automation User’s Manual CATC Version 1.0 2.4.1 ITrace::GetName Retrieves trace name. Syntax HRESULT GetName ( [out, retval] BSTR* trace_name ); Parameters Return values • trace_name – the 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: Set Analyzer = WScript.CreateObject("CATC.FwAnalyzer") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.
PAGE 32
FireInspector Automation User’s Manual CATC Version 1.0 2.4.2 ITrace::ApplyDisplayOptions Applies specified display options to the trace. Syntax HRESULT ApplyDisplayOptions ( [in] BSTR do_file_name ); 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 in the recorded or opened trace.
PAGE 33
FireInspector Automation User’s Manual CATC Version 1.0 2.4.3 ITrace::Save Saves trace into file, allows to save a range of packets.
PAGE 34
FireInspector Automation User’s Manual CATC Version 1.0 fw_trace->Save( file_name, packet_from, packet_to ); } catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("FwAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.
PAGE 35
FireInspector Automation User’s Manual CATC Version 1.0 2.4.
PAGE 36
CATC FireInspector Automation User’s Manual Version 1.0 _______| Data(2 quadlets) data_CRC(0x12CC63D9) ACK(pending) Idle( 61.584 µs) _______| Time Stamp(00018.5812 2136) _______|___________________________________________________ 14_____| S(1) WriteResp(lbl: 0) dest_ID(FFC0) src_ID(FFC2) rt(X) _______| rcode(complete) header_CRC(0x2007F63C) ACK(complete) Idle( 19.602 ms) _______| Time Stamp(00018.
PAGE 37
FireInspector Automation User’s Manual CATC Version 1.0 rt(X) _______| rcode(complete) header_CRC(0x2007F63C) ACK(complete) Idle( 51.719 ms) _______| Time Stamp(00018.6898 0958) _______|___________________________________________________ 21_____| S(1) WriteDB(lbl: 51) dest_ID(FFC0) src_ID(FFC2) rt(X) _______| dest_offset(FFFF: F0000B00) data_len(5) header_CRC(0x34C3B5BC) _______| Data(2 quadlets) data_CRC(0x3C9045AC) ACK(complete) Idle( 6.449 ms) _______| Time Stamp(00018.
PAGE 38
CATC FireInspector Automation User’s Manual Version 1.0 ::MessageBox( NULL, er.Description(), _T("FwAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.
PAGE 39
FireInspector Automation User’s Manual CATC Version 1.0 2.4.5 ITrace::Close Closes the trace. Syntax HRESULT Close ( ); Parameters Return values Remarks Closes current trace, do not releases interface pointer. Call IUnknown::Release method right after this method call. No one ITrace method call will succeeded after calling ITrace::Close method. (Currently there is no need to call ITrace::Close directly since IUnknown::Release will close the trace.
PAGE 40
FireInspector Automation User’s Manual CATC Version 1.0 2.4.6 ITrace::ReportFileInfo Saves trace information into specified text file. Syntax HRESULT ReportFileInfo ( [in] BSTR file_name ); Parameters • file_name – string providing the full pathname to file where trace information report is created Return values • ANALYZERCOMERROR_UNABLESAVE – unable to create trace information report Remarks Creates trace information file if necessary. Stores trace information in specified file.
PAGE 41
FireInspector Automation User’s Manual CATC Version 1.0 C++: IFwTrace* fw_trace; TCHAR file_name[_MAX_PATH]; . . . try { fw_trace->ReportFileInfo( file_name ); } catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("FwAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.
PAGE 42
FireInspector Automation User’s Manual CATC Version 1.0 2.4.7 ITrace::ReportErrorSummary Saves trace error summary information into specified text file. Syntax HRESULT ReportErrorSummary ( [in] BSTR file_name ); Parameters • file_name – string providing the full pathname to file where error summary report is created Return values • ANALYZERCOMERROR_UNABLESAVE – unable to create trace information report Remarks Creates error summary file if necessary. Stores error summary in specified file.
PAGE 43
FireInspector Automation User’s Manual CATC Version 1.0 C++: IFwTrace* fw_trace; TCHAR file_name[_MAX_PATH]; . . . try { fw_trace->ReportErrorSummary( file_name ); } catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("FwAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.
PAGE 44
FireInspector Automation User’s Manual CATC Version 1.0 2.4.8 ITrace::ReportTrafficSummary Saves trace traffic summary information into specified text file. Syntax HRESULT ReportTrafficSummary( [in] BSTR file_name ); Parameters • file_name is created – string providing the full pathname to file where traffic summary report Return values • E_NOTIMPL Remarks Not implemented yet.
PAGE 45
CATC FireInspector Automation User’s Manual Version 1.0 2.4.9 ITrace::GetPacket Retrieves raw packet representation.
PAGE 46
FireInspector Automation User’s Manual CATC Version 1.0 (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 --> C++: IFwTrace* fw_trace; LONG packet_number; . . .
PAGE 47
FireInspector Automation User’s Manual CATC Version 1.0 { VARIANT var; HRESULT hr = SafeArrayGetElement(packet_safearray, &i, &var); if (FAILED(hr)) { ::MessageBox( NULL, _T("Error accessing array"), _T("FwAnalyzer client"), MB_OK ); return 1; } if ( var.
PAGE 48
FireInspector Automation User’s Manual CATC Version 1.0 2.4.10 ITrace::GetPacketsCount Retrieves total number of packets in the trace. Syntax HRESULT GetPacketsCount ( [out, retval] long* number_of_packets ); Parameters • number_of_packets – points to long value where number of packets in the trace is retrieved Return values Remarks Example WSH: Set Analyzer = WScript.CreateObject("CATC.FwAnalyzer") CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Trace = Analyzer.
PAGE 49
CATC FireInspector Automation User’s Manual Version 1.
PAGE 50
FireInspector Automation User’s Manual CATC Version 1.0 2.4.11 ITrace::GetTriggerPacketNum Retrieves trigger packet number. Syntax HRESULT GetTriggerPacketNum ( [out, retval] long* packet_number ); Parameters • packet_number – points to long value where trigger packet number is retrieved Return values Remarks Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.FwAnalyzer") Set Trace = Analyzer.
PAGE 51
FireInspector Automation User’s Manual CATC Version 1.0 2.4.12 ITrace::AnalyzerErrors Retrieves trace file errors.
PAGE 52
FireInspector Automation User’s Manual CATC Version 1.0 client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("FwAnalyzer client"), MB_OK ); return 1; } . . .
PAGE 53
CATC FireInspector Automation User’s Manual Version 1.0 2.5 Primary Dual Interface for Recording Options IFwRecOptions interface is the primary interface for IBRecOption object. It derives from IRecOptions interface that implements the common functionality for all CATC analyzers.
PAGE 54
FireInspector Automation User’s Manual CATC Version 1.0 2.5.1 IRecOptions::Load Loads recording options from specified file. Syntax HRESULT Load ( [in] BSTR ro_file_name ); Parameters • ro_file_name – string providing the full pathname to the recording options file Return values • ANALYZERCOMERROR_UNABLEOPENFILE – unable to open file Remarks Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.
PAGE 55
FireInspector Automation User’s Manual CATC Version 1.0 2.5.2 IRecOptions::Save Saves recording options into specified file. Syntax HRESULT Save ( [in] BSTR ro_file_name ); Parameters • ro_file_name – string providing the full pathname to the recording options file Return values • ANALYZERCOMERROR_UNABLEOPENFILE – unable to open file Remarks If specified file does not exist, it will be created; if it does exist, it will be overwritten. Example WSH: CurrentDir = Left(WScript.
PAGE 56
FireInspector Automation User’s Manual CATC Version 1.0 2.5.3 IRecOptions::SetRecMode Sets the recording mode.
PAGE 57
FireInspector Automation User’s Manual CATC Version 1.0 2.5.4 IRecOptions::SetBufferSize Sets the size of buffer to record. Syntax HRESULT SetBufferSize ( [in] long buffer_size ); Parameters • buffer_size – buffer size in bytes Return values • E_INVALIDARG – invalid buffer size was specified Remarks This command sets the size of the buffer allocated in the internal memory of the system.
PAGE 58
FireInspector Automation User’s Manual CATC Version 1.0 2.5.5 IRecOptions::SetPostTriggerPercentage Sets the post-trigger buffer size. Syntax HRESULT SetPostTriggerPercentage ( [in] short posttrigger_percentage ); Parameters • posttrigger_percentage – the size of post-trigger buffer in percents of the whole recording buffer (see section 2.
PAGE 59
FireInspector Automation User’s Manual CATC Version 1.0 2.5.6 IRecOptions::SetTriggerBeep Sets the flag indicating to make a sound when trigger occurs. Syntax HRESULT SetTriggerBeep ( [in] BOOL beep ); Parameters • beep – possible values: • TRUE – beep when trigger occurs • FALSE – do not beep when trigger occurs Return values Remarks The default state of the beeper is FALSE. Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.
PAGE 60
FireInspector Automation User’s Manual CATC Version 1.0 2.5.7 IRecOptions::SetDataTruncate Sets the flag indicating that recorded data is to be truncated and the length of data to truncate. Syntax HRESULT SetDataTruncate ( [in] long length ); Parameters • length – length of data in bytes, could not be less then 108 Return values Remarks By default data is not truncating. Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.
PAGE 61
FireInspector Automation User’s Manual CATC Version 1.0 2.5.8 IRecOptions::SetSaveExternalSignals Sets the flag indicating to save external signals. Syntax HRESULT SetSaveExternalSignals ( [in] BOOL save ); Parameters • save – possible values: • TRUE – save external signals • FALSE – do not save external signals Return values Remarks By default external signals are not saved. Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.
PAGE 62
FireInspector Automation User’s Manual CATC Version 1.0 2.5.9 IRecOptions::SetTraceFileName Sets the path to the file where trace will be stored after recording. Syntax HRESULT SetTraceFileName ( [in] BSTR file_name ); Parameters • file_name – string providing the full pathname to the file where recording will be stored Return values Remarks If specified file does not exist, it will be created; if it does exist, it will be overwritten. Example WSH: CurrentDir = Left(WScript.
PAGE 63
FireInspector Automation User’s Manual CATC Version 1.0 2.5.10 IRecOptions:: SetFilterPolarity Sets the whether to filter in or out the recording events. Syntax HRESULT SetFilterPolarity ( [in] BOOL filter_out ); Parameters • filter_out – possible values: • TRUE – filter out • FALSE – filter in Return values • E_INVALIDARG – operation code and/or connection was specified Remarks By default all events are filtered out. Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.
PAGE 64
FireInspector Automation User’s Manual CATC Version 1.0 2.5.11 IRecOptions::Reset Resets recording options to its initial state. Syntax HRESULT Reset ( ); Parameters Return values Remarks For default values of recording options see the Remarks for Sections 2.5.1 to 2.5.10. Example WSH: CurrentDir = Left(WScript.ScriptFullName, InstrRev(WScript.ScriptFullName, "\")) Set Analyzer = WScript.CreateObject("CATC.FwAnalyzer") Set RecOptions = Analyzer.GetRecordingOptions RecOptions.
PAGE 65
CATC FireInspector Automation User’s Manual Version 1.0 2.6 Errors Collection Interface The IAnalyzerErrors dispinterface is a standard collection interface for collection of errors of specified type (see ITrace::AnalyzerErrors on page 47).
PAGE 66
FireInspector Automation User’s Manual CATC Version 1.0 2.6.1 IAnalyzerErrors::get_Item Retrieves an Analyzer error. Use IAnalyzerErrors::get_Count to retrieve the number of errors. Syntax HRESULT get_Item( [in] long index, [out, retval] long* packet_number ); Parameters • index – index of error in the collection • packet_number – points to long value where error packet number is retrieved Return values Remarks Example See IAnalyzerErrors::get_Count on page 63.
PAGE 67
FireInspector Automation User’s Manual CATC Version 1.0 2.6.2 IAnalyzerErrors::get_Count Retrieves the number of Analyzer errors. Use IAnalyzerErrors::get_Item to retrieve the actual errors. Syntax HRESULT get_Count( [out, retval] long* number_of_errors ); Parameters • number_of_errors – points to long value where number of elements in the collection is retrieved Return values Remarks Example WSH: C++: IFwTrace* fw_trace; . . .
PAGE 68
FireInspector Automation User’s Manual CATC Version 1.0 { analyzer_error = analyzer_errors->GetItem(i); TCHAR cur_error[32]; _stprintf( cur_error, _T(" %ld"), analyzer_error ); _tcscat( all_errors, cur_error ); } if ( i>2048/32 ) _tcscat( all_errors, _T(" ...") ); } catch ( _com_error& er) { if (er.Description().length() > 0) ::MessageBox( NULL, er.Description(), _T("FwAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.
PAGE 69
CATC FireInspector Automation User’s Manual Version 1.0 2.7 Analyzer Events Callback Interface The _IAnalyzerEvents interface is a standard COM event interface that fires events to the client at recording Start/Stop moments and when the analyzer state changes.
PAGE 70
CATC FireInspector Automation User’s Manual Version 1.0 2.7.1 IAnalyzerEvents dispinterface In order to retrieve the events from FireInspector application you must implement _IAnalyzerEvents interface. Since this interface is default source interface for FwAnalyzer object there is very simple implementation from languages such as Visual Basic, VBA, VBScript, WSH etc.
PAGE 71
FireInspector Automation User’s Manual CATC Version 1.0 2.7.2 IAnalyzerEvents::OnTraceCreated Fired when trace is created; this event is a result of IAnalyzer::StartRecording/ IAnalyzer::StopRecording method call. Syntax HRESULT OnTraceCreated ( [in] IDispatch* trace ); Parameters • trace – address of a pointer to the FwTrace object primary interface Return values Remarks Make sure the event handlers have _stdcall calling convention.
PAGE 72
CATC FireInspector Automation User’s Manual ::MessageBox( NULL, er.Description(), _T("FwAnalyzer client"), MB_OK ); else ::MessageBox( NULL, er.ErrorMessage(),_T("FwAnalyzer client"), MB_OK ); return hr; } . . . return hr; } 68 Version 1.
PAGE 73
FireInspector Automation User’s Manual CATC Version 1.0 2.7.3 _IAnalyzerEvents::OnStatusReport Fired when there is a change in analyzer's state or there is a change in progress (percent_done) of analyzer's state.
PAGE 74
FireInspector Automation User’s Manual CATC Version 1.
PAGE 75
FireInspector Automation User’s Manual CATC Version 1.
PAGE 76
FireInspector Automation User’s Manual CATC Version 1.0 break; case FW_ASR_SYNC_STATE_SYNCING: _tcscpy( m_SyncStatus, _T("Syncing...
PAGE 77
CATC FireInspector Automation API User’s Manual Version 1.0 Appendix A: Setting Up FireInspector Automation FireInspector Automation is an Application Programming Interface (API) that allows users to create scripts or programs of FireInspector commands and run these scripts or programs locally or remotely over a network. The name Automation is derived from the goal of allowing engineers to automate test procedures.
PAGE 78
CATC FireInspector Automation API User’s Manual Version 1.0 A.3 Setting Up Automation for Remote Use If you intend to run automation over a network, you will need to perform DCOM configuration and a few other steps. These steps enable the FireInspector application to be automated. A Summary of the Steps: • Run the Microsoft utility dcomcnfg on the FireInspector host computer and configure the host computer as a server so that it can be controlled by another device.
PAGE 79
CATC FireInspector Automation API User’s Manual Version 1.0 Step 2 In the Open edit box within the Run dialog, type dcomcnfg. Step 3 Click OK. The Distributed COM Configuration Properties utility opens. The Applications tab is displayed by default. Set Authentication Level The dcomcnfg utility presents a number of security options. In the steps that follow, configure the FireInspector application on the FireInspector host computer to authenticate the user when the user first attempts a connection.
PAGE 80
CATC FireInspector Automation API User’s Manual Step 2 Version 1.0 Click the Properties button. The FwAnalyzer Properties dialog box opens. The options in this dialog box allow you to configure security on the selected application. Step 3 Select Connect from the Authentication Level pull-down menu on the General tab of the FwAnalyzer Properties dialog. The Authentication Level menu lets you set packet-level security on communications for the selected application.
PAGE 81
CATC FireInspector Automation API User’s Manual Version 1.0 Set Access Permissions Access permission determines who may execute commands on the application once it is running. In the following steps, you give everyone access to the FireInspector application on the host computer. Step 1 Select the Security tab in the FwAnalyzer Properties dialog.
PAGE 82
CATC FireInspector Automation API User’s Manual Version 1.0 The Registry Value Permissions dialog box appears. Step 4 Click the Add... button. The Add Users and Groups dialog box appears. Step 5 Select the group called Everyone. Step 6 Click the Add button. Step 7 Select the group System. Step 8 Click the Add button. Step 9 Click OK. T he Add Users and Groups dialog box closes. The Registry Value Permissions dialog box remains on the screen. Step 10 Click OK.
PAGE 83
CATC FireInspector Automation API User’s Manual Version 1.0 The Add Users and Groups dialog appears. Step 4 Select the group called Everyone. If you prefer, you can select individual user accounts instead of Everyone. Step 5 Click the Add... button. Step 6 Click OK. T he Add Users and Groups dialog box closes. The Registry Value Permissions dialog box remains on the screen. Step 7 Click OK. The Registry Value Permissions dialog box closes.
PAGE 84
CATC FireInspector Automation API User’s Manual Version 1.0 Set User Identity Permissions If you want to create password-based security for individual users, perform the following steps on the host computer: Step 1 From the FwAnalyzer Properties dialog box, select the Identity tab. Step 2 Click the This User option. Step 3 In the User box, type the name of the user account that will be using the application.
PAGE 85
CATC FireInspector Automation API User’s Manual Version 1.0 A.5 DCOM Client Configuration To configure the DCOM client, run the DCOM configuration utility dcomcnfg on the remote computer. This utility will present a list of installed applications. Select the FireInspector application and apply authentication, permissions, location, and protocol settings.
PAGE 86
CATC FireInspector Automation API User’s Manual Version 1.0 Set Server Location You need to identify the device upon which the client will be executing its commands. Step 1 With the FwAnalyzer Properties dialog box still open, click the Location tab. The Location window displays. Step 2 Select Run application on the following computer. Step 3 In the text box below the selected option, enter the Host Name or IP address of the FireInspector host computer.
PAGE 87
CATC FireInspector Automation API User’s Manual Step 2 Select the option Enable Distributed COM on this computer. Step 3 Set the Default Authentication Level to Default. Step 4 Set the Default Impersonation Level to Identify. Version 1.0 Set Default Network Protocol Step 1 In the Distributed COM Configuration Properties utility, click the Default Protocols tab. Make sure that Connection-oriented TCP/IP appears at the top of the list of DCOM protocols.
PAGE 88
CATC FireInspector Automation API User’s Manual Version 1.0 and press OK. The protocol will be added to the bottom of the list of DCOM Protocols. Use the Move Up button to move it to the top of the list. Step 2 Click OK to close the Distributed COM Configuration Properties utility. Your PC is now configured to run FireInspector Automation. A.
PAGE 89
CATC FireInspector Automation API User’s Manual Version 1.0 Note If you prefer, you can copy the executable to the remote computer’s hard drive and launch it from there. The FireDrive application will start. Step 2 In the Open File section of the FireDrive application window, press the Trace File button. The Open FireInspector Trace File dialog will open. Step 3 Select a trace (.fdb) file and click Open.
PAGE 90
CATC FireInspector Automation API User’s Manual Version 1.0 These messages indicate that a connection has been established with the FireInspector host computer and the FireInspector application has automatically launched on the host computer. Troubleshooting Automation Setup • If the message “The RPC server is unavailable” appears when you attempt to open a trace file, check the network connections between the two PCs.
PAGE 91
CATC FireInspector Automation API User’s Manual Version 1.0 Appendix B: How to Contact CATC Type of Service Call for technical support… Contact US and Canada: 1 (800) 909-2282 Worldwide: 1 (408) 727-6600 Fax your questions… Worldwide: 1 (408) 727-6622 Write a letter… Computer Access Technology Corp. Customer Support 2403 Walsh Avenue Santa Clara, CA 95051-1302 Send e-mail… support@CATC.com Visit CATC’s web site… http://www.CATC.
PAGE 92
CATC FireInspector Automation API User’s Manual 88 Version 1.