Virtual Serial Ports - Software Virtual COM Port Null Modem Cable Emulator for Windows
Docs

IVirtualSerialLibrary Interface

interface IVirtualSerialLibrary {
    // Properties
    readonly ${devicesArray}: ${IVirtualSerialDevice}[];
    // Methods
    ${createDevice}(portName?: string | number): ${IVirtualSerialDevice};
    ${installLicenseFile}(path: string): void;
    ${displayActivationDialog}(window?: number): void;
    ${dispatchEvents}(keepAlive: () => boolean, intervalMs: number): void;
    ${stopEventDispatching}(): void;
    // Events
    ${added}(handler: (devices: ${IVirtualSerialDevice}[]) => void): number;
    ${added}(eventId: number): void;
    ${deleted}(handler: (devices: ${IVirtualSerialDevice}[]) => void): number;
    ${deleted}(eventId: number): void;
    ${changed}(handler: (device: ${IVirtualSerialDevice}, changed: ${ChangeMode}) => void): number;
    ${changed}(eventId: number): void;
}
public interface IVirtualSerialLibrary
{
    // Properties
    ${IDeviceCollection} ${devicesCollection} { get; }
    // Methods
    ${IVirtualSerialDevice} ${createDevice}(object portName);
    void ${installLicenseFile}(string path);
    void ${installLicense}(uint size, ref byte data);
    void ${displayActivationDialog}(object window);
    void ${addListener}(${IVirtualSerialLibraryListener} listener);
    void ${removeListener}(${IVirtualSerialLibraryListener} listener);
}
struct IVirtualSerialLibrary : IDispatch
{
    // Properties
    ${IDeviceCollectionPtr#IDeviceCollection} ${devicesCollection};  // get 
    // Methods
    ${IVirtualSerialDevicePtr#IVirtualSerialDevice} ${createDevice}(const _variant_t & portName);
    HRESULT ${installLicenseFile}(_bstr_t path);
    HRESULT ${installLicense}(unsigned long size, unsigned char * data);
    HRESULT ${displayActivationDialog}(const _variant_t & window);
    HRESULT ${addListener}(${IVirtualSerialLibraryListener} * listener);
    HRESULT ${removeListener}(${IVirtualSerialLibraryListener} * listener);
};

IVirtualSerialLibrary Properties

devicesArray

readonly devicesArray: ${IVirtualSerialDevice}[];
// This property is not available in managed environment
// This property is not available in native environment

This property holds an array of all created virtual serial devices. This property is available only for scripting clients.

devicesCollection

// This property is not available in scripting environment
${IDeviceCollection} devicesCollection { get; }
${IDeviceCollectionPtr#IDeviceCollection} devicesCollection;  // get 

This property holds a collection of all created virtual serial devices. This property is available only for native clients.

IVirtualSerialLibrary Methods

createDevice

createDevice(portName?: string | number): ${IVirtualSerialDevice};
${IVirtualSerialDevice} createDevice(object portName);
${IVirtualSerialDevicePtr#IVirtualSerialDevice} createDevice(const _variant_t & portName);
portName
Port number or a string in the form "COMn". If the requested port is taken, an error code is returned. If omitted, a next available port will be selected automatically.

This method creates new unconnected virtual serial device. This device should be later connected to one of the transports in order to be used.

When last reference to the device is released, the device is not deleted. To delete a device, call IVirtualSerialDevice.deleteDevice method and then release a reference.

The calling application must have required privileges in order to be able to create 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 creation 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.

Native only: This method returns S_OK if device has been successfully created, S_FALSE if device has been created, but restart is required to complete installation. Otherwise, standard COM error code is returned.

installLicenseFile

installLicenseFile(path: string): void;
void installLicenseFile(string path);
HRESULT installLicenseFile(_bstr_t path);
path
Full path to the license file.

Installs a license from a file which location is specified by path parameter.

installLicense

// This method is not available in scripting environment
void installLicense(uint size, ref byte data);
HRESULT installLicense(unsigned long size, unsigned char * data);
size
Size of a memory block, in bytes.
data
Pointer to the first byte of license data in memory.

Installs a license from a memory block. This method is available for native clients only.

displayActivationDialog

displayActivationDialog(window?: number): void;
void displayActivationDialog(object window);
HRESULT displayActivationDialog(const _variant_t & window);
window
Window handle.

Installs a license by displaying an activation dialog and letting the user to select the location of a license file. Optional window parameter must be a window handle.

addListener

// This method is not available in scripting environment
void addListener(${IVirtualSerialLibraryListener} listener);
HRESULT addListener(${IVirtualSerialLibraryListener} * listener);
listener
A reference to the listener object.

Adds new listener object to the library.

removeListener

// This method is not available in scripting environment
void removeListener(${IVirtualSerialLibraryListener} listener);
HRESULT removeListener(${IVirtualSerialLibraryListener} * listener);
listener
A reference to the listener object.

Removes an object from the library.

dispatchEvents

dispatchEvents(keepAlive: () => boolean, intervalMs: number): void;
// This method is not available in managed environment
// This method is not available in native environment
keepAlive
Callback function to be invoked at intervalMs intervals. If callback function returns false, execution of dispatchEvents terminates and function returns. Otherwise, events dispatching continues.
intervalMs
An interval, in milliseconds, to call user callback function keepAlive.

When using library from scripting environments (browser or Windows Scripting Host) it is required to call this method to be able to receive events fired by the library. If client code does not subscribe to any events, calling this method is not required.

Client code may also call stopEventDispatching from any of event handlers to terminate the call.

This method is intended for scripting clients.

stopEventDispatching

stopEventDispatching(): void;
// This method is not available in managed environment
// This method is not available in native environment

Client code may call this method from any event handler to stop the pending dispatchEvents call.

IVirtualSerialLibrary Events

added

added(handler: (devices: ${IVirtualSerialDevice}[]) => void): number;
added(eventId: number): void;

devices
An array of new device objects.

This event is fired when new virtual serial device(s) appear on the system.

deleted

deleted(handler: (devices: ${IVirtualSerialDevice}[]) => void): number;
deleted(eventId: number): void;

devices
An array of deleted device objects.

This event is fired when virtual serial device(s) are deleted from the system.

changed

changed(handler: (device: ${IVirtualSerialDevice}, changed: ${ChangeMode}) => void): number;
changed(eventId: number): void;

device
Device which state has been changed.
changed
Indicates what has changed.

This event is fired when virtual serial device referenced by device parameter state is changed. The new state is specified by changed parameter.