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.

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 www.eterlogic.com in the product documentation and your web site.
• Commercial 32/64 bit API key. Gives ability to work in 64 bit environment. VSPE API can simultaneously work with VSPE or other applications consuming VSPE_API (with different vendor id).

There are two ways to activate VSPE API. Both ways are correct.

• 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. vspe_activate still needs to be called, but you can provide empty string and the key file will be loaded.

Required files

There are two ways of using VSPE API: native dll linking and COM interface. 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 in MSDN for 
LoadLibaray and GetProcAddress functions.

Dependencies with native binding (without COM interface)

To run your application without correctly, you should either install VSPE or copy the following files to your application folder: All devices (kernel and user):

• Vspe_Api.dll (VSPE API core)
• VspeUtils.dll (VSPE core)
• KernelDevices.plg (Connector, Splitter, Pair, Mapper)
• UserDevices.plg (TcpServer, TcpClient etc)
• KrushUtilities.dll (helper dll used by multiple components)

Kernel devices only (splitter, connector, pair, mapper)

• Vspe_Api.dll (VSPE API core)
• VspeUtils.dll (VSPE core)
• KernelDevices.plg (Connector, Splitter, Pair, Mapper)

Dependencies with native binding (without COM interface)

• Register VSPE_ComServer.dll (regsvr32 VSPE_ComServer.dll). No any additional files in the application folder required. Please note that 32/64 bit COM interfaces should be registered separately - use corresponding components from 32 and 64 bit installer packages.

Standalone installation

Installation

• Add all the files mentioned in the sections above to your application setup package.
• Run WixInteractor.exe on_install with administrator privileges
• Register VSPE_ComServer.dll (regsvr32 VSPE_ComServer.dll)

Uninstallation

• Run WixInteractor.exe on_uninstall with administrator privileges
• Unregister VSPE_ComServer.dll (regsvr32 /u VSPE_ComServer.dll)

Additional uninstallation steps for 64 bit VSPE_API license with unique vendor ID If you are using 64 bit VSPE API license, you have unique vendor id. It means that you are responsible to unregister kernel driver with your unique vendor suffix.

• You should check 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EterlogicVirtualSerialDriverXXXXX' key where XXXXX is your unique vendor id.
• Stop the service (sc.exe stop EterlogicVirtualSerialDriverXXXXX)
• Delete the service (sc.exe delete EterlogicVirtualSerialDriverXXXXX)
• Delete corresponding kernel driver file (\Windows\System32\drivers\VSPEXXXXX.sys)

Settings folder. All settings are stored in 'localappdata%\Eterlogic\VSPE' folder:

• VSPE.log: log file for VSPE or VSPE API startup
• VSPE.ini: settings file for VSPE application
• VSPE.license: license key used by VSPE application

Running compiled program

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

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 char* __cdecl vspe_get_activation_error();

/*
 * 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);


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


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

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


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


/*
* Get VSPE deviceId by device index
* \param idx device index
* \return deviceId
*/
VSPE_API int __cdecl vspe_getDeviceIdByIdx(int idx);

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

/*
* Get device information
* \param deviceId
* \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 deviceId, const char** name, const char** initString, int* ok, int* used);

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

/*
* 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
// http://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 deviceId
    */
    [id(5), helpstring("method vspe_createDevice")] HRESULT vspe_createDevice([in] BSTR name, [in] BSTR initString, [out, retval] BOOL* Result);

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

    /*
    * Reinitialize device
    * \param deviceId
    * \return result
    */
    [id(7), helpstring("method vspe_reinitializeDevice")] HRESULT vspe_reinitializeDevice([in] LONG deviceId, [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 VSPE deviceId by device index
    * \param idx device index
    * \return deviceId
    */
    [id(13), helpstring("method vspe_getDeviceIdByIdx")] HRESULT vspe_getDeviceIdByIdx([in] LONG idx, [out, retval] LONG* Result);

    /*
    * Get device information
    * \param deviceId
    * \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(14), helpstring("method vspe_getDeviceInfo")] HRESULT vspe_getDeviceInfo([in] LONG deviceId, [out] BSTR* name, [out] BSTR* initString, [out] LONG* ok, [out] LONG* used, [out, retval] BOOL* Result);

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


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

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



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

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

};