VSPE API reference

VSPE API activation

To use VSPE API, you need an activation key.
You can order it on eterlogic.com web site or you can use FREE 32 bit key in the installation package.

Please note that Standard License does not give access to API on 64 bit platforms.

Please note that by default the activation key contains registration info: user name and company name.
Let us know if you do not want this information to be added when acquiring API key.

At the moment, there are two types of activation keys:

FREE 32 bit API key. Can be used for any purpose. To use it for FREE, place the link to https://eterlogic.com in the product documentation and your web site.
Commercial 32/64/ARM64 bit API key

There are 3 ways to activate VSPE API:

Use vspe_activate(key) function. Must be called every time your application runs.
Create 'vspeapi.license' file and paste your activation key. Place it in your application folder. Call vspe_activate("") - with empty string.
Create 'programdata%\Eterlogic\VSPE\vspeapi.license' file and paste your activation key. Call vspe_activate("").

Running API application (using COM interface) if VSPE is already installed

Stop VSPE service (EterlogicVspeDeviceManagerService)
Run your application

Required files

There are two ways to consume VSPE API: native dll linking and using COM interface (recommended). Check out VSPE_API folder for examples.

Linking with VSPE API (using VSPE_API.dll)

To compile with VSPE API, do the following steps:

Include VSPE_API.h (for C++ programmers)
Link with VSPE_API.lib

In some cases static linking will not work.
To use dynamic linking, look into MSDN documentation for LoadLibaray and GetProcAddress functions.

Dependencies with native binding (without COM interface)

To run your application, you should either install VSPE or copy the following files to your application folder:

VSPE_API.dll (VSPE API core)
VSPEUtils.dll (VSPE core)
EterlogicUtilities.dll (internal used by VSPE components)
Bridge.dll (internal used by VSPE components)

VSPE API will not work if VSPE service (EterlogicVspeDeviceManagerService) is running.
You should stop the service before running your application.

Dependencies for COM interface

Standalone installation

Install:

Add all the files mentioned in the sections above to your application setup package.
Run VspeInstall.exe driver_install with administrator privileges. This will install VSPE kernel driver.
(If needed): Register VSPE COM component (regsvr32 /s VSPE_ComServer.dll)

Uninstall:

Stop any applications/services which are using VSPE.
Run VspeInstall.exe driver_uninstall with administrator privileges. This will uninstall VSPE kernel driver.
(If needed): Unregister VSPE COM component (regsvr32 /u /s VSPE_ComServer.dll)

Running compiled program

Ensure that all required dependencies are located in your app folder (if you link to VSPE by referencing DLL).

Warning: Running VSPE application with VSPE API (or multiple VSPE_API instances) is not allowed. 
To start VSPE API application, you have to either uninstall VSPE or stop EterlogicVspeDeviceManagerService.

VSPE API header (VSPE_API.h)

// Virtual Serial Port Emulator API header
// https://www.eterlogic.com

#ifndef _VSPE_API_H_
#define _VSPE_API_H_

#ifdef VSPE_API_EXPORTS
#define VSPE_API extern "C" _declspec(dllexport) 
#else
#define VSPE_API extern "C" _declspec(dllimport)
#endif


/*
* Activate VSPE API using activation key
* \return result
*/
VSPE_API bool __cdecl vspe_activate(const char* key);

/*
* Get VSPE API activation erorr details
* \return result
*/
VSPE_API const char* __cdecl vspe_getActivationError();

/*
 * Initialize VSPE core
 * \return result
 */
VSPE_API bool __cdecl vspe_initialize();

/*
 * Load configuration file
 * \param name 
 * \return result
 */
VSPE_API bool __cdecl vspe_loadConfiguration(const char* name);

/*
 * Load configuration file
 * \param name
 * \return result
 */
VSPE_API bool __cdecl vspe_loadConfigurationW(const wchar_t* name);


/*
* Save configuration
* \param name 
* \return result
*/
VSPE_API bool __cdecl vspe_saveConfiguration(const char* name);

/*
* Save configuration
* \param name
* \return result
*/
VSPE_API bool __cdecl vspe_saveConfigurationW(const wchar_t* name);

/*
* Create device
* \param name Device name. For example "Connector", "Splitter", "Pair" etc.
* \param initString device initialization string
* \return deviceIndex
*/
VSPE_API int __cdecl vspe_createDevice(const char* name, const char* initString);

/*
* Destroy device by deviceIndex
* \param deviceIndex
* \return result
*/
VSPE_API bool __cdecl vspe_destroyDevice(int deviceIndex);


/*
* Get VSPE devices count
* \return result
*/
VSPE_API int __cdecl vspe_getDevicesCount();


/*
* Get VSPE deviceIndex by COM port index
* \param ComPortIdx
* \return deviceIndex (-1 if not found).
*/
VSPE_API int __cdecl vspe_getDeviceIndexByComPortIndex(int ComPortIdx);

/*
* Get device information
* \param deviceIndex
* \param name [out] device name
* \param initStirng [out] device initString
* \param ok [out] device state (1 = good)
* \param used [out] device clients count (0 - not used)
* \return result
*/
VSPE_API bool __cdecl vspe_getDeviceInfo(int deviceIndex, const char** name, const char** initString, int* ok, int* used);

/*
* Reinitialize device by deviceIndex
* \param deviceIndex
* \return result
*/
VSPE_API bool __cdecl vspe_reinitializeDevice(int deviceIndex);

/*
* Stop device by deviceIndex
* \param deviceIndex
* \return result
*/
VSPE_API bool __cdecl vspe_stopDevice(int deviceIndex);

/*
* Start device by deviceIndex
* \param deviceIndex
* \return result
*/
VSPE_API bool __cdecl vspe_startDevice(int deviceIndex);

/*
* Run maintenance routine which is applicable for some devices (automatic re-connect and re-start if needed)
*/
VSPE_API void __cdecl vspe_runMaintenanceRoutine();

/*
* Destroy all devices
* \return result
*/
VSPE_API bool __cdecl vspe_destroyAllDevices();


/*
 * Start emulation
 * \return result
 */
VSPE_API bool __cdecl vspe_startEmulation();

/*
 * Stop emulation
 * \return result
 */
VSPE_API bool __cdecl vspe_stopEmulation();

/*
 * Release VSPE core
 */
VSPE_API void __cdecl vspe_release();

/*
* Get VSPE API version information
* \return result
*/
VSPE_API const char* __cdecl vspe_getVersionInformation();

#endif

VSPE API COM interface (VSPE_ComServer.idl)

// Virtual Serial Port Emulator API header
// https://www.eterlogic.com


import "oaidl.idl";
import "ocidl.idl";


[
    object,
    uuid(4350205d-80d8-429e-ac0c-0fc64dc42180),
    dual,
    nonextensible,
    helpstring("IVSPE Interface"),
    pointer_default(unique)
]

// ========================================================================
// Main VSPE interface
// ========================================================================
interface IVSPE : IDispatch
{

    /*
    * Activate VSPE API using activation key
    * \param key Activation key
    * \return result
    */
    [id(1), helpstring("method vspe_activate")] HRESULT vspe_activate([in] BSTR key, [out, retval] BOOL* result);

    /*
    * Initialize VSPE core
    * \return result
    */
    [id(2), helpstring("method vspe_initialize")] HRESULT vspe_initialize([out, retval] BOOL* result);

    /*
    * Load configuration file
    * \param name 
    * \return result
    */
    [id(3), helpstring("method vspe_loadConfiguration")] HRESULT vspe_loadConfiguration([in] BSTR name, [out, retval] BOOL* result);

    /*
    * Save configuration
    * \param name 
    * \return result
    */
    [id(4), helpstring("method vspe_saveConfiguration")] HRESULT vspe_saveConfiguration([in] BSTR name, [out, retval] BOOL* result);

    /*
    * Create device
    * \param name Device name. For example "Connector", "Splitter", "Pair" etc.
    * \param initString device initialization string
    * \return deviceIndex
    */
    [id(5), helpstring("method vspe_createDevice")] HRESULT vspe_createDevice([in] BSTR name, [in] BSTR initString, [out, retval] BOOL* result);

    /*
    * Destroy device
    * \param deviceIndex
    * \return result
    */
    [id(6), helpstring("method vspe_destroyDevice")] HRESULT vspe_destroyDevice([in] LONG deviceIndex, [out, retval] BOOL* result);

    /*
    * Reinitialize device
    * \param deviceIndex
    * \return result
    */
    [id(7), helpstring("method vspe_reinitializeDevice")] HRESULT vspe_reinitializeDevice([in] LONG deviceIndex, [out, retval] BOOL* result);

    /*
    * Destroy all devices
    * \return result
    */
    [id(8), helpstring("method vspe_destroyAllDevices")] HRESULT vspe_destroyAllDevices([out, retval] BOOL* result);

    /*
    * Start emulation
    * \return result
    */
    [id(9), helpstring("method vspe_startEmulation")] HRESULT vspe_startEmulation([out, retval] BOOL* result);

    /*
    * Stop emulation
    * \return result
    */
    [id(10), helpstring("method vspe_stopEmulation")] HRESULT vspe_stopEmulation([out, retval] BOOL* result);

    /*
    * Release VSPE core
    */
    [id(11), helpstring("method vspe_release")] HRESULT vspe_release();

    /*
    * Get VSPE devices count
    * \return result
    */
    [id(12), helpstring("method vspe_getDevicesCount")] HRESULT vspe_getDevicesCount([out, retval] LONG* result);

    /*
    * Get device information
    * \param deviceIndex
    * \param name [out] device name
    * \param initString [out] device initString
    * \param ok [out] device state (1 = good)
    * \param used [out] device clients count (0 - not used)
    * \return result
    */
    [id(13), helpstring("method vspe_getDeviceInfo")] HRESULT vspe_getDeviceInfo([in] LONG deviceIndex, [out] BSTR* name, [out] BSTR* initString, [out] LONG* ok, [out] LONG* used, [out, retval] BOOL* result);

    /*
    * Get VSPE API version information
    * \return result
    */
    [id(14), helpstring("method vspe_getVersionInformation")] HRESULT vspe_getVersionInformation([out, retval] BSTR* result);


    /*
    * Get VSPE deviceIndex by COM port index
    * \param ComPortIdx
    * \return deviceIndex (-1 if not found).
    */
    [id(15), helpstring("method vspe_getDeviceIndexByComPortIndex")] HRESULT vspe_getDeviceIndexByComPortIndex([in] LONG ComPortIdx, [out, retval] LONG* result);

    /*
    * Get activation error message
    * \return result
    */
    [id(16), helpstring("method vspe_getActivationError")] HRESULT vspe_getActivationError([out, retval] BSTR* result);

    /*
    * Stop device
    * \param deviceIndex
    * \return result
    */
    [id(17), helpstring("method vspe_reinitializeDevice")] HRESULT vspe_stopDevice([in] LONG deviceIndex, [out, retval] BOOL* result);

    /*
    * Reinitialize device
    * \param deviceIndex
    * \return result
    */
    [id(18), helpstring("method vspe_reinitializeDevice")] HRESULT vspe_startDevice([in] LONG deviceIndex, [out, retval] BOOL* result);

    /*
    * Run maintenance routine which is applicable for some devices (automatic re-connect and re-start if needed)
    */
    [id(19), helpstring("method vspe_runMaintenanceRoutine")] HRESULT vspe_runMaintenanceRoutine();
};



[
    uuid(d7cd1ef7-a520-457b-af9a-8ea103b95381),
    version(2.0),
    helpstring("VSPE 2.0 Type Library")
]

library VSPELib
{
    // ========================================================================
    // Interface implementations
    // ========================================================================
    [
        uuid(bf32160d-8fa7-408b-8a3c-cbfbfc19caa6),
        helpstring("VSPEApi Class")
    ]
    coclass VSPEApi
    {
        [default] interface IVSPE;
    };

};