IVirtualSerialDevice Interface

You obtain this interface either as a result of a call to IVirtualSerialLibrary.createDevice method or as a result of enumeration (see IVirtualSerialLibrary.devicesCollection and IVirtualSerialLibrary.devicesArray).

Declaration

interface IVirtualSerialDevice {
    // Properties
    readonly ${mode}: ${VirtualSerialDeviceMode};
    readonly ${path}: string;
    readonly ${deleted}: boolean;
    ${portName}: string;
    readonly ${vLibrary}: ${IVirtualSerialLibrary};
    readonly ${connections}: number;
    readonly ${bytesSent}: number;
    readonly ${bytesReceived}: number;
    ${enabled}: boolean;
    ${crossoverProbability}: number;
    ${emulateTxOverflow}: boolean;
    readonly ${securityDescriptor}: string;
    readonly ${pipeName}: string;
    readonly ${pair}: ${IVirtualSerialDevice};
    readonly ${remoteServer}: string;
    readonly ${remotePort}: string;
    readonly ${remoteEndpoint}: string;
    readonly ${localSocket}: ${ISocket};
    readonly ${remoteSocket}: ${ISocket};
    readonly ${inputFileName}: string;
    readonly ${outputFileName}: string;

    // Methods
    ${deleteDevice}(): void;
    ${disconnectDevice}(): void;
    ${startListening}(securityDescriptor?: string): void;
    ${connectToPipe}(pipeName: string): void;
    ${createAndConnectPipe}(pipeName: string,
        numberOfInstances: number,
        outputBufferSize: number,
        inputBufferSize: number,
        defaultTimeout: number): void;
    ${createBridge}(anotherDevice: IVirtualSerialDevice, permanent?: boolean): void;
    ${createRemoteBridge}(portName: string,
        serverName: string,
        permanent: boolean,
        login: string,
        password: string,
        domain: string): void;
    ${restoreDefaultPins}(): void;
    ${connectToFiles}(inputFile: string,
        outputFile: string,
        creationMode: ${FileCreationMode}): void;
}

public interface IVirtualSerialDevice
{
    // Properties
    ${VirtualSerialDeviceMode} ${mode} { get; }
    string ${path} { get; }
    bool ${deleted} { get; }
    string ${portName} { get; set; }
    ${IVirtualSerialLibrary} ${vLibrary} { get; }
    ulong ${connections} { get; }
    ulong ${bytesSent} { get; }
    ulong ${bytesReceived} { get; }
    bool ${enabled} { get; set; }
    double ${crossoverProbability} { get; set; }
    bool ${emulateTxOverflow} { get; set; }
    string ${securityDescriptor} { get; }
    string ${pipeName} { get; }
    ${IVirtualSerialDevice} ${pair} { get; }
    string ${remoteServer} { get; }
    string ${remotePort} { get; }
    string ${remoteEndpoint} { get; }
    ${ISocket} ${localSocket} { get; }
    ${ISocket} ${remoteSocket} { get; }
    string ${inputFileName} { get; }
    string ${outputFileName} { get; }

    // Methods
    void ${deleteDevice}();
    void ${disconnectDevice}();
    void ${startListening}(object securityDescriptor);
    void ${connectToPipe}(string pipeName);
    void ${createAndConnectPipe}(string pipeName,
        uint numberOfInstances,
        uint outputBufferSize,
        uint inputBufferSize,
        uint defaultTimeout);
    void ${createBridge}(IVirtualSerialDevice anotherDevice, bool permanent);
    void ${createRemoteBridge}(string portName,
        string serverName,
        bool permanent,
        string login,
        string password,
        string domain);
    void ${restoreDefaultPins}();
    void ${connectToFiles}(string inputFile,
        string outputFile,
        ${FileCreationMode} creationMode);
}

struct IVirtualSerialDevice : IDispatch
{
    // Properties
    ${VirtualSerialDeviceMode} ${mode};  // get 
    _bstr_t ${path};  // get 
    VARIANT_BOOL ${deleted};  // get 
    _bstr_t ${portName};  // get set 
    ${IVirtualSerialLibraryPtr#IVirtualSerialLibrary} ${vLibrary};  // get 
    unsigned long long ${connections};  // get 
    unsigned long long ${bytesSent};  // get 
    unsigned long long ${bytesReceived};  // get 
    VARIANT_BOOL ${enabled};  // get set 
    double ${crossoverProbability};  // get set 
    VARIANT_BOOL ${emulateTxOverflow};  // get set 
    _bstr_t ${securityDescriptor};  // get 
    _bstr_t ${pipeName};  // get 
    ${IVirtualSerialDevicePtr#IVirtualSerialDevice} ${pair};  // get 
    _bstr_t ${remoteServer};  // get 
    _bstr_t ${remotePort};  // get 
    _bstr_t ${remoteEndpoint};  // get 
    ${ISocketPtr#ISocket} ${localSocket};  // get 
    ${ISocketPtr#ISocket} ${remoteSocket};  // get 
    _bstr_t ${inputFileName};  // get 
    _bstr_t ${outputFileName};  // get 

    // Methods
    HRESULT ${deleteDevice}();
    HRESULT ${disconnectDevice}();
    HRESULT ${startListening}(const _variant_t & securityDescriptor);
    HRESULT ${connectToPipe}(_bstr_t pipeName);
    HRESULT ${createAndConnectPipe}(_bstr_t pipeName,
        unsigned long numberOfInstances,
        unsigned long outputBufferSize,
        unsigned long inputBufferSize,
        unsigned long defaultTimeout);
    HRESULT ${createBridge}(IVirtualSerialDevicePtr anotherDevice, VARIANT_BOOL permanent);
    HRESULT ${createRemoteBridge}(_bstr_t portName,
        _bstr_t serverName,
        VARIANT_BOOL permanent,
        _bstr_t login,
        _bstr_t password,
        _bstr_t domain);
    HRESULT ${restoreDefaultPins}();
    HRESULT ${connectToFiles}(_bstr_t inputFile,
        _bstr_t outputFile,
        ${FileCreationMode} creationMode);
};

IVirtualSerialDevice Properties

mode

readonly mode: ${VirtualSerialDeviceMode};

${VirtualSerialDeviceMode} mode { get; }

${VirtualSerialDeviceMode} mode;  // get

This property holds the current transport mode. Immediately after creation this property equals to VirtualSerialDeviceMode.Broken.

path

readonly path: string;

string path { get; }

_bstr_t path;  // get

Use this property to get a device's path. This string may be passed in a call to CreateFile API function in order to open a virtual serial port. All modern applications are supposed to use this device path instead of legacy COM port name.

deleted

readonly deleted: boolean;

bool deleted { get; }

VARIANT_BOOL deleted;  // get

This is the only property that may be checked after the call to deleteDevice method. In this case, this property is true. Otherwise, it is false.

portName

portName: string;

string portName { get; set; }

_bstr_t portName;  // get set

This read/write property holds the currently assigned COM port name and allows the client code to change it.

vLibrary

readonly vLibrary: ${IVirtualSerialLibrary};

${IVirtualSerialLibrary} vLibrary { get; }

${IVirtualSerialLibraryPtr#IVirtualSerialLibrary} vLibrary;  // get

Retrieve the reference to the library object.

connections

readonly connections: number;

ulong connections { get; }

unsigned long long connections;  // get

Total number of connections to the port.

bytesSent

readonly bytesSent: number;

ulong bytesSent { get; }

unsigned long long bytesSent;  // get

Total number of bytes sent through the port.

bytesReceived

readonly bytesReceived: number;

ulong bytesReceived { get; }

unsigned long long bytesReceived;  // get

Total number of bytes received from the port.

enabled

enabled: boolean;

bool enabled { get; set; }

VARIANT_BOOL enabled;  // get set

Allows the device to be enabled or disabled. Disabled devices cannot be opened.

crossoverProbability

crossoverProbability: number;

double crossoverProbability { get; set; }

double crossoverProbability;  // get set

Single bit crossover probability. May be a floating-point number between 0 and 0.5 (inclusive). Value 0 disables line noise emulation.

By default, Virtual Serial Ports does not emulate line noise. Change the value of this property to enable line noise emulation.

emulateTxOverflow

emulateTxOverflow: boolean;

bool emulateTxOverflow { get; set; }

VARIANT_BOOL emulateTxOverflow;  // get set

Turn emulation of output buffer overflow on or off.

By default, Virtual Serial Ports does not emulate output buffer overflow.

securityDescriptor

readonly securityDescriptor: string;

string securityDescriptor { get; }

_bstr_t securityDescriptor;  // get

String security descriptor associated with a listening port. See startListening method for more information.

pipeName

readonly pipeName: string;

string pipeName { get; }

_bstr_t pipeName;  // get

When device is connected to the Named Pipe Transport, this property holds the name of the pipe it is connected to. Note that on some operating systems this information may be unavailable.

pair

readonly pair: ${IVirtualSerialDevice};

${IVirtualSerialDevice} pair { get; }

${IVirtualSerialDevicePtr#IVirtualSerialDevice} pair;  // get

When virtual serial device is part of a local or remote bridge, you may use this property to determine the current device's pair, that is another virtual serial device it is bridged with.

Note that querying this property for remote bridges results in an exception.

remoteServer

readonly remoteServer: string;

string remoteServer { get; }

_bstr_t remoteServer;  // get

Name of the remote server on which other part of remote bridge resides. Generates exception if device is not part of a remote bridge.

remotePort

readonly remotePort: string;

string remotePort { get; }

_bstr_t remotePort;  // get

Port name on other side of the remote bridge. Generates exception if device is not part of remote bridge.

remoteEndpoint

readonly remoteEndpoint: string;

string remoteEndpoint { get; }

_bstr_t remoteEndpoint;  // get

Returns the user-friendly name of other side of the bridge or generates exception if device is not a part of a bridge. May be used with both local and remote bridges.

localSocket

readonly localSocket: ${ISocket};

${ISocket} localSocket { get; }

${ISocketPtr#ISocket} localSocket;  // get

Get this property to reference pins on the local part of a bridge.

You must use localSocket and remoteSocket properties of a single device object to configure pin-outs. Never use the value of pair property for that!

remoteSocket

readonly remoteSocket: ${ISocket};

${ISocket} remoteSocket { get; }

${ISocketPtr#ISocket} remoteSocket;  // get

Get this property to reference pins on the remote part of a bridge.

You must use localSocket and remoteSocket properties of a single device object to configure pin-outs. Never use the value of pair property for that!

inputFileName

readonly inputFileName: string;

string inputFileName { get; }

_bstr_t inputFileName;  // get

When virtual serial device is connected to Input/Output Files Transport, you may use this property to get the full path of the input file.

outputFileName

readonly outputFileName: string;

string outputFileName { get; }

_bstr_t outputFileName;  // get

When virtual serial device is connected to Input/Output Files Transport, you may use this property to get the full path of the output file.

IVirtualSerialDevice Methods

deleteDevice

deleteDevice(): void;

void deleteDevice();

HRESULT deleteDevice();

Deletes the virtual serial device. Device is actually deleted when all handles and references to it are closed or released. After calling this method, you may only release a reference. All other methods and properties (except deleted property) will return error codes after this method is called.

The calling application must have required privileges in order to be able to delete a device instance on the target computer for this method to work successfully. Otherwise, the “Access Denied” error is returned. When UAC is turned on, the calling application must have already elevated itself before calling this method.

It is allowed to call this method from 32-bit application on 64-bit operating system. In this case, the library uses a proxy to perform device deletion in the context of 64-bit process. This is performed transparently for the calling application. The same security and elevation requirements apply in this case.

disconnectDevice

disconnectDevice(): void;

void disconnectDevice();

HRESULT disconnectDevice();

Disconnects the device from any currently connected transport. After this method returns, the mode property equals VirtualSerialDeviceMode.Broken.

startListening

startListening(securityDescriptor?: string): void;

void startListening(object securityDescriptor);

HRESULT startListening(const _variant_t & securityDescriptor);

securityDescriptor: Listening security descriptor in SDDL format. See MSDN for more information on SDDL.

Prepares the port to receive remote bridge connections. Allows the client to specify the security descriptor via securityDescriptor parameter that governs access to the port. See MSDN for documentation on string security descriptor format.

Currently, the only access type is Connect, which code is 0x00000001.

connectToPipe

connectToPipe(pipeName: string): void;

void connectToPipe(string pipeName);

HRESULT connectToPipe(_bstr_t pipeName);

pipeName: Pipe name in form \\servername\pipe\pipename, where servername is either a host name, address or . for local computer.

Connect a virtual serial device to the specified named pipe (in client mode). The pipe's server may be on a local or remote computer. pipeName is the name of the pipe. See the MSDN for CreateFile function for the correct named pipe name syntax.

createAndConnectPipe

createAndConnectPipe(pipeName: string,
    numberOfInstances: number,
    outputBufferSize: number,
    inputBufferSize: number,
    defaultTimeout: number): void;

void createAndConnectPipe(string pipeName,
    uint numberOfInstances,
    uint outputBufferSize,
    uint inputBufferSize,
    uint defaultTimeout);

HRESULT createAndConnectPipe(_bstr_t pipeName,
    unsigned long numberOfInstances,
    unsigned long outputBufferSize,
    unsigned long inputBufferSize,
    unsigned long defaultTimeout);

pipeName: Pipe name in form \\.\pipe\pipename.
numberOfInstances: See MSDN for CreateNamedPipe function.
outputBufferSize: See MSDN for CreateNamedPipe function.
inputBufferSize: See MSDN for CreateNamedPipe function.
defaultTimeout: See MSDN for CreateNamedPipe function.

Creates a pipe and connects virtual serial port to this pipe.

createBridge

createBridge(anotherDevice: IVirtualSerialDevice, permanent?: boolean): void;

void createBridge(IVirtualSerialDevice anotherDevice, bool permanent);

HRESULT createBridge(IVirtualSerialDevicePtr anotherDevice, VARIANT_BOOL permanent);

anotherDevice: Reference to device on the “other” side of a bridge.
permanent: true or omit to create a permanent bridge (the one that will automatically be re-created after system reboot).

Bridge a virtual serial device with another. anotherDevice is a reference to other end of the bridge. Set permanent to true (or omit) to create a permanent bridge (the one that will automatically be recreated after system reboot).

createRemoteBridge

createRemoteBridge(portName: string,
    serverName: string,
    permanent: boolean,
    login: string,
    password: string,
    domain: string): void;

void createRemoteBridge(string portName,
    string serverName,
    bool permanent,
    string login,
    string password,
    string domain);

HRESULT createRemoteBridge(_bstr_t portName,
    _bstr_t serverName,
    VARIANT_BOOL permanent,
    _bstr_t login,
    _bstr_t password,
    _bstr_t domain);

portName: Remote port name.
serverName: Remote host name or address.
permanent: true to create permanent bridge. Permanent bridges are automatically re-created after system restart.
login: User name for authentication on remote server.
password: User password for authentication on remote server.
domain: Optional user domain for authentication on remote server.

Creates a remote bridge by establishing connection to remote port portName on serverName. A remote port must be in listening state and must grant connection access to the specified user.

If permanent is false, login, password and domain parameters may be empty strings. In this case, the calling user's credentials are used to establish connection.

If permanent is true, credentials must be explicitly specified. They are used to establish a connection and to re-establish it after the system is rebooted.

Credentials, if supplied, are stored in Registry in a secure way. If the stored credentials are copied to another machine, they cannot be decrypted. Stored credentials are associated with a device instance. Stored credentials are automatically removed from the Registry as soon as device is deleted.

restoreDefaultPins

restoreDefaultPins(): void;

void restoreDefaultPins();

HRESULT restoreDefaultPins();

Restores the default pin connections.

connectToFiles

connectToFiles(inputFile: string,
    outputFile: string,
    creationMode: ${FileCreationMode}): void;

void connectToFiles(string inputFile,
    string outputFile,
    ${FileCreationMode} creationMode);

HRESULT connectToFiles(_bstr_t inputFile,
    _bstr_t outputFile,
    ${FileCreationMode} creationMode);

inputFile: Full path to the input file.
outputFile: Full path to the output file.
creationMode: File creation or opening mode. See FileCreationMode enumeration for more information.

Connect to the given input (inputFile) and output (outputFile) files (see Input/Output Files Transport for more information). The library uses the supplied createParam value (see FileCreationMode enumeration for more information) to open the output file. After the output file is successfully opened, the library will start appending data to the end of the file.

VirtualSerialDeviceMode IVirtualSerialLibrary IVirtualSerialDevice ISocket FileCreationMode