AlluVision Inc. Home

vm48400_win32 - Virtual Machine library, API document


Index

Error codes
Variant
Handle types
Functions
Examples

Error codes

#define APPL_ERROR						0x20000000

#define VME_NONE						(APPL_ERROR + 0)
#define VME_OUT_OF_MEMORY					(APPL_ERROR + 1)
#define VME_CANT_OPEN_FILE					(APPL_ERROR + 2)
#define VME_FILE_READ_ERROR					(APPL_ERROR + 3)
#define VME_SYNTAX_ERROR					(APPL_ERROR + 4)
#define VME_UNKNOWN_OBJECT_TYPE				(APPL_ERROR + 5)
#define VME_CANT_CREATE_DIRECTORY_SCANNER			(APPL_ERROR + 6)
#define VME_REWIND_DIRECTORY_SCANNER_FAILED			(APPL_ERROR + 7)
#define VME_DIRECTORY_SCAN_FAILED				(APPL_ERROR + 8)
#define VME_OBJECT_NOT_FOUND				(APPL_ERROR + 9)
#define VME_CANT_OPEN_OBJECT				(APPL_ERROR + 10)
#define VME_INVALID_USER_REFERENCE_SIZE			(APPL_ERROR + 11)
#define VME_USER_REFERENCE_NOT_FOUND				(APPL_ERROR + 12)
#define VME_NO_STARTUP_DEFINED				(APPL_ERROR + 13)
#define VME_NO_STACK_DEFINED				(APPL_ERROR + 14)
#define VME_CANT_GET_RETURN_VALUE				(APPL_ERROR + 15)
#define VME_INVALID_REFERENCE_TYPE				(APPL_ERROR + 16)
#define VME_UNSPECIFIED_ERROR				(APPL_ERROR + 100)

Error codes explained:
  • VME_NONE, no errors. Typically the library will not store this error code with the SetLastError() function.
  • VME_OUT_OF_MEMORY, the system returned NULL instead of memory chunk.
  • VME_CANT_OPEN_FILE, the library couldn't open the .ini file.
  • VME_FILE_READ_ERROR, error occurred during the reading of the .ini file.
  • VME_SYNTAX_ERROR, .ini file parser couldn't parse the .ini file.
  • VME_UNKNOWN_OBJECT_TYPE, type of the object file not an executable nor library.
  • VME_CANT_CREATE_DIRECTORY_SCANNER, the library couldn't create the directory scanner object. This is typically due to out of memory condition.
  • VME_REWIND_DIRECTORY_SCANNER_FAILED, the library couldn't rewind the directory scanner object. This is typically due to out of memory condition.
  • VME_DIRECTORY_SCAN_FAILED, the library couldn't scan the directory. This is typically due to out of memory condition.
  • VME_OBJECT_NOT_FOUND, the library did scan the directories, but the specified object was not found.
  • VME_CANT_OPEN_OBJECT, the object file was found, but the file open failed.
  • VME_INVALID_USER_REFERENCE_SIZE, user reference size can only be either 1, 2 or 4 bytes.
  • VME_USER_REFERENCE_NOT_FOUND, name of the user reference was not exported in the object file.
  • VME_NO_STARTUP_DEFINED, tried to run the object but there were no startup address defined.
  • VME_NO_STACK_DEFINED, tried to run the object but there were no stack defined.
  • VME_CANT_GET_RETURN_VALUE, tried to retrieve return value with the invalid variant type or there is no return value available.
  • VME_INVALID_REFERENCE_TYPE, specified invalid reference variant type.
  • VME_UNSPECIFIED_ERROR, some other error. Shouldn't happen.

Variant

Variant object is used to define the parameter lists. vmVariantType, which specifies the type of the variant's value, is also used to define the return value of the external function.

vmVariantType

vmVariantType enumerates the different variant types.
typedef enum __vmVariantType
{
	vmVariantTypeVoid,
	vmVariantTypeChar,
	vmVariantTypeShort,
	vmVariantTypeLong,
	vmVariantTypeLongLong,
	vmVariantTypeFloat,
	vmVariantTypeDouble,
	vmVariantTypeLongDouble
}vmVariantType;

vmTypeChar

8-bit datatype
typedef char vmTypeChar;

vmTypeShort

16-bit datatype
typedef short vmTypeShort;

vmTypeLong

32-bit datatype. Also pointers are of this type.
typedef long vmTypeLong;

vmTypeLongLong

64-bit datatype
typedef __int64 vmTypeLongLong;

vmTypeFloat

Single precision floating point datatype
typedef float vmTypeFloat;

vmTypeDouble

Double precision floating point datatype
typedef double vmTypeDouble;

vmTypeLongDouble

Extended precision floating point datatype. Currently implemented in double precision.
typedef double vmTypeLongDouble;

vmVariantValue

vmVariantValue union holds the value of the variant.
typedef union __vmVariantValue
{
	vmTypeChar Char;
	vmTypeShort Short;
	vmTypeLong Long;
	vmTypeLongLong LongLong;
	vmTypeFloat Float;
	vmTypeDouble Double;
	vmTypeLongDouble LongDouble;
}vmVariantValue;

vmVariant, vmVariantHandle

vmVariant object can hold many different kind of data types, althought not on the same time. vmVariantHandle is a pointer to vmVariant type.
typedef struct __vmVariant
{
	vmVariantType Type;
	vmVariantValue Value;
}vmVariant, *vmVariantHandle;

Handle types

Internal data structures of the library are hidden from the interface. Therefore data types used in the interface are effectively pointers to nothing(void *).

vmListHandle

vmList object is used to store external functions(references), labels in the objects and in the parameter passing.
typedef void *vmListHandle;

vmReferenceHandle

vmReference object is used to introduce external functions(or variables) for the object file. The object loader will link to reference addresses during the load phase.
typedef void *vmReferenceHandle;

vmLabelHandle

vmLabel object is used to retrieve addresses in the object file. The object file loader will store label addresses after resolving the object file.
typedef void *vmLabelHandle;

vmObjectHandle

vmObject object is used to hold the loaded object file.
typedef void *vmObjectHandle;

vmStdArgHandle

vmStdArg object is used to define standard arguments. This will work only if the startup of the object file is declared like this: int main(int argc, char **argv);, except, the name of the startup function doesn't have to be 'main'.
typedef void *vmStdArgHandle;

Functions

vmCreateList
vmDeleteList
vmAddToList
vmCreateVariant
vmCreateVariantChar
vmCreateVariantShort
vmCreateVariantLong
vmCreateVariantLongLong
vmCreateVariantFloat
vmCreateVariantDouble
vmCreateVariantLongDouble
vmDeleteVariant
vmCreateReference
vmDeleteReference
vmCreateLabel
vmDeleteLabel
vmCreateStdArg
vmAddStringToStdArg
vmDeleteStdArg
vmConvertStdArgToList
vmLoadExecutable
vmDeleteObject
vmRun
vmReturnValue

vmCreateList

The vmCreateList function allocates the new vmList object.
#include "vm48400_win32.h"

vmListHandle vmCreateList(void);
Parameters
None

Return value
If the function succeeds, the return value is a handle to the new vmList object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmListHandle, vmDeleteList, vmAddToList

vmDeleteList

The vmDeleteList function frees the vmList object.
#include "vm48400_win32.h"

void vmDeleteList(
	vmListHandle List		// handle of the vmList object
);
Parameters
  • List, handle of the vmList object.

Return value
None

See also
vmListHandle, vmCreateList, vmAddToList

vmAddToList

The vmAddToList function creates a new node to the list.
#include "vm48400_win32.h"

BOOL vmAddToList(
	vmListHandle List,		// handle of the vmList object
	LPCSTR Name,		// optional name of the node
	LPCVOID PayLoad		// optional pointer to the payload
);
Parameters
  • List, handle of the vmList object.
  • Name, optional name of the node. If other than NULL, the string will be duplicated.
  • Payload, optional pointer to the payload.

Return value
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See also
vmListHandle, vmCreateList, vmDeleteList

vmCreateVariant

The vmCreateVariant function allocates the new vmVariant object.
#include "vm48400_win32.h"

vmVariantHandle vmCreateVariant(void);
Parameters
None

Return value
If the function succeeds, the return value is a handle to the new vmVariant object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmVariantHandle, vmCreateVariantChar, vmCreateVariantShort, vmCreateVariantLong, vmCreateVariantLongLong, vmCreateVariantFloat, vmCreateVariantDouble, vmCreateVariantLongDouble, vmDeleteVariant,

vmCreateVariantChar

The vmCreateVariantChar function allocates the new vmVariant object.
#include "vm48400_win32.h"

vmVariantHandle vmCreateVariantChar(
	vmTypeChar Char		// value to be stored to the variant
);
Parameters
  • Char, value of type vmTypeChar to be stored to the vmVariant object.
Return value
If the function succeeds, the return value is a handle to the new vmVariant object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmVariantHandle, vmCreateVariant, vmCreateVariantShort, vmCreateVariantLong, vmCreateVariantLongLong, vmCreateVariantFloat, vmCreateVariantDouble, vmCreateVariantLongDouble, vmDeleteVariant,

vmCreateVariantShort

The vmCreateVariantShort function allocates the new vmVariant object.
#include "vm48400_win32.h"

vmVariantHandle vmCreateVariantShort(
	vmTypeShort Short		// value to be stored to the variant
);
Parameters
  • Short, value of type vmTypeShort to be stored to the vmVariant object.
Return value
If the function succeeds, the return value is a handle to the new vmVariant object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmVariantHandle, vmCreateVariant, vmCreateVariantChar, vmCreateVariantLong, vmCreateVariantLongLong, vmCreateVariantFloat, vmCreateVariantDouble, vmCreateVariantLongDouble, vmDeleteVariant,

vmCreateVariantLong

The vmCreateVariantLong function allocates the new vmVariant object.
#include "vm48400_win32.h"

vmVariantHandle vmCreateVariantLong(
	vmTypeLong Long		// value to be stored to the variant
);
Parameters
  • Long, value of type vmTypeLong to be stored to the vmVariant object.
Return value
If the function succeeds, the return value is a handle to the new vmVariant object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmVariantHandle, vmCreateVariant, vmCreateVariantChar, vmCreateVariantShort, vmCreateVariantLongLong, vmCreateVariantFloat, vmCreateVariantDouble, vmCreateVariantLongDouble, vmDeleteVariant,

vmCreateVariantLongLong

The vmCreateVariantLongLong function allocates the new vmVariant object.
#include "vm48400_win32.h"

vmVariantHandle vmCreateVariantLongLong(
	vmTypeLongLong LongLong		// value to be stored to the variant
);
Parameters
  • LongLong, value of type vmTypeLongLong to be stored to the vmVariant object.
Return value
If the function succeeds, the return value is a handle to the new vmVariant object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmVariantHandle, vmCreateVariant, vmCreateVariantChar, vmCreateVariantShort, vmCreateVariantLong, vmCreateVariantFloat, vmCreateVariantDouble, vmCreateVariantLongDouble, vmDeleteVariant,

vmCreateVariantFloat

The vmCreateVariantFloat function allocates the new vmVariant object.
#include "vm48400_win32.h"

vmVariantHandle vmCreateVariantFloat(
	vmTypeFloat Float		// value to be stored to the variant
);
Parameters
  • Float, value of type vmTypeFloat to be stored to the vmVariant object.
Return value
If the function succeeds, the return value is a handle to the new vmVariant object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmVariantHandle, vmCreateVariant, vmCreateVariantChar, vmCreateVariantShort, vmCreateVariantLong, vmCreateVariantLongLong, vmCreateVariantDouble, vmCreateVariantLongDouble, vmDeleteVariant,

vmCreateVariantDouble

The vmCreateVariantDouble function allocates the new vmVariant object.
#include "vm48400_win32.h"

vmVariantHandle vmCreateVariantDouble(
	vmTypeDouble Double		// value to be stored to the variant
);
Parameters
  • Double, value of type vmTypeDouble to be stored to the vmVariant object.
Return value
If the function succeeds, the return value is a handle to the new vmVariant object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmVariantHandle, vmCreateVariant, vmCreateVariantChar, vmCreateVariantShort, vmCreateVariantLong, vmCreateVariantLongLong, vmCreateVariantFloat, vmCreateVariantLongDouble, vmDeleteVariant,

vmCreateVariantLongDouble

The vmCreateVariantLongDouble function allocates the new vmVariant object.
#include "vm48400_win32.h"

vmVariantHandle vmCreateVariantLongDouble(
	vmTypeLongDouble LongDouble		// value to be stored to the variant
);
Parameters
  • LongDouble, value of type vmTypeLongDouble to be stored to the vmVariant object.
Return value
If the function succeeds, the return value is a handle to the new vmVariant object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmVariantHandle, vmCreateVariant, vmCreateVariantChar, vmCreateVariantShort, vmCreateVariantLong, vmCreateVariantLongLong, vmCreateVariantFloat, vmCreateVariantDouble, vmDeleteVariant,

vmDeleteVariant

The vmDeleteVariant function frees the vmVariant object.
#include "vm48400_win32.h"

void vmDeleteVariant(
	vmVariantHandle Variant		// handle of the vmVariant object
);
Parameters
  • Variant, handle of the vmVariant object.
Return value
None

See also
vmVariantHandle, vmCreateVariant, vmCreateVariantChar, vmCreateVariantShort, vmCreateVariantLong, vmCreateVariantLongLong, vmCreateVariantFloat, vmCreateVariantDouble, vmCreateVariantLongDouble,

vmCreateReference

The vmCreateReference function allocates the new vmReference object.
#include "vm48400_win32.h"

vmReferenceHandle vmCreateReference(
	vmVariantType Type,		// type of the referenced external label
	LPCVOID Entry			// address of the referenced external label
);
Parameters
  • Type, type of the referenced label. If the reference is a function which doesn't return value, use vmVariantTypeVoid.
  • Entry, address of the referenced label or the function's entry point.
Return value
If the function succeeds, the return value is a handle to the new vmReference object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmReferenceHandle, vmDeleteReference

vmDeleteReference

The vmDeleteReference function frees the vmReference object.
#include "vm48400_win32.h"

void vmDeleteReference(
	vmReferenceHandle Reference		// handle of the vmReference object
);
Parameters
  • Reference, handle of the vmReference object.

Return value
None

See also
vmReferenceHandle, vmCreateReference

vmCreateLabel

The vmCreateLabel function allocates the new vmLabel object.
#include "vm48400_win32.h"

vmLabelHandle vmCreateLabel(
	ULONG Size,			// size of the variable
	LPCVOID Address			// address of the variable
);
Parameters
  • Size, size of the variable. Valid sizes are; 1, 2 and 4 bytes.
  • Address, address of the variable. The variable will get the label's value during the object load phase.
Return value
If the function succeeds, the return value is a handle to the new vmLabel object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmLabelHandle, vmDeleteLabel

vmDeleteLabel

The vmDeleteLabel function frees the vmLabel object.
#include "vm48400_win32.h"

void vmDeleteLabel(
	vmLabelHandle Label		// handle of the vmLabel object
);
Parameters
  • Label, handle of the vmLabel object.
Return value
None

See also
vmLabelHandle, vmCreateLabel

vmCreateStdArg

The vmCreateStdArg function allocates the new vmStdArg object.
#include "vm48400_win32.h"

vmStdArgHandle vmCreateStdArg(void);
Parameters
None

Return value
If the function succeeds, the return value is a handle to the new vmStdArg object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmStdArgHandle, vmAddStringToStdArg, vmDeleteStdArg, vmConvertStdArgToList

vmAddStringToStdArg

The vmAddStringToStdArg function stores the given string to the vmStdArg object.
#include "vm48400_win32.h"

BOOL vmAddStringToStdArg(
	vmStdArgHandle StdArg,		// handle of the vmStdArg object
	LPCSTR Arg			// pointer to the string
);
Parameters
  • StdArg, handle of the vmStdArg object.
  • Arg, pointer to the string. The string will be duplicated.
Return value
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See also
vmStdArgHandle, vmCreateStdArg, vmDeleteStdArg, vmConvertStdArgToList

vmDeleteStdArg

The vmDeleteStdArg function frees the vmStdArg object.
#include "vm48400_win32.h"

void vmDeleteStdArg(
	vmStdArgHandle StdArg		// handle of the vmStdArg object
);
Parameters
  • StdArg, handle of the vmStdArg object.
Return value
None

See also
vmStdArgHandle, vmCreateStdArg, vmAddStringToStdArg, vmConvertStdArgToList

vmConvertStdArgToList

The vmConvertStdArgToList function converts the vmStdArg object to the vmList object.
#include "vm48400_win32.h"

const vmListHandle vmConvertStdArgToList(
	vmStdArgHandle StdArg		// handle of the vmStdArg object
);
Parameters
  • StdArg, handle of the vmStdArg object.
Return value
If the function succeeds, the return value is a handle to the new vmList object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks
The succesfull call of the vmConvertStdArgToList function returns the vmList object. The list is also stored in the vmStdArg object and must not be freed after use. It will be automatically freed in the vmDeleteStdArg function or in the next call of the vmConvertStdArgToList function.

See also
vmStdArgHandle, vmCreateStdArg, vmAddStringToStdArg, vmDeleteStdArg

vmLoadExecutable

The vmLoadExecutable function finds and loads an executable object file.
#include "vm48400_win32.h"

vmObjectHandle vmLoadExecutable(
	LPCSTR Name,			// name of the object file
	vmListHandle References,		// optional list of external references
	vmListHandle Labels		// optional list of labels
);
Parameters
  • Name, name of the executable object file.
  • References, handle of the vmList object containing vmReference objects or NULL.
  • Labels, handle of the vmList object containing vmLabel objects or NULL.
Return value
If the function succeeds, the return value is a handle to the new vmObject object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See also
vmObjectHandle, vmDeleteObject, vmRun, vmReturnValue

vmDeleteObject

The vmDeleteObject function frees the vmObject object.
#include "vm48400_win32.h"

void vmDeleteObject(
	vmObjectHandle Object		// handle of the vmObject object
);
Parameters
  • Object, handle of the vmObject object.
Return value
None

See also
vmObjectHandle, vmLoadExecutable, vmRun, vmReturnValue

vmRun

The vmRun function runs the program loaded to the vmObject object.
#include "vm48400_win32.h"

BOOL vmRun(
	vmObjectHandle Object,		// handle of the vmObject object
	vmListHandle Parameters		// optional list of parameters
);
Parameters
  • Object, handle of the vmObject object.
  • Parameters, handle of the vmList object containing vmVariant objects or NULL.
Return value
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See also
vmObjectHandle, vmLoadExecutable, vmDeleteObject, vmReturnValue

vmReturnValue

The vmReturnValue function retrieves the return value of the vmObject object.
#include "vm48400_win32.h"

BOOL vmReturnValue(
	vmObjectHandle Object,		// handle of the vmObject object
	LPLONG ReturnValue			// reference to the return value variable
);
Parameters
  • Object, handle of the vmObject object.
  • ReturnValue, address of the variable which will receive the object's return value.
Return value
If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

See also
vmObjectHandle, vmLoadExecutable, vmDeleteObject, vmRun

Examples

Example 1. - load and run

Example 1. - load and run

This example will load the object file and run the program in it. Finally, the return value is retrieved and the object is freed.

#include "vm48400_win32.h"
#include <stdio.h>

int main(int argc, char **argv)
{
	vmObjectHandle Object;
	LONG ReturnValue;
	/* let's load the object named 'calculate'.
	 * don't bother using any references nor labels.
	 */
	Object = vmLoadExecutable("calculate", NULL, NULL);
	if(Object != NULL)
	{
		/* ok, the load was succesfull.
		 * now we can run the program(ain't using parameters).
		 */
		if(vmRun(Object, NULL))
		{
			/* hooray, the run was successfull!!!
			 * i wonder what was the return value??
			 */
			if(vmReturnValue(Object, &ReturnValue))
			{
				printf("retval=%d\n", ReturnValue);
			}
		}
		vmDeleteObject(Object);
	}
	return 0;
}

There are couple of things which need some clarification in this example.
  • Because we are not using references, the program in the object file must be entirely self contained. ie. it must not have any external references. So, the only way the program can interact with the user is the return value.
  • We choosed to not provide any parameters to the program. In the situation like this, the program must be written in such a way that it wouldn't use the startup function's parameters. The parameters can be declared but because nobody pushed the parameter values to the stack, the use of the parameter will lead to a protected mode fault.


version 0.1
20050130 Markku Alén


2005 AlluVision Inc.
2005 AlluVision Inc. All rights reserved.