vmi.h File Reference

---

Detailed Description

VM interface specification.

Classes
struct	VMInterfaceFunctions_
	The VM interface function table. More...
Defines
#define	vmi_h
#define	USING_VMI
#define	VMI_ACCESS_FROM_ENV(env)   VMInterface* privateVMI = VMI_GetVMIFromJNIEnv(env)
	Convenience macros for acquiring a VMInterface.
#define	VMI_ACCESS_FROM_JAVAVM(javaVM)   VMInterface* privateVMI = VMI_GetVMIFromJavaVM(javaVM)
#define	VMI   privateVMI
#define	BOOTCLASSPATH_PROPERTY   "org.apache.harmony.boot.class.path"
	Name of the property holding bootclasspath string.
Typedefs
typedef char *	value
typedef char void *	userData
typedef VMInterfaceFunctions_ *	VMInterface
	The VM interface structure.
Enumerations
enum	vmiError {   VMI_ERROR_NONE = 0, VMI_ERROR_UNKNOWN = 1, VMI_ERROR_UNIMPLEMENTED = 2, VMI_ERROR_UNSUPPORTED_VERSION = 3,   VMI_ERROR_OUT_OF_MEMORY = 4, VMI_ERROR_ILLEGAL_ARG = 5, VMI_ERROR_READ_ONLY = 6, vmiErrorEnsureWideEnum = 0x1000000 }
	Enumeration of all possible return codes from VM interface functions. More...
enum	vmiVersion { VMI_VERSION_UNKNOWN = 0x00000000, VMI_VERSION_1_0 = 0x00010000, vmiVersionEnsureWideEnum = 0x1000000 }
	VM interface version identifier. More...
Functions
typedef	void (JNICALL *vmiSystemPropertyIterator)(char *key
VMInterface *JNICALL	VMI_GetVMIFromJNIEnv (JNIEnv *env)
	Extract the VM interface from a JNIEnv.
VMInterface *JNICALL	VMI_GetVMIFromJavaVM (JavaVM *vm)
	Extract the VM interface from a JNI JavaVM.
vmiError JNICALL	CheckVersion (VMInterface *vmi, vmiVersion *version)
	Check the version of the VM interface.
JavaVM *JNICALL	GetJavaVM (VMInterface *vmi)
HyPortLibrary *JNICALL	GetPortLibrary (VMInterface *vmi)
HyVMLSFunctionTable *JNICALL	GetVMLSFunctions (VMInterface *vmi)
HyZipCachePool *JNICALL	GetZipCachePool (VMInterface *vmi)
JavaVMInitArgs *JNICALL	GetInitArgs (VMInterface *vmi)
vmiError JNICALL	GetSystemProperty (VMInterface *vmi, char *key, char **valuePtr)
	Retrieve the value of a VM system property.
vmiError JNICALL	SetSystemProperty (VMInterface *vmi, char *key, char *value)
	Override the value of a VM system property.
vmiError JNICALL	CountSystemProperties (VMInterface *vmi, int *countPtr)
	Return the number of VM system properties.
vmiError JNICALL	IterateSystemProperties (VMInterface *vmi, vmiSystemPropertyIterator iterator, void *userData)
	Iterate over the VM system properties calling a function.

---

Define Documentation

#define vmi_h

#define USING_VMI

#define VMI_ACCESS_FROM_ENV

(

env

)

VMInterface* privateVMI = VMI_GetVMIFromJNIEnv(env)

Convenience macros for acquiring a VMInterface.

#define VMI_ACCESS_FROM_JAVAVM

(

javaVM

)

VMInterface* privateVMI = VMI_GetVMIFromJavaVM(javaVM)

#define VMI   privateVMI

#define BOOTCLASSPATH_PROPERTY   "org.apache.harmony.boot.class.path"

Name of the property holding bootclasspath string.

---

Typedef Documentation

typedef char* value

typedef char void* userData

VMInterface

The VM interface structure.

Points to the VM interface function table. Implementations will likely choose to store opaque data off this structure.

---

Enumeration Type Documentation

enum vmiError

Enumeration of all possible return codes from VM interface functions.

Enumerator:

VMI_ERROR_NONE	Success.
VMI_ERROR_UNKNOWN	Unknown error.
VMI_ERROR_UNIMPLEMENTED	Function has not been implemented.
VMI_ERROR_UNSUPPORTED_VERSION	The requested VM interface version is not supported.
VMI_ERROR_OUT_OF_MEMORY	Not enough memory was available to complete the request.
VMI_ERROR_ILLEGAL_ARG	An attempt to set illegal value (e.g. NULL value is not allowed in system properties)
VMI_ERROR_READ_ONLY	An attempt was made to modify a read-only item.
vmiErrorEnsureWideEnum

enum vmiVersion

VM interface version identifier.

Enumerator:

VMI_VERSION_UNKNOWN	Unknown VMInterface version.
VMI_VERSION_1_0	VMInterface version 1.0.
vmiVersionEnsureWideEnum

---

Function Documentation

typedef void

(

JNICALL *

vmiSystemPropertyIterator

)

VMInterface* JNICALL VMI_GetVMIFromJNIEnv

(

JNIEnv *

env

)

Extract the VM interface from a JNIEnv.

VMInterface* JNICALL VMI_GetVMIFromJavaVM

(

JavaVM *

vm

)

Extract the VM interface from a JNI JavaVM.

VMInterfaceFunctions_::CheckVersion	(	VMInterface *	vmi,
		vmiVersion *	version
	)

Check the version of the VM interface.

 vmiError JNICALL CheckVersion(VMInterface* vmi, vmiVersion* version); 

Parameters:

[in]	vmi	The VM interface pointer
[in,out]	version	Pass in the version to check, or VMI_VERSION_UNKNOWN. Returns the current version.

Returns:

a VMI error code

Note:

The CheckVersion function allows a class library to verify that the VM provides the required interface functions. If the version requested is VMI_VERSION_UNKNOWN, then the function will reply with the current version and not return an error. If a specific version is passed, it will be compatibility checked against the current, and VMI_ERROR_UNSUPPORTED_VERSION may be returned.

JavaVM* JNICALL GetJavaVM

(

VMInterface *

vmi

)

HyPortLibrary* JNICALL GetPortLibrary

(

VMInterface *

vmi

)

HyVMLSFunctionTable* JNICALL GetVMLSFunctions

(

VMInterface *

vmi

)

HyZipCachePool* JNICALL GetZipCachePool

(

VMInterface *

vmi

)

JavaVMInitArgs* JNICALL GetInitArgs

(

VMInterface *

vmi

)

VMInterfaceFunctions_::GetSystemProperty	(	VMInterface *	vmi,
		char *	key,
		char **	valuePtr
	)

Retrieve the value of a VM system property.

Note:

The returned string is owned by the VM, and should not be freed.

VMInterfaceFunctions_::SetSystemProperty	(	VMInterface *	vmi,
		char *	key,
		char *	value
	)

Override the value of a VM system property.

 vmiError JNICALL SetSystemProperty(VMInterface* vmi, char* key, char* value); 

Parameters:

[in]	vmi	The VM interface pointer
[in]	key	The system property to override
[in]	value	The value of the system property

Returns:

a VMI error code

Note:

Only existing properties can be overridden. New properties cannot be added by this mechanism.

See GetSystemProperty() for the list of properties that must be defined by the vm.

VMInterfaceFunctions_::CountSystemProperties	(	VMInterface *	vmi,
		int *	countPtr
	)

Return the number of VM system properties.

 vmiError JNICALL CountSystemProperties(VMInterface* vmi, int* countPtr); 

Parameters:

[in]	vmi	The VM interface pointer
[out]	countPtr	The location to store the number of system properties

Returns:

a VMI error code

Note:

See GetSystemProperty() for the list of properties that must be defined by the vm.

VMInterfaceFunctions_::IterateSystemProperties	(	VMInterface *	vmi,
		vmiSystemPropertyIterator	iterator,
		void *	userData
	)

Iterate over the VM system properties calling a function.

Parameters:

[in]	vmi	The VM interface pointer
[in]	iterator	The iterator function to call with each property
[in]	userData	Opaque data to pass to the iterator function

Returns:

a VMI error code

Note:

The returned strings are owned by the VM, and should not be freed.

See GetSystemProperty() for the list of properties that must be defined by the vm.

---