ISession Interface

interface ISession {
    // Properties
    readonly ${state}: ${Session.State};
    ${precise}: boolean;
    readonly ${visualizers}: ${IVisualizer}[];

    // Methods
    ${addDevice}(deviceName?: string, serverName?: string): void;
    ${addDevice#addDevice1}(device?: { serial: string }, serverName?: string): void;
    ${addDevice#addDevice2}(device?: { usb: { device?: string; port?: number; address?: number; serialNumber?: string; } }, serverName?: string): void;
    ${addDevice#addDevice3}(device?: { network: string }, serverName?: string): void;
    ${addDevice#addDevice4}(device?: { virtual: any }, serverName?: string): ${ISession};
    ${addDevice#addDevice5}(device?: { playback: { path: string; stream?: number; } }, serverName?: string): void;
    ${addDevice#addDevice6}(device?: { bridge: string | ${IBridge} }, serverName?: string): void;
    ${addVisualizer}(name: string): ${IVisualizer};
    ${addVisualizer#addVisualizer1}(name: "Data Recording",
        config?: ${VisConfig.Recorder}): ${DataRecording.IRecordingVisualizer2};
    ${addVisualizer#addVisualizer2}(name: "Structure View",
        structure_view_config?: { filter?: ${VisConfig.Filter}; bind?: string; }): ${IVisualizer};
    ${addVisualizer#addVisualizer3}(name: "Raw Data View",
        raw_data_view_config?: { filter?: ${VisConfig.Filter}; bind?: string; }): ${IVisualizer};
    ${addVisualizer#addVisualizer4}(name: "PPP View",
        ppp_view_config?: { filter?: ${VisConfig.Filter}; bind?: string; }): ${IVisualizer};
    ${addVisualizer#addVisualizer5}(name: "Raw Exporter",
        raw_exporter_config?: { exporter: ${VisConfig.Exporter}; filter?: ${VisConfig.Filter}; bind?: string; }): ${IVisualizer};
    ${addVisualizer#addVisualizer6}(name: "Text Exporter",
        text_exporter_config?: { exporter: ${VisConfig.Exporter}; filter?: ${VisConfig.Filter}; bind?: string; }): ${IVisualizer};
    ${start}(): void;
    ${stop}(): void;
    ${pause}(): void;
    ${resume}(): void;
    ${setCaptureFilter}(config: ${VisConfig.Filter}): void;
    ${configureSource}(config: { playback: ${Playback.Config} }): void;
    ${configureSource#configureSource1}(config: { path: string }): void;
    ${configureSource#configureSource2}(config: { serial: ${Serial.CommunicationsMode}; }): void;
    ${configureSource#configureSource3}(config: { serial: { mode: ${Serial.CommunicationsMode}; script?: string; discardEmptyReads?: boolean; terminal?: ${IDeviceConfig}; } }): void;
    ${configureSource#configureSource4}(config: { multi: ${Multi.Color}[]; }): void;
    ${saveToLog}(config: ${VisConfig.Recorder}): Promise<void>;
}

// This interface is not available in managed environment

// This interface is not available in native environment

ISession Properties

state

readonly state: ${Session.State};

// This property is not available in managed environment

// This property is not available in native environment

Returns current session state.

precise

precise: boolean;

// This property is not available in managed environment

// This property is not available in native environment

Returns or sets current session's precise timing mode. Timing mode may only be changed before the session is started.

visualizers

readonly visualizers: ${IVisualizer}[];

// This property is not available in managed environment

// This property is not available in native environment

Returns an array of references to data visualizer objects.

Note that each time you query this property, a new object is created for each data visualizer. This means that expression session.visualizers[0] === session.visualizers[0] will never be true. Use the IVisualizer.equals method to test whether two references describe the same object.

ISession Methods

addDevice

addDevice(deviceName?: string, serverName?: string): void;

// This method is not available in managed environment

// This method is not available in native environment

deviceName: An optional string which is parsed by each installed data source in turn until the matched device is found. If omitted, device may later added using ISession.addDevice method.
serverName: Optional remote server name. If omitted, or passed empty string or ".", local monitoring session is created.

Adds a specified device to the session. A monitoring session may have several devices but they all must be of the same type.

This overload uses generic string matching. It cycles through all installed modules and performs exact device name match. Serial module also supports device names of the form “COMx” where x is a number from 1 to 255.

addDevice

addDevice(device?: { serial: string }, serverName?: string): void;

// This method is not available in managed environment

// This method is not available in native environment

device: A serial device identifier (full name or COM port).
serverName: Optional remote server name. If omitted, or passed empty string or ".", local monitoring session is created.

Adds a specified device to the session. A monitoring session may have several devices but they all must be of the same type.

addDevice

addDevice(device?: { usb: { device?: string; port?: number; address?: number; serialNumber?: string; } }, serverName?: string): void;

// This method is not available in managed environment

// This method is not available in native environment

device: An USB device to connect to. Empty configuration object means “Next connected device”. A combination of device, port and address fields use to identify the device you want to monitor. Alternatively, use the serialNumber field to identify the device.
serverName: Optional remote server name. If omitted, or passed empty string or ".", local monitoring session is created.

Adds a specified device to the session. A monitoring session may have several devices but they all must be of the same type.

addDevice

addDevice(device?: { network: string }, serverName?: string): void;

// This method is not available in managed environment

// This method is not available in native environment

device: A network device identifier (full adapter name).
serverName: Optional remote server name. If omitted, or passed empty string or ".", local monitoring session is created.

Adds a specified device to the session. A monitoring session may have several devices but they all must be of the same type.

addDevice

addDevice(device?: { virtual: any }, serverName?: string): ${ISession};

// This method is not available in managed environment

// This method is not available in native environment

device: An object of the following type: to reference Import Data Source.
serverName: Optional remote server name. If omitted, or passed empty string or ".", local monitoring session is created.

Adds a specified device to the session. A monitoring session may have several devices but they all must be of the same type.

addDevice

addDevice(device?: { playback: { path: string; stream?: number; } }, serverName?: string): void;

// This method is not available in managed environment

// This method is not available in native environment

device: An object which references a given log file and optionally a stream in it.
serverName: Optional remote server name. If omitted, or passed empty string or ".", local monitoring session is created.

Adds a specified device to the session. A monitoring session may have several devices but they all must be of the same type.

addDevice

addDevice(device?: { bridge: string | ${IBridge} }, serverName?: string): void;

// This method is not available in managed environment

// This method is not available in native environment

device: A serial bridge name or a reference to IBridge interface.
serverName: Optional remote server name. If omitted, or passed empty string or ".", local monitoring session is created.

Adds a specified device to the session. A monitoring session may have several devices but they all must be of the same type.

Adding devices to the session:

var session = monitoring.createSession();

// Add COM1 serial device to it (use automatic matching):
session.addDevice("COM1");

// Add specific serial device:
session.addDevice({ serial: "Communications Port (COM1)" });

// Add specific USB device:
session.addDevice({ usb: { device: "USB Input Device", port: 4, address: 1 } });

// Add specific network adapter:
session.addDevice({ network: "Realtek PCIe GBE Family Controller(802.3)" });

// Add specific log file:
session.addDevice({ playback: { path: "C:\\temp\\Communications Port (COM1)$140408$1.dmslog8", stream: 0 } });

// Create remote monitoring session for serial port
session.addDevice("COM5", "remote_server_name");

addVisualizer

addVisualizer(name: string): ${IVisualizer};

// This method is not available in managed environment

// This method is not available in native environment

name: Data visualizer name.

Adds a data visualizer to the session. The method takes a name of data visualizer and an optional configuration object. Several data visualizers support configuration while some require it.

This method is overloaded to help check syntax.

addVisualizer

addVisualizer(name: "Data Recording",
    config?: ${VisConfig.Recorder}): ${DataRecording.IRecordingVisualizer2};

// This method is not available in managed environment

// This method is not available in native environment

name: Name of the Data Recording processing module.
config: Optional logging configuration object.

Adds a Data Recording component to the session.

addVisualizer

addVisualizer(name: "Structure View",
    structure_view_config?: { filter?: ${VisConfig.Filter}; bind?: string; }): ${IVisualizer};

// This method is not available in managed environment

// This method is not available in native environment

name: Name of the Structure View data visualizer.
structure_view_config: Optional configuration object which configures visualizer's Display Filter (filter object) and Root Protocol (bind string). See VisConfig.Filter for more information on configuring Display Filter. Root Protocol may be configured using the bind parameter.

Adds a Structure View data visualizer to the session.

addVisualizer

addVisualizer(name: "Raw Data View",
    raw_data_view_config?: { filter?: ${VisConfig.Filter}; bind?: string; }): ${IVisualizer};

// This method is not available in managed environment

// This method is not available in native environment

name: Name of the Raw Data View data visualizer.
raw_data_view_config: Optional configuration object which configures visualizer's Display Filter (filter object) and Root Protocol (bind string). See VisConfig.Filter for more information on configuring Display Filter. Root Protocol may be configured using the bind parameter.

Adds a Raw Data View data visualizer to the session.

addVisualizer

addVisualizer(name: "PPP View",
    ppp_view_config?: { filter?: ${VisConfig.Filter}; bind?: string; }): ${IVisualizer};

// This method is not available in managed environment

// This method is not available in native environment

name: Name of the PPP View data visualizer.
ppp_view_config: Optional configuration object which configures visualizer's Display Filter (filter object) and Root Protocol (bind string). See VisConfig.Filter for more information on configuring Display Filter. Root Protocol may be configured using the bind parameter.

Adds a PPP View data visualizer to the session.

addVisualizer

addVisualizer(name: "Raw Exporter",
    raw_exporter_config?: { exporter: ${VisConfig.Exporter}; filter?: ${VisConfig.Filter}; bind?: string; }): ${IVisualizer};

// This method is not available in managed environment

// This method is not available in native environment

name: Name of the Raw Exporter data processing module.
raw_exporter_config: Configuration object must configure the exporter settings and may optionally configure Display Filter (filter object) and Root Protocol (bind string). To configure exporter, see the VisConfig.Exporter topic for more information.

Adds a Raw Exporter data processing module to the session.

addVisualizer

addVisualizer(name: "Text Exporter",
    text_exporter_config?: { exporter: ${VisConfig.Exporter}; filter?: ${VisConfig.Filter}; bind?: string; }): ${IVisualizer};

// This method is not available in managed environment

// This method is not available in native environment

name: Name of the Text Exporter data processing module.
text_exporter_config: Configuration object must configure the exporter settings and may optionally configure Display Filter (filter object) and Root Protocol (bind string). To configure exporter, see the VisConfig.Exporter topic for more information.

Adds a Text Exporter data processing module to the session.

Adding devices to the session:

var session = monitoring.createSession();

// Add Request View visualizer
session.addVisualizer("Request View");

// Add Structure View visualizer with default configuration
session.addVisualizer("Structure View");

// Add PPP View visualizer and configure both Display Filter and Root Protocol
session.addVisualizer("PPP View",{filter: {name:"IO packets only"}, bind: "PPP"});

// Add Raw Exporter and configure it
session.addVisualizer("Raw Exporter",{exporter: {path: "c:\\temp\\raw.bin", overwrite: true, nocache: false}});

start

start(): void;

// This method is not available in managed environment

// This method is not available in native environment

Start monitoring session. Make sure at least one device and one data visualizer are successfully added to the session before calling this method. You may add devices using ISession.addDevice method and visualizers using ISession.addVisualizer.

Several data sources may support or require configuration using ISession.configureSource method.

An optional Capture Filter may be specified for monitoring session using ISession.setCaptureFilter method.

Creating, configuring and starting a monitoring session:

var session = monitoring.createSession();
session.addDevice({ serial: "Communications Port (COM1)" });
session.addVisualizer("Data View");
session.start();

stop

stop(): void;

// This method is not available in managed environment

// This method is not available in native environment

Stops a monitoring session. A monitoring session object may not be used after the session has been stopped. Only requesting the session state is allowed it.

pause

pause(): void;

// This method is not available in managed environment

// This method is not available in native environment

Pauses a running monitoring session.

resume

resume(): void;

// This method is not available in managed environment

// This method is not available in native environment

Resumes a paused monitoring session.

setCaptureFilter

setCaptureFilter(config: ${VisConfig.Filter}): void;

// This method is not available in managed environment

// This method is not available in native environment

config: Capture Filter configuration parameter.

Configure session's Capture Filter.

Configuring Capture Filter:

// Use predefined capture filter
session.setCaptureFilter({ name: "IO packets only"});

// Use custom capture filter
session.setCaptureFilter({ expression: "usb.urb.BulkOrInterrupt.TransferBufferLength > 500" });

configureSource

configureSource(config: { playback: ${Playback.Config} }): void;

// This method is not available in managed environment

// This method is not available in native environment

config: Playback configuration object. See Playback.Config for more information.

Configure the Playback data source.

Configure Playback Source:

var session = monitoring.createSession();
session.addDevice({ playback: { path: "C:\\temp\\Communications Port (COM1)$140408$1.dmslog8", stream: 0 } });
session.configureSource({ playback: { scale: Playback.Scale.FourToOne }});

configureSource

configureSource(config: { path: string }): void;

// This method is not available in managed environment

// This method is not available in native environment

config: Full path to the import log file. This configures the Virtual Network Adapter source.

Configure the Import Source.

configureSource

configureSource(config: { serial: ${Serial.CommunicationsMode}; }): void;

// This method is not available in managed environment

// This method is not available in native environment

config: Serial data source communications mode. See Serial.CommunicationsMode for more information.

Configure the Serial data source.

var session = monitoring.createSession();
session.addDevice({ serial: "Communications Port (COM1)" });
session.configureSource({ serial: Serial.CommunicationsMode.PPP});

configureSource

configureSource(config: { serial: { mode: ${Serial.CommunicationsMode}; script?: string; discardEmptyReads?: boolean; terminal?: ${IDeviceConfig}; } }): void;

// This method is not available in managed environment

// This method is not available in native environment

config: Configuration object used to configure custom communication mode or general mode with specific value for discardEmptyReads (defaults to true). You can also configure the terminal session by passing the IDeviceConfig interface.

Configure the Serial data source.

configureSource

configureSource(config: { multi: ${Multi.Color}[]; }): void;

// This method is not available in managed environment

// This method is not available in native environment

config: A configuration object with color array to configure Multi-Source data source. May be combined with other configuration objects if applicable. See Multi.Color for more information.

Configure the Multi-Source data source.

Configure both Serial and Multi-Source:

var session = monitoring.createSession();
session.addDevice({ serial: "Communications Port (COM1)" });
session.addDevice({ serial: "Next connected device" });
session.configureSource({ multi: [{ r: 250, g: 187, b: 0, a: 112 }, { r: 64, g: 64, b: 64, a: 112 }], 
        serial: Serial.CommunicationsMode.PPP});

saveToLog

saveToLog(config: ${VisConfig.Recorder}): Promise<void>;

// This method is not available in managed environment

// This method is not available in native environment

config: Logging configuration object. At least the path parameter must be specified and must be the full path to the resulting log file. Other configuration parameters may be omitted, in which case defaults will be used.

Start the Save to Log command on the current session object. This method pauses the monitoring session, asynchronously executes the save to log command and then resumes the session. It can throw a number of exceptions if given parameters are not valid or the session is currently in invalid state.

async function saveSession(session: ISession, path: string) {
        await session.saveToLog({ path: path });
}

IVisualizer DataRecording.IRecordingVisualizer2 VisConfig.Recorder VisConfig.Exporter VisConfig.Filter Playback.Config Serial.CommunicationsMode Multi.Color IDeviceConfig Session.State