729628e531b73ea366f673393008e45740218428
[scilab.git] / scilab / modules / jvm / includes / JniUtils.h
1 /*------------------------------------------------------------------------*/
2 /* file: JniUtils.h                                                       */
3 /* Copyright INRIA 2007                                                   */
4 /* Authors : Jean-Baptiste Silvy                                          */
5 /* desc : Set of functions to simplify the use of JNI. These              */
6 /*        functions are used to call Java from C code                     */
7 /*------------------------------------------------------------------------*/
8
9 #ifndef _JNI_UTILS_H_
10 #define _JNI_UTILS_H_
11
12 #include <jni.h>
13 #include <stdarg.h>
14 #include "machine.h"
15
16 /**
17  * Cache some data that does not change between functions calls
18  */
19 typedef struct 
20 {
21   jclass    instanceClass;
22   jmethodID methodId;
23 } jniCallMethodCache;
24
25 /**
26  * Create a new cache
27  */
28 jniCallMethodCache * jniCreateCallMethodCache( void ) ;
29
30 /**
31  * Destroy a cache
32  */
33 void jniDestroyCallMethodCache( jniCallMethodCache * cache ) ;
34
35 /**
36  * Initialize a cache with its values.
37  */
38 void jniIntializeCallMethodCache( jniCallMethodCache * cache, jclass instanceClass, jmethodID methodId ) ;
39
40 /**
41  * To know if a cache has alredy been initialized
42  */
43 BOOL jniIsCallMethodCacheInitialized( jniCallMethodCache * cache ) ;
44
45 /**
46  * Initialize the environment from an already created jvm.
47  */
48 void jniInitUtils( JavaVM * jvm ) ;
49
50 /**
51  * To be called when we don't need the jvm any more.
52  */
53 void jniCloseUtils( void ) ;
54
55 /**
56  * Return the virtual machine used by this object
57  */
58 JavaVM * jniGetJavaVM( void ) ;
59
60 /**
61  * Manually specify the current java environment.
62  * Maught be used when calling C function from Java
63  */
64 void jniSetCurrentEnv( JNIEnv * env ) ;
65
66 /**
67  * Retrieve the current Java environment from the JVM.
68  * This function should be called each time the environment
69  * May have changed.
70  */
71 void jniUpdateCurrentEnv( void ) ;
72
73 /**
74  * Get the current Java environment
75  */
76 JNIEnv * jniGetCurrentJavaEnv( void ) ;
77
78 /**
79  * Allocate and set a Java array as a copy of a C array.
80  */
81 jdoubleArray jniCreateDoubleArrayCopy( const jdouble * cArray, int nbElements ) ;
82 jintArray    jniCreateIntArrayCopy(    const jint    * cArray, int nbElements ) ;
83
84 /**
85  * Copy a java array into a preallocated C array
86  */
87 void jniCopyJavaDoubleArray( const jdoubleArray javaArray, jdouble * cArray ) ;
88 void jniCopyJavaIntArray(    const jintArray    javaArray, jint    * cArray ) ;
89
90 /**
91  * Create a copy of a C string to a Java string
92  */
93 jstring jniCreateStringCopy( const char * cString ) ;
94
95 /**
96  * Delete a Java object (array, objects, ...)
97  */
98 void jniDeleteLocalEntity( jobject entity ) ;
99
100 /**
101 * Delete a Java object (array, objects, ...)
102 */
103 void jniDeleteGlobalEntity( jobject entity ) ;
104
105 /**
106  * Create a new instance of a Java class calling its
107  * default constructor
108  * @param className[in] string of the class name
109  * @param instanceClass[out] Java reference to the class
110  * @param instance[out] created object
111  * @return TRUE if the call was succesful, FALSE otherwise.
112  */
113 BOOL jniCreateDefaultInstance(     const char * className, jclass * instanceClass, jobject * instance ) ;
114 BOOL jniCreateDefaultInstanceSafe( const char * className, jclass * instanceClass, jobject * instance ) ;
115
116 /**
117  * Call a Java function returning void.
118  * @param instance Object caontaining the function to call
119  * @param functionName Name of the function
120  * @param paramTypes string containing the types of paramaters given as optionals argument.
121  *                   This respect the JNI style and looks like "[DID".
122  * @return TRUE if the call was succesful, FALSE otherwise.
123  */
124 BOOL jniCallVoidFunction(     jobject instance, jclass instanceClass, const char * functionName, const char * paramTypes, ... ) ;
125 BOOL jniCallVoidFunctionSafe( jobject instance, jclass instanceClass, const char * functionName, const char * paramTypes, ... ) ;
126 BOOL jniCallVoidFunctionV(    jobject instance, jclass instanceClass, const char * functionName, const char * paramTypes, va_list args ) ;
127
128 /**
129  * Call a java member function from C code.
130  * @param instance bject containing the function to call
131  * @param cache cache relative to this function used to speed up call to the function.
132  *              if cache is NULL, then it is not used. If cache is not initialized then the function will initialize it.
133  * @param pointer on the instance class. If NULL the class would be retrieved from the object and stored in the instance class.
134  * @param functionName Name of the function
135  * @param descriptor string containing the kinds of parameters the function takes and the return type.
136  *                   This respect the JNI style and looks like "([DID)V".
137  * The parameters are then given has optionals arguments.
138  */
139 jvalue jniCallMemberFunction(     jobject instance, jniCallMethodCache * cache, const char * functionName, const char * descriptor, ... ) ;
140 jvalue jniCallMemberFunctionSafe( jobject instance, jniCallMethodCache * cache, const char * functionName, const char * descriptor, ... ) ;
141 jvalue jniCallMemberFunctionV(    jobject instance, jniCallMethodCache * cache, const char * functionName, const char * descriptor, va_list args ) ;
142
143
144 /**
145  * Set a jvalue to default values
146  */
147 void jniInitJValue( jvalue * value ) ;
148
149 /**
150  * Get the double value of a jvalue;
151  */
152 double jniGetDoubleValue( jvalue value ) ;
153 int    jniGetIntValue(    jvalue value ) ;
154
155 /**
156  * Tell if the last call to JNI primitive was successful
157  * @return true if the call was successful, false otherwise
158  * @param dumpStack if true the calling stack is dump in the shell
159  * like when exceptions are not caught in Java
160  */
161 BOOL jniCheckLastCall( BOOL dumpStack ) ;
162
163 #endif /* _JNI_UTILS_H_ */
164