modules/luni/src/main/native/include/shared/vmi.h File Reference

---

Detailed Description

VM interface specification.

#include "jni.h"
#include "hyport.h"
#include "hyvmls.h"
#include "zipsup.h"

Data Structures
struct	VMInterfaceFunctions_
	The VM interface function table. More...
Defines
#define	VMI_ACCESS_FROM_ENV(env)   VMInterface* privateVMI = VMI_GetVMIFromJNIEnv(env)
	Convenience macros for acquiring a VMInterface.
#define	BOOTCLASSPATH_PROPERTY   "org.apache.harmony.boot.class.path"
	Name of the property holding bootclasspath string.
Typedefs
typedef struct 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 }
	Enumeration of all possible return codes from VM interface functions. More...
enum	vmiVersion {   VMI_VERSION_UNKNOWN = 0x00000000,   VMI_VERSION_1_0 = 0x00010000 }
	VM interface version identifier. More...
Functions
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.
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 BOOTCLASSPATH_PROPERTY   "org.apache.harmony.boot.class.path"

Name of the property holding bootclasspath string.

#define VMI_ACCESS_FROM_ENV

(

env

)

VMInterface* privateVMI = VMI_GetVMIFromJNIEnv(env)

Convenience macros for acquiring a VMInterface.

---

Typedef Documentation

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.

enum vmiVersion

VM interface version identifier.

Enumerator:

VMI_VERSION_UNKNOWN	Unknown VMInterface version.
VMI_VERSION_1_0	VMInterface version 1.0.

---

Function Documentation

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.

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_::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_::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.

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.

VMInterface* JNICALL VMI_GetVMIFromJavaVM

(

JavaVM *

vm

)

Extract the VM interface from a JNI JavaVM.

Extract the VM interface from a JNI JavaVM.

This stub implementation is non-functional, provided for the purposes of building the dependent natives. Extract the VM Interface from a JNI JavaVM

Parameters:

[in]

vm

The JavaVM to query

Returns:

a VMInterface pointer

VMInterface* JNICALL VMI_GetVMIFromJNIEnv

(

JNIEnv *

env

)

Extract the VM interface from a JNIEnv.

Extract the VM interface from a JNIEnv.

Parameters:

[in]

env

The JNIEnv to query

Returns:

a VMInterface pointer

---