The DLL API

Parent Previous Next

The DLL API.

The API functions are designed to be simple to use and only involves simple standard types supported by most programming languages and compilers.


In order to facilitate easy adaption, all API functions are duplicated and exist in two (twin) versions:


It is important to link to the appropriate function in order to pass arguments using the correct calling convention. It is simple to distinguish the functions by their name, because if a function in group 1 is named "ABC" then the same function in group 2 is named "ABC_cdecl".


Selecting an appropriate calling convention is less relevant for 64 bit Windows applications, however the 64 bit VM DLL provides the same two groups of functions and respective naming conventions to allow for easy reuse of source code across multiple platforms.


The Involved Types.

Almost all parameters or return values are based on either 32 bit integers, or pointers to a byte (to pass byte-arrays).


The only two exceptions are:


Below you will find all the functions and their argument signatures. When in doubt it can be beneficial to compare the two definitions of the same function - e.g. comparing VMFree and VMFree_cdecl. Please also notice that the description of a given function "ABC" from group 1 is also applicable for the "ABC_cdecl" (twin) function in group 2 - the functionality does not differ - only the calling convention differs.


The API for Stdcall.

All the functions of group 1 for the stdcall convention are listed here in Pascal syntax:



//Please note that in Pascal:

// - Parameters are default passed by value.

// - A var specified parameter is passed by reference.

// - PByte points to the first byte of a byte-array.

function CompilerVersion() : int32;

function MultiThreadMode(mode : int32) : TBoolInt;

function LastErrorGetStringLength(codePage : int32; var len : int32) : TBoolInt;

function LastErrorGetString(codePage, len : int32; textbytes : PByte) : TBoolInt;

function VMCreate(codePage, len : int32; asmByteCode : PByte; var vm : int32) : TBoolInt;

function VMFree(vm : int32) : TBoolInt;

function VMSetCallback(vm : int32; callBack : TCallBack) : TBoolInt;

function VMGC(vm : int32; gcMainClass : TBoolInt) : TBoolInt;

function VMExecute(vm, x, y, z : int32; var returnValue : int32) : TBoolInt;

function VMClearCells(vm : int32) : TBoolInt;

function VMCellIsInteger(vm, row, col : int32; var returnValue : TBoolInt) : TBoolInt;

function VMCellIsBytes(vm, row, col : int32; var returnValue : TBoolInt) : TBoolInt;

function VMCellIsString(vm, row, col : int32; var returnValue : TBoolInt) : TBoolInt;

function VMCellGetInteger(vm, row, col : int32; var returnValue : int32) : TBoolInt;

function VMCellGetBytesLength(vm, row, col : int32; var len : int32) : TBoolInt;

function VMCellGetBytes(vm, row, col, len : int32; bytes : PByte) : TBoolInt;

function VMCellGetStringLength(vm, row, col, codePage : int32; var len : int32) : TBoolInt;

function VMCellGetString(vm, row, col, codePage, len : int32; textbytes : PByte) : TBoolInt;

function VMCellSetInteger(vm, row, col, value : int32) : TBoolInt;

function VMCellSetBytes(vm, row, col, len : int32; bytes : PByte) : TBoolInt;

function VMCellSetString(vm, row, col, codePage, len : int32; textbytes : PByte) : TBoolInt;



The API for Cdecl.

All the functions of group 2 for the cdecl convention are listed here in C/C++ syntax:



int CompilerVersion_cdecl();

TBoolInt MultiThreadMode_cdecl(int mode);

TBoolInt LastErrorGetStringLength_cdecl(int codePage, int& len);

TBoolInt LastErrorGetString_cdecl(int codePage, int len, unsigned char* textbytes);

TBoolInt VMCreate_cdecl(int codePage, int len, unsigned char* asmByteCode, int& vm);

TBoolInt VMFree_cdecl(int vm);

TBoolInt VMSetCallback_cdecl(int vm, int (*callBack)(int,int,int));

TBoolInt VMGC_cdecl(int vm, TBoolInt gcMainClass);

TBoolInt VMExecute_cdecl(int vm, int x, int y, int z, int& returnValue);

TBoolInt VMClearCells_cdecl(int vm);

TBoolInt VMCellIsInteger_cdecl(int vm, int row, int col, TBoolInt& returnValue);

TBoolInt VMCellIsBytes_cdecl(int vm, int row, int col, TBoolInt& returnValue);

TBoolInt VMCellIsString_cdecl(int vm, int row, int col, TBoolInt& returnValue);

TBoolInt VMCellGetInteger_cdecl(int vm, int row, int col, int& returnValue);

TBoolInt VMCellGetBytesLength_cdecl(int vm, int row, int col, int& len);

TBoolInt VMCellGetBytes_cdecl(int vm, int row, int col, int len, unsigned char* bytes);

TBoolInt VMCellGetStringLength_cdecl(int vm, int row, int col, int codePage, int& len);

TBoolInt VMCellGetString_cdecl(int vm, int row, int col, int codePage, int len, unsigned char* textbytes);

TBoolInt VMCellSetInteger_cdecl(int vm, int row, int col, int value);

TBoolInt VMCellSetBytes_cdecl(int vm, int row, int col, int len, unsigned char* bytes);

TBoolInt VMCellSetString_cdecl(int vm, int row, int col, int codePage, int len, unsigned char* textbytes);



Function Results.

The function CompilerVersion() is a bit special. It returns a 32 bit integer value for the required version of the compiler.


However, the rest of the functions all return a TBoolInt value (32 bit integer), which is either 1 or 0. A function returns 1 to indicate that no errors occurred and the task was completed. When a function returns 0 some kind of error occurred.


If an error occurs the two functions LastErrorGetStringLength and LastErrorGetString can be used to get the last occurred internal error message.

Important: Do not invoke any of the other functions, as these may clear or overwrite the last reported error.


Parameters.

These are the parameters used - listed in alphabetic order:


Please note:


Memory Management.

It is always the caller that owns and is responsible for the memory management of the passed values.


This is especially evident for the host application in case a byte-array must be returned from the VM DLL.

In that case it is necessary for the host to:


It is imperative to understand, that the VM DLL must be correctly informed about the length of a passed byte-array or else the VM DLL may illegally use or overwrite memory, causing errors or unpredictable results.