API Overview

Virtual Serial Port Tools installs an in-process COM server providing full-featured API to native, .NET or scripting clients. This documentation section describes the provided API in detail.

Any user code that intends to call any API method or use any API interface must have sufficient rights on the local computer. This means at least SeLoadDriverPrivilege privilege must be granted to the calling process and usually also means that the caller needs to be running elevated.

Using from Native Code

In order to use the API in native code, include the supplied header files:

#include "clientctl.tlh"
#include "clientctl.tli"

These files are pre-installed in the %INSTALLDIR%\api\native folder.

After that you can use all library classes and interfaces. For example, to create an instance of the library object and then create a new alias virtual serial port, use the following code:

hhdvspkit::ISerialPortLibraryPtr pLibrary;
if (SUCCEEDED(pLibrary.CreateInstance(__uuidof(hhdvspkit::SerialPortLibrary))))
{
      // create new alias virtual serial port with automatically-assigned port name
      auto pNewPort = pLibrary->${createAliasPort}();   
      // configure created port
      pNewPort1->put_${aliasPort} = 1;
      // ...
}

Using from C#

In order to use the library from C# project, add a reference to the supplied hhdvspkit.interop.dll file to your project in Microsoft Visual Studio. The file is pre-installed in the %INSTALLDIR%\api\interop folder.

Use the API provided by the library:

var library = new hhdvspkit.${SerialPortLibrary#ISerialPortLibrary}();
var port = library.${createAliasPort}();
port.${aliasPort} = 1;
// ...

Adding a reference to hhdvspkit.dll in Visual Studio generates an interop DLL that exposes .NET wrappers for native code provided by the COM server. You can also add a reference to the included hhdvspkit.interop.dll, which is a pre-generated version of the interop DLL.

Using from JavaScript

To create an instance of the library, use the following code:

var library = new ActiveXObject("hhdvspkit.SerialPortLibrary.4");

Then, use the library object to create and manage virtual serial devices:

// create new virtual serial port
var port = library.${createAliasPort}();
// configure serial port
port.${aliasPort} = 1;
// ...

Using from TypeScript

Virtual Serial Port Tools library contains TypeScript definition file that simplifies library usage in scripting environments. It automatically gives you method parameter type validation and simplifies specifying callback methods.

///<reference path="hhdvspkit.d.ts" />
var library = (${ISerialPortLibrary}) new ActiveXObject("hhdvspkit.SerialPortLibrary.4");
// create new virtual serial port with automatically-assigned port name
var port = library.${createAliasPort}();
// configure port
port.${aliasPort} = 1;
// ...

Legacy API

Virtual Serial Port Tools incorporated the previous HHD Software product, Virtual Serial Ports. Virtual Serial Ports code is almost untouched in the current version and, therefore, original VSP API is also almost unchanged.

We plan to finally incorporate the VSP API into VSPT API described above, but currently in order to create local or remote bridges, pipe-connected ports or listening ports, the following interfaces should be used instead:

Note that a separate library exists for legacy devices.

ISerialPortLibrary createAliasPort aliasPort