Added some useful variables to java.make
[nativez] / src / notzed.nativez / jni / nativez.h
1 /*
2  * Copyright (C) 2018 Michael Zucchi
3  *
4  * This file is part of nativez <https://www.zedzone.space/software/nativez.html>
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions are
8  * met:
9  *
10  *     (1) Redistributions of source code must retain the above copyright
11  *     notice, this list of conditions and the following disclaimer. 
12  *
13  *     (2) Redistributions in binary form must reproduce the above copyright
14  *     notice, this list of conditions and the following disclaimer in
15  *     the documentation and/or other materials provided with the
16  *     distribution.  
17  *     
18  *     (3)The name of the author may not be used to
19  *     endorse or promote products derived from this software without
20  *     specific prior written permission.
21  * 
22  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
23  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
24  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25  * DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
26  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
27  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
30  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
31  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32  * POSSIBILITY OF SUCH DAMAGE. 
33  * 
34  */
35
36 #ifndef _NATIVEZ_H
37 #define _NATIVEZ_H
38
39 #include <jni.h>
40
41 /**
42  * Resolves a java table created by nativez-gen 
43  */
44 int nativez_ResolveReferences(JNIEnv *env, const char *jn_names, void *jnp);
45
46 /**
47  * Support for dynamic library loading.
48  *
49  * It happens in two parts:
50  *
51  * 1. load the libraries using nativez_ResolveLibraries;
52  * 2. resolve the function pointers using nativez_ResolveFunctions.
53  *
54  */
55 typedef struct NZLibTable {
56         const char *name;       /* portable name of library */
57         const char *path;       /* platform-specific name of library file */
58         const int flags;        /* NZSO_* flags */
59         void *lib;              /* pointer to library handle */
60 } NZLibTable;
61
62 // Define NZLibTable entry.
63 #define NZSO(name, path, flags) { name, path, flags }
64 #define NZSO_END { 0 }
65
66 // non-core library, non-existance is not a failure
67 #define NZSO_NONCORE 1
68
69 /**
70  * ResolveLibraries loads libraires via a table of NZLibTable entries.
71  * The library name is platform specific.  Also see NZSO_* flags.
72  * The opened library is stored in the table[].lib.
73  * The table is terminated with an empty entry or NZSO_END.
74  */
75 int nativez_ResolveLibraries(JNIEnv *env, NZLibTable *table);
76
77 /**
78  * ResolveFunctions uses the output of nativez-gen to fill out
79  * a table.
80  */
81 int nativez_ResolveFunctions(JNIEnv *env, const NZLibTable *table, const char *fn_names, void *fnp);
82
83 // Check if function exists, return value if not and set an exception
84 #define NZCHECK_RET(env, x, ret) do { if (!nativez_NonNull(env, #x, (void *)fn.x)) { return ret; } } while (0)
85 // Call a function pointer, or just use the struct directly.
86 #define NZCALL(x) (fn.x)
87
88 /**
89  * Checks if ptr is non-null, if it is null throws a NullPointer
90  * exception with the given description and returns true.
91  */
92 int nativez_NonNull(JNIEnv *env, const char *what, void *ptr);
93
94 /**
95  * For converting array or string arguments to native pointers.
96  */
97 typedef struct nzpointer nzpointer;
98
99 struct nzpointer {
100         const jobject object;
101         union {
102                 void *v;
103                 jint *i;
104                 jfloat *f;
105                 jdouble *d;
106                 const char *U;
107                 void *N;
108         } p;
109 };
110
111 /**
112  * Retrieve pointers from java objects.
113  *
114  * desc is a string which defines the types of the arguments.
115  *
116  *   p   j*Array as GetPrimitiveArrayCritical
117  *   u   String as UTF8
118  *   n   Native.Z p pointer
119  *   P   j*Array that may not be null
120  *   U   String that may not be null
121  *   N   NativeZ that may not be null
122  *
123  * info is an array of initialsed nzpointer objects with the .object field set to the
124  * source object and the p field nullified.  Each element corresponds to the
125  * same index desc.
126  *
127  * Note: MUST always call ReleasePointers() with the same arguments regardles of return value.
128  *
129  * Returns true if all pointers were resolved successfully.
130  */
131 jboolean nativez_GetPointers(JNIEnv *env, const char *desc, nzpointer * __restrict info);
132 void nativez_ReleasePointers(JNIEnv *env, const char *desc, nzpointer *info);
133
134 /***
135  * Call GetStringUTFChars but handles null js
136  */
137 const char *nativez_GetString(JNIEnv *env, jstring js);
138
139 /**
140  * Call ReleaseStringUTFChars but handles null js
141  */
142 void nativez_ReleaseString(JNIEnv *env, jstring js, const char *s);
143
144 /**
145  * Call NewStringUTF but handle NULL s
146  */
147 jstring nativez_NewString(JNIEnv *env, const char *s);
148
149 /**
150  * Throw a basic named exception with a simple message.
151  */
152 void nativez_ThrowException(JNIEnv *env, const char *cname, const char *msg);
153 void nativez_ThrowOutOfMemoryError(JNIEnv *env, const char *msg);
154
155 /**
156  * (Byte)Buffer methods
157  */
158 jobject nativez_NewDirectBuffer(JNIEnv *env, void *data, jlong size);
159 jboolean nativez_BufferHasArray(JNIEnv *env, jobject jbuffer);
160 jboolean nativez_BufferIsDirect(JNIEnv *env, jobject jbuffer);
161 jarray nativez_BufferArray(JNIEnv *env, jobject jbuffer);
162 jint nativez_BufferArrayOffset(JNIEnv *env, jobject jbuffer);
163 jint nativez_BufferPosition(JNIEnv *env, jobject jbuffer);
164 jint nativez_BufferLimit(JNIEnv *env, jobject jbuffer);
165 void nativez_BufferSetPosition(JNIEnv *env, jobject jbuffer, jint jposition);
166 void nativez_BufferSetLimit(JNIEnv *env, jobject jbuffer, jint jlimit);
167
168 /**
169  * Allocate aligned memory, throws an exception on error.
170  */
171 void *nativez_AllocAligned(size_t align, size_t size);
172 void nativez_FreeAligned(void *mem);
173
174 /*
175   Call this in the OnLoad method
176 */
177 jint nativez_OnLoad(JavaVM *vmi, JNIEnv *env);
178
179 /*
180   Attach current thread, so it can be used in callbacks.
181  */
182 JNIEnv *nativez_AttachCurrentThread(void);
183 JNIEnv *nativez_AttachCurrentThreadAsDaemon(void);
184
185 /*
186   It is always safe to call resolve() for the freeable object case,
187   create() just implements an optimised path.
188
189   resolve() is required for objects which are refcounted on the C side.
190  */
191
192 /* Create a new object, e.g. one that has just been allocated and can't possibly already exist in java */
193 jobject NativeZ_create(JNIEnv *env, jclass jc, void *p);
194 /* Register a newly created object */
195 jobject NativeZ_register(JNIEnv *env, jobject object);
196 /* Turn a pointer into a freeable object.  If it already exists the same object will be returned */
197 jobject NativeZ_resolve(JNIEnv *env, jclass jc, void *p);
198 /* Turn a pointer into a non-freeable object.  If it already exists the same object will be returned */
199 jobject NativeZ_refer(JNIEnv *env, jclass jc, void *p);
200 /* Retreive the native pointer stored in NativeZ subclass instance jo */
201 void *NativeZ_getP(JNIEnv *env, jobject jo);
202
203 #endif