Cryville.Interop.Java

Provides a set of helper methods for Android.

The Android API level of the device.

Gets a local reference to the current android.app.Application object.

The . A local reference to the current android.app.Application object. This method can only be called from the main thread, otherwise it may return a reference to null.

Gets a local reference to a system service associated with the context specified by .

The . The context. The name of a static field in the class android.content.Context. A local reference to a system service.

Represents a local reference frame.

Use this struct with a using statement: using (JniLocalFrame frame = new JniLocalFrame(env, capacity)) { // ... } If an object obtained within the frame is required outside the frame, use this code snippet: IntPtr result; using (JniLocalFrame frame = new JniLocalFrame(env, capacity)) { // ... result = frame.Pop(obj); }

Pushes a local reference frame in which at least a given number of local references can be created.

The . The capacity.

Pops off the local reference frame, frees all the local references, and returns a local reference in the previous local reference frame for the given object.

The result object. A local reference in the previous local reference frame for the given object. The local reference frame has already been popped. Pass as if you do not need to return a reference to the previous frame.

Pops off the local reference frame and frees all the local references.

The JNI Invocation API.

Unloads a Java VM and reclaims its resources.

On failure. Any thread, whether attached or not, can invoke this function. If the current thread is attached, the VM waits until the current thread is the only non-daemon user-level Java thread. If the current thread is not attached, the VM attaches the current thread and then waits until the current thread is the only non-daemon user-level thread.

Attaches the current thread to a Java VM.

or a structure to specify additional information. A JNI interface. On failure. Trying to attach a thread that is already attached is a no-op. A native thread cannot be attached simultaneously to two Java VMs. When a thread is attached to the VM, the context class loader is the bootstrap loader.

Detaches the current thread from a Java VM.

On failure. All Java monitors held by this thread are released. All Java threads waiting for this thread to die are notified. The main thread can be detached from the VM.

Gets the attached to the current thread.

The requested JNI version. A JNI interface, if an error occurs. On failure, with a of if the current thread is not attached to the VM, or if the specified version is not supported.

Same semantics as , but the newly-created java.lang.Thread instance is a daemon.

A structure to specify additional information. A JNI interface. On failure. If the thread has already been attached via either or , this routine simply returns the of the current thread. In this case neither nor this routine have any effect on the daemon status of the thread.

Additional information for attaching the current thread to a Java VM.

The requested JNI version.

The name of the thread, or .

Global ref of a ThreadGroup object, or .

Creates an instance of the struct.

The requested JNI version. The name of the thread. Global ref of a ThreadGroup object.

Java VM manager.

Registers a Java VM.

A Java VM. is .

All registered Java VMs.

The first VM registered.

The of the first VM registered.

Exception occurring in JNI functions.

The result code returned by the JNI function.

Creates an instance of the class with set to .

Creates an instance of the class with set to .

The error message that explains the reason for the exception.

Creates an instance of the class with set to .

The error message that explains the reason for the exception. The exception that is the cause of the current exception.

Creates an instance of the class with set to .

The exception that is the cause of the current exception.

Creates an instance of the class.

The result code returned by the JNI function.

Creates an instance of the class.

The result code returned by the JNI function. The error message that explains the reason for the exception.

Creates an instance of the class.

The result code returned by the JNI function. The error message that explains the reason for the exception. The exception that is the cause of the current exception.

Creates an instance of the class with serialized data.

The that holds the serialized object data about the exception being thrown. The that contains contextual information about the source or destination.

Checks the result code returned by a JNI function and throws a if an error occurred.

The result code returned by a JNI function. An error occurred.

JNI native method.

The name of the native method.

The signature of the native method.

The function pointer of the native method.

The function pointers nominally must have the following signature: ReturnType function(IntPtr env, IntPtr objectOrClass, ...)

Creates an instance of the struct.

The name. The signature. The function pointer. Either of the arguments is .

Object reference type.

Invalid reference.

Local reference type.

Global reference type.

Weak global reference type.

Provides information on how the array buffer should be released.

Copy back the content and free the elems buffer.

Copy back the content but do not free the elems buffer.

Free the buffer without copying back the possible changes.

The Java native interface.

Returns the version of the native method interface.

The version of the native method interface. Returns the major version number in the higher 16 bits and the minor version number in the lower 16 bits. In JDK/JRE 1.1, returns 0x00010001. In JDK/JRE 1.2, returns 0x00010002. In JDK/JRE 1.4, returns 0x00010004. In JDK/JRE 1.6, returns 0x00010006.

Loads a class from a buffer of raw class data.

The name of the class or interface to be defined. A class loader assigned to the defined class. Buffer containing the .class file data. Buffer length. A Java class object or if an error occurs. The buffer containing the raw class data is not referenced by the VM after the DefineClass call returns, and it may be discarded if desired.

Searches and loads a defined class.

A fully-qualified class name (that is, a package name, delimited by “/”, followed by the class name). If the name begins with “[“ (the array signature character), it returns an array class. A class object from a fully-qualified name, or if the class cannot be found. In JDK release 1.1, this function loads a locally-defined class. It searches the directories and zip files specified by the CLASSPATH environment variable for the class with the specified name. Since Java 2 SDK release 1.2, the Java security model allows non-system classes to load and call native methods. locates the class loader associated with the current native method; that is, the class loader of the class that declared the native method. If the native method belongs to a system class, no class loader will be involved. Otherwise, the proper class loader will be invoked to load and link the named class. Since Java 2 SDK release 1.2, when is called through the Invocation Interface, there is no current native method or its associated class loader. In that case, the result of ClassLoader.getSystemClassLoader is used. This is the class loader the virtual machine creates for applications, and is able to locate classes listed in the java.class.path property. The name argument is a fully-qualified class name or an array type signature. For example, the fully-qualified class name for the java.lang.String class is: "java/lang/String" The array type signature of the array class java.lang.Object[] is: "[Ljava/lang/Object;"

Converts a java.lang.reflect.Method or java.lang.reflect.Constructor object to a method ID.

A java.lang.reflect.Method or java.lang.reflect.Constructor object. A method ID.

Converts a java.lang.reflect.Field to a field ID.

A java.lang.reflect.Field. A field ID.

Converts a method ID derived from to a java.lang.reflect.Method or java.lang.reflect.Constructor object.

A Java class. A method ID. Whether the method ID refers to a static field. A java.lang.reflect.Method or java.lang.reflect.Constructor object. if fails.

Returns the object that represents the superclass of the class specified by .

A Java class object. The superclass of the class represented by , or . If represents any class other than the class Object, then this function returns the object that represents the superclass of the class specified by . If specifies the class Object, or represents an interface, this function returns .

Determines whether an object of can be safely cast to .

The first class argument. The second class argument. if either of the following is true:The first and second class arguments refer to the same Java class.The first class is a subclass of the second class.The first class has the second class as one of its interfaces.

Converts a field ID derived from to a java.lang.reflect.Field object.

A Java class. A field ID. Whether refers to a static field. A java.lang.reflect.Field object. if fails.

Causes a java.lang.Throwable object to be thrown.

A java.lang.Throwable object. On failure.

Constructs an exception object from the specified class with the message specified by and causes that exception to be thrown.

A subclass of java.lang.Throwable. The message used to construct the java.lang.Throwable object. On failure.

Determines if an exception is being thrown.

The exception object that is currently in the process of being thrown, or if no exception is currently being thrown. The exception stays being thrown until either the native code calls , or the Java code handles the exception.

Prints an exception and a backtrace of the stack to a system error-reporting channel, such as stderr.

This is a convenience routine provided for debugging.

Clears any exception that is currently being thrown.

If no exception is currently being thrown, this routine has no effect.

Raises a fatal error and does not expect the VM to recover. This function does not return.

An error message.

Creates a new local reference frame, in which at least a given number of local references can be created.

The capacity of the frame. On failure with a pending OutOfMemoryError. Note that local references already created in previous local frames are still valid in the current local frame.

Pops off the current local reference frame, frees all the local references, and returns a local reference in the previous local reference frame for the given object.

The result object. A local reference in the previous local reference frame for the given object. Pass as if you do not need to return a reference to the previous frame.

Creates a new global reference to the object referred to by the argument.

A global or local reference. A global reference to the given . if: refers to nullthe system has run out of memory was a weak global reference and has already been garbage collected Global references must be explicitly disposed of by calling .

Deletes the global reference pointed to by .

A global reference.

Deletes the local reference pointed to by .

A local reference. JDK/JRE 1.1 provides the function so that programmers can manually delete local references. For example, if native code iterates through a potentially large array of objects and uses one element in each iteration, it is a good practice to delete the local reference to the no-longer-used array element before a new local reference is created in the next iteration. As of JDK/JRE 1.2 an additional set of functions are provided for local reference lifetime management. They are the four functions listed below:

Tests whether two references refer to the same Java object.

A Java object. A Java object. if and refer to the same Java object, or are both null; otherwise, .

Creates a new local reference that refers to the same object as .

A global or local reference. A new local reference that refers to the same object as . if refers to null.

Ensures that at least a given number of local references can be created in the current thread.

The number of local references. On failure with a pending OutOfMemoryError. Before it enters a native method, the VM automatically ensures that at least 16 local references can be created. For backward compatibility, the VM allocates local references beyond the ensured capacity. (As a debugging support, the VM may give the user warnings that too many local references are being created. In the JDK, the programmer can supply the -verbose:jni command line option to turn on these messages.) The VM calls FatalError if no more local references can be created beyond the ensured capacity.

Allocates a new Java object without invoking any of the constructors for the object.

A Java class object. A Java object, or if the object cannot be constructed. The argument must not refer to an array class.

Constructs a new Java object.

A Java class object. The method ID of the constructor. An array of arguments to the constructor. A Java object, or if the object cannot be constructed. The method ID indicates which constructor method to invoke. This ID must be obtained by calling with <init> as the method name and void (V) as the return type. The argument must not refer to an array class.

Returns the class of an object.

A Java object (must not be ). A Java class object.

Tests whether an object is an instance of a class.

A Java object. A Java class object. if can be cast to ; otherwise, . null can be cast to any class.

Returns the method ID for an instance (nonstatic) method of a class or interface.

A Java class object. The method name. The method signature. A method ID, or if the specified method cannot be found. The method may be defined in one of the ’s superclasses and inherited by . The method is determined by its name and signature. causes an uninitialized class to be initialized. To obtain the method ID of a constructor, supply <init> as the method name and void (V) as the return type.

Invokes an instance (nonstatic) method on a Java object, according to the specified method ID.

A Java object. A method ID. An array of arguments. The result of calling the Java method. The argument must be obtained by calling . When the function is used to call private methods and constructors, the method ID must be derived from the real class of , not from one of its superclasses.

Invokes an instance (nonstatic) method on a Java object, based on the class, designated by the parameter, from which the method ID is obtained.

A Java object. A Java class. A method ID. An array of arguments. The result of calling the Java method. The argument must be obtained by calling . The families of routines and the families of routines are different. routines invoke the method based on the class of the object, while routines invoke the method based on the class, designated by the parameter, from which the method ID is obtained. The method ID must be obtained from the real class of the object or from one of its superclasses.

Returns the field ID for an instance (nonstatic) field of a class.

A Java class object. The field name. The field signature. A field ID, or if the operation fails. The field is specified by its name and signature. The and families of accessor functions use field IDs to retrieve object fields. causes an uninitialized class to be initialized. cannot be used to obtain the length field of an array. Use instead.

Returns the value of an instance (nonstatic) field of an object.

A Java object (must not be ). A valid field ID. The content of the field. The field to access is specified by a field ID obtained by calling .

Sets the value of an instance (nonstatic) field of an object.

A Java object (must not be ). A valid field ID. The new value of the field. The field to access is specified by a field ID obtained by calling .

Returns the method ID for a static method of a class.

A Java class object. The static method name. The method signature. A method ID, or if the operation fails. The method is specified by its name and signature. causes an uninitialized class to be initialized.

Invokes a static method on a Java object, according to the specified method ID.

A Java object. A static method ID. An array of arguments. The result of calling the static Java method. The method ID must be derived from , not from one of its superclasses.

Returns the field ID for a static field of a class.

A Java class object. The static field name. The field signature. A field ID, or if the specified static field cannot be found. The field is specified by its name and signature. The and families of accessor functions use field IDs to retrieve static fields. causes an uninitialized class to be initialized.

Returns the value of a static field of an object.

A Java class object. A static field ID. The content of the static field. The field to access is specified by a field ID, which is obtained by calling .

Sets the value of a static field of an object.

A Java class object. A static field ID. The new value of the field. The field to access is specified by a field ID, which is obtained by calling .

Constructs a new java.lang.String object from an array of Unicode characters.

A pointer to a Unicode string. Length of the Unicode string. A Java string object, or if the string cannot be constructed.

Returns the length (the count of Unicode characters) of a Java string.

A Java string object. The length of the Java string.

Returns a pointer to the array of Unicode characters of the string.

A Java string object. Set to if a copy is made; or set to if no copy is made. A pointer to a Unicode string, or if the operation fails. The returned pointer is valid until is called.

Informs the VM that the native code no longer needs access to .

A Java string object. A pointer to a Unicode string. The argument is a pointer obtained from string using .

Constructs a new java.lang.String object from an array of characters in modified UTF-8 encoding.

The pointer to a modified UTF-8 string. A Java string object, or if the string cannot be constructed.

Returns the length in bytes of the modified UTF-8 representation of a string.

A Java string object. Returns the UTF-8 length of the string.

Returns a pointer to an array of bytes representing the string in modified UTF-8 encoding.

A Java string object. Set to if a copy is made; or set to if no copy is made. A pointer to a modified UTF-8 string, or if the operation fails. The returned array is valid until it is released by .

Informs the VM that the native code no longer needs access to .

A Java string object. A pointer to a modified UTF-8 string. The argument is a pointer derived from string using .

Returns the number of elements in the array.

A Java array object. The length of the array.

Constructs a new array holding objects in class .

Array size. Array element class. Initialization value. A Java array object, or if the array cannot be constructed. All elements are initially set to .

Returns an element of an Object array.

A Java array. Array index. A Java object.

Sets an element of an Object array.

A Java array. Array index. The new value.

Constructs a new primitive array object.

The array length. A Java array, or if the array cannot be constructed.

Returns the body of the primitive array.

A Java array. Set to if a copy is made; or set to if no copy is made. A pointer to the array elements, or if the operation fails. The result is valid until the corresponding function is called. Since the returned array may be a copy of the Java array, changes made to the returned array will not necessarily be reflected in the original array until is called.

Informs the VM that the native code no longer needs access to .

A Java array object. A pointer to array elements. The release mode. The argument is a pointer derived from array using the corresponding function. If necessary, this function copies back all changes made to to the original array. The argument provides information on how the array buffer should be released. has no effect if is not a copy of the elements in . In most cases, programmers pass to the mode argument to ensure consistent behavior for both pinned and copied arrays. The other options give the programmer more control over memory management and should be used with extreme care.

Copies a region of a primitive array into a buffer.

A Java array. The starting index. The number of elements to be copied. The destination buffer.

Copies back a region of a primitive array from a buffer.

A Java array. The starting index. The number of elements to be copied. The source buffer.

Registers native methods with the class specified by the argument.

A Java class object. The native methods in the class. On failure. The parameter specifies an array of structures that contain the names, signatures, and function pointers of the native methods.

Unregisters native methods of a class.

A Java class object. On failure. The class goes back to the state before it was linked or registered with its native method functions. This function should not be used in normal native code. Instead, it provides special programs a way to reload and relink native libraries.

Enters the monitor associated with the underlying Java object referred to by .

A normal Java object or class object. On failure. Enters the monitor associated with the object referred to by . The reference must not be . Each Java object has a monitor associated with it. If the current thread already owns the monitor associated with , it increments a counter in the monitor indicating the number of times this thread has entered the monitor. If the monitor associated with is not owned by any thread, the current thread becomes the owner of the monitor, setting the entry count of this monitor to 1. If another thread already owns the monitor associated with , the current thread waits until the monitor is released, then tries again to gain ownership.

Exits the monitor associated with the underlying Java object referred to by .

A normal Java object or class object. On failure. The current thread must be the owner of the monitor associated with the underlying Java object referred to by . The thread decrements the counter indicating the number of times it has entered this monitor. If the value of the counter becomes zero, the current thread releases the monitor. Native code must not use to exit a monitor entered through a synchronized method or a monitorenter Java virtual machine instruction.

Returns the Java VM interface (used in the Invocation API) associated with the current thread.

The result. On failure.

Copies number of Unicode characters beginning at offset to the given buffer .

A Java string object. The offset where the copy starts. The number of characters to be copied. The destination buffer. Throws StringIndexOutOfBoundsException on index overflow.

Translates number of Unicode characters beginning at offset into modified UTF-8 encoding and place the result in the given buffer .

A Java string object. The offset where the translation starts. The number of characters to be translated. The destination buffer. Throws StringIndexOutOfBoundsException on index overflow.

Returns the body of the primitive array.

A Java array. Set to if a copy is made; or set to if no copy is made. A pointer to the array elements, or if the operation fails. The result is valid until the corresponding function is called. Since the returned array may be a copy of the Java array, changes made to the returned array will not necessarily be reflected in the original array until is called. There are significant restrictions on how this function can be used. After calling , the native code should not run for an extended period of time before it calls . We must treat the code inside this pair of functions as running in a "critical region." Inside a critical region, native code must not call other JNI functions, or any system call that may cause the current thread to block and wait for another Java thread. (For example, the current thread must not call read on a stream being written by another Java thread.) These restrictions make it more likely that the native code will obtain an uncopied version of the array, even if the VM does not support pinning. For example, a VM may temporarily disable garbage collection when the native code is holding a pointer to an array obtained via . Multiple pairs of and may be nested. Note that might still make a copy of the array if the VM internally represents arrays in a different format. Therefore we need to check its return value against for possible out of memory situations.

Informs the VM that the native code no longer needs access to .

A Java array object. A pointer to array elements. The release mode. The argument is a pointer derived from array using the corresponding function. If necessary, this function copies back all changes made to to the original array. The argument provides information on how the array buffer should be released. has no effect if is not a copy of the elements in . In most cases, programmers pass to the mode argument to ensure consistent behavior for both pinned and copied arrays. The other options give the programmer more control over memory management and should be used with extreme care. There are significant restrictions on how this function can be used. After calling , the native code should not run for an extended period of time before it calls . We must treat the code inside this pair of functions as running in a "critical region." Inside a critical region, native code must not call other JNI functions, or any system call that may cause the current thread to block and wait for another Java thread. (For example, the current thread must not call read on a stream being written by another Java thread.) These restrictions make it more likely that the native code will obtain an uncopied version of the array, even if the VM does not support pinning. For example, a VM may temporarily disable garbage collection when the native code is holding a pointer to an array obtained via . Multiple pairs of and may be nested. Note that might still make a copy of the array if the VM internally represents arrays in a different format. Therefore we need to check its return value against for possible out of memory situations.

Returns a pointer to the array of Unicode characters of the string.

A Java string object. Set to if a copy is made; or it is set to if no copy is made. A pointer to a Unicode string, or if the operation fails. The returned pointer is valid until is called. There are significant restrictions on how this function can be used. In a code segment enclosed by and calls, the native code must not issue arbitrary JNI calls, or cause the current thread to block.

Informs the VM that the native code no longer needs access to .

A Java string object. A pointer to a Unicode string. The argument is a pointer obtained from string using . There are significant restrictions on how this function can be used. In a code segment enclosed by and calls, the native code must not issue arbitrary JNI calls, or cause the current thread to block.

Creates a new weak global reference.

The object. A new weak global reference. if refers to null, or if the VM runs out of memory. If the VM runs out of memory, an OutOfMemoryError will be thrown.

Delete the VM resources needed for the given weak global reference.

The weak global reference.

Checks whether there is a pending exception.

when there is a pending exception; otherwise, . Identical to , but without creating a local reference to the exception object.

Allocates and returns a direct java.nio.ByteBuffer referring to the block of memory starting at the memory address and extending bytes.

The starting address of the memory region (must not be ). The size in bytes of the memory region (must be positive). A local reference to the newly-instantiated java.nio.ByteBuffer object. if an exception occurs, or if JNI access to direct buffers is not supported by this virtual machine. Native code that calls this function and returns the resulting byte-buffer object to Java-level code should ensure that the buffer refers to a valid region of memory that is accessible for reading and, if appropriate, writing. An attempt to access an invalid memory location from Java code will either return an arbitrary value, have no visible effect, or cause an unspecified exception to be thrown.

Fetches and returns the starting address of the memory region referenced by the given direct java.nio.Buffer.

A direct java.nio.Buffer object (must not be ). The starting address of the memory region referenced by the buffer. if the memory region is undefined, if the given object is not a direct java.nio.Buffer, or if JNI access to direct buffers is not supported by this virtual machine. This function allows native code to access the same memory region that is accessible to Java code via the buffer object.

Fetches and returns the capacity of the memory region referenced by the given direct java.nio.Buffer.

A direct java.nio.Buffer object (must not be ). The capacity of the memory region associated with the buffer. -1 if the given object is not a direct java.nio.Buffer, if the object is an unaligned view buffer and the processor architecture does not support unaligned access, or if JNI access to direct buffers is not supported by this virtual machine. The capacity is the number of elements that the memory region contains.

Returns the type of the object referred to by the argument.

A local, global or weak global reference. One of the enumerated values defined as a . If the argument is not a valid reference, the return value for this function will be . An invalid reference is a reference which is not a valid handle. That is, the pointer address does not point to a location in memory which has been allocated from one of the Ref creation functions or returned from a JNI function. As such, would be an invalid reference and would return . On the other hand, a null reference, which is a reference that points to a null, would return the type of reference that the null reference was originally created as. cannot be used on deleted references. Since references are typically implemented as pointers to memory data structures that can potentially be reused by any of the reference allocation services in the VM, once deleted, it is not specified what value the will return.

Result code returned by JNI functions.

Success.

Unknown error.

Thread detached from the VM.

JNI version error.

Not enough memory.

VM already created.

Invalid arguments.

Check inner exception.

JNI value.

Creates an instance of the struct with a (boolean in Java) value.

The value.

Creates an instance of the struct with a (byte in Java) value.

The value.

Creates an instance of the struct with a (casted to , byte in Java) value.

The value.

Creates an instance of the struct with a (char in Java) value.

The value.

Creates an instance of the struct with a (short in Java) value.

The value.

Creates an instance of the struct with a (casted to , short in Java) value.

The value.

Creates an instance of the struct with a (int in Java) value.

The value.

Creates an instance of the struct with a (casted to , int in Java) value.

The value.

Creates an instance of the struct with a (long in Java) value.

The value.

Creates an instance of the struct with a (casted to , long in Java) value.

The value.

Creates an instance of the struct with a (float in Java) value.

The value.

Creates an instance of the struct with a (double in Java) value.

The value.

Creates an instance of the struct with a to an object (java.lang.Object in Java).

The value.