ITerminalSession Interface

This interface is implemented by the terminal session object. You receive a session object either from ITerminalManager.sessions array, or through a call to ITerminalManager.createSession method.

Declaration

interface ITerminalSession {
    // Properties
    ${friendlyName}: string;
    ${portName}: string;
    ${config}: ${IDeviceConfig};
    ${rts}: boolean;
    ${dtr}: boolean;
    readonly ${cts}: boolean;
    readonly ${dsr}: boolean;
    readonly ${dcd}: boolean;
    readonly ${ring}: boolean;
    readonly ${visible}: boolean;

    // Methods
    ${xon}(): void;
    ${xoff}(): void;
    ${breakOn}(): void;
    ${breakOff}(): void;
    ${start}(): void;
    ${stop}(): void;
    ${send#send1}(text: string): Promise<void>;
    ${send#send2}(byte: number): Promise<void>;
    ${send#send3}(bytes: number [] | Uint8Array | Uint16Array | Uint32Array | ArrayBuffer | DataView): Promise<void>;
    ${sendAs}(sendAs: ${Terminal.SendAs}, data: number [] | Uint8Array | Uint16Array | Uint32Array | ArrayBuffer | DataView, bigEndian?: boolean): Promise<void>;
    ${sendFile}(fileName: string, byLines: boolean): Promise<void>;
    ${receive}(): Promise<Uint8Array>;

    // Events
    ${sent}(handler: (data: Uint8Array) => void): number;
    ${sent}(eventId: number): void;
    ${received}(handler: (data: Uint8Array) => void): number;
    ${received}(eventId: number): void;
}

// This interface is not available in managed environment

// This interface is not available in native environment

ITerminalSession Properties

friendlyName

friendlyName: string;

// This property is not available in managed environment

// This property is not available in native environment

The session friendly name.

portName

portName: string;

// This property is not available in managed environment

// This property is not available in native environment

The property stores the so-called device interface string for a serial device. The device interface is one of the following:

The string of format “COMn”, where n is the port number. It is internally converted to a string “\.\COMn”.
The string of format “\.\COMn”, which is equivalent to the previous.
The device interface string of format "\?\acpi#pnp0501#1#{0100fdd7-be5a-4808-91f5-05002bc60f72}", which uniquely identifies any device in the system. The various tools, including Device Monitoring Studio itself may be used to obtain device interfaces for installed devices.

config

config: ${IDeviceConfig};

// This property is not available in managed environment

// This property is not available in native environment

Get or set a terminal session configuration object. See IDeviceConfig interface for details. Any configuration object property may be omitted, in which case the system default value is used.

rts

rts: boolean;

// This property is not available in managed environment

// This property is not available in native environment

Ready To Send signal state (RTS).

dtr

dtr: boolean;

// This property is not available in managed environment

// This property is not available in native environment

Data Terminal Ready signal state (DTR).

cts

readonly cts: boolean;

// This property is not available in managed environment

// This property is not available in native environment

Clear To Send signal state (CTS). This property is read-only.

dsr

readonly dsr: boolean;

// This property is not available in managed environment

// This property is not available in native environment

Data Set Ready signal state (DSR). This property is read-only.

dcd

readonly dcd: boolean;

// This property is not available in managed environment

// This property is not available in native environment

Data Carrier Detect (DCD). This property is read-only.

ring

readonly ring: boolean;

// This property is not available in managed environment

// This property is not available in native environment

Ring Indicator (RI). This property is read-only.

visible

readonly visible: boolean;

// This property is not available in managed environment

// This property is not available in native environment

true if this session is visible in UI, false otherwise. This property is read-only.

ITerminalSession Methods

xon

xon(): void;

// This method is not available in managed environment

// This method is not available in native environment

Simulate that XON character received.

xoff

xoff(): void;

// This method is not available in managed environment

// This method is not available in native environment

Simulate that XOFF character received.

breakOn

breakOn(): void;

// This method is not available in managed environment

// This method is not available in native environment

Simulate BREAK ON state.

breakOff

breakOff(): void;

// This method is not available in managed environment

// This method is not available in native environment

Simulate BREAK OFF state.

start

start(): void;

// This method is not available in managed environment

// This method is not available in native environment

Start a terminal session.

stop

stop(): void;

// This method is not available in managed environment

// This method is not available in native environment

Stop a terminal session. This will cause the opened handle to a serial device to be closed.

send

send(text: string): Promise<void>;

// This method is not available in managed environment

// This method is not available in native environment

text: String to be sent to the terminal session.

Send data to a terminal session. A given string is converted to ANSI and sent to the port.

send

send(byte: number): Promise<void>;

// This method is not available in managed environment

// This method is not available in native environment

byte: A single byte to be sent to the terminal session.

Send a given byte to a terminal session.

send

send(bytes: number [] | Uint8Array | Uint16Array | Uint32Array | ArrayBuffer | DataView): Promise<void>;

// This method is not available in managed environment

// This method is not available in native environment

bytes: A JavaScript array of integer numbers to be sent to the terminal session.

Send a passed byte array to a terminal session.

sendAs

sendAs(sendAs: ${Terminal.SendAs}, data: number [] | Uint8Array | Uint16Array | Uint32Array | ArrayBuffer | DataView, bigEndian?: boolean): Promise<void>;

// This method is not available in managed environment

// This method is not available in native environment

sendAs: @split A constant that tells how to interpret numbers in an array. See Terminal.SendAs for more information.
data: A JavaScript array of integer numbers to send to the port. Numbers are interpreted according to sendAs parameter.
bigEndian: An optional boolean parameter, which if passed and equals to true tells terminal session to use big-endian encoding for integers. Ignored for when sendAs equals Terminal.SendAs.Bytes. Equals false if omitted.

Send a number array to terminal session. First parameter tells how to interpret numbers in an array and the second parameter is a Javascript array of integer numbers.

Send data to the terminal session

await session.sendAs(Terminal.SendAs.Words, [ 0x4154, 0x440d ], true);

sendFile

sendFile(fileName: string, byLines: boolean): Promise<void>;

// This method is not available in managed environment

// This method is not available in native environment

fileName: Full path to a file to send. Specify empty string to open dialog box, that will allow you to visually select file using system Open File dialog.
byLines: If this parameter is true, the file is analyzed and split into the lines. The lines are then sent to the serial terminal session. If this parameter is false, the file is sent to the session byte by byte.

Send contents of a file to the terminal session.

receive

receive(): Promise<Uint8Array>;

// This method is not available in managed environment

// This method is not available in native environment

A promise object that produces a byte array when ready.

Receive (read) data from the terminal session.

Receive data from the terminal session

async function check(session)
{
  await session.send("AT\n");
  var response = await session.receive();
}

ITerminalSession Events

sent

sent(handler: (data: Uint8Array) => void): number;
sent(eventId: number): void;

data: Sent bytes in JavaScript array.

This event is fired when new data is sent to the serial device.

First overload is used to bind new handler to the event. It returns a numeric eventId which then may be passed to second overload to unbind a handler.

Sample sent data handler for a text protocol.

var user_session = terminal.sessions[0];
var eventId = user_session.sent(function(data)
{
  alert(data.length + " bytes sent to " + user_session.FriendlyName + ".\n");
});

// ...
// Unbind event handler when not needed anymore
user_session.sent(eventId);

received

received(handler: (data: Uint8Array) => void): number;
received(eventId: number): void;

data: Received bytes in JavaScript array.

This event is fired when new data is received from the serial device.

First overload is used to bind new handler to the event. It returns a numeric eventId which then may be passed to second overload to unbind a handler.

Sample received data handler for a text protocol.

var user_session = terminal.sessions[0];
var eventId = user_session.received(function(data)
{
  alert(data.length + " bytes received to " + user_session.FriendlyName + ".\n");
});

// ...
// Unbind event handler when not needed anymore
user_session.received(eventId);

IDeviceConfig Terminal.SendAs