Struct jni_glue::Env

#[repr(transparent)]
pub struct Env(_);

FFI: Use &Env instead of *const JNIEnv. This represents a per-thread Java exection environment.

A "safe" alternative to jni_sys::JNIEnv raw pointers, with the following caveats:

1. A null env will result in undefined behavior. Java should not be invoking your native functions with a null *mut JNIEnv, however, so I don't believe this is a problem in practice unless you've bindgened the C header definitions elsewhere, calling them (requiring unsafe), and passing null pointers (generally UB for JNI functions anyways, so can be seen as a caller soundness issue.)

2. Allowing the underlying JNIEnv to be modified is undefined behavior. I don't believe the JNI libraries modify the JNIEnv, so as long as you're not accepting a *mut JNIEnv elsewhere, using unsafe to dereference it, and mucking with the methods on it yourself, I believe this "should" be fine.

Example

MainActivity.java

package com.maulingmonkey.example;
 
public class MainActivity extends androidx.appcompat.app.AppCompatActivity {
    @Override
    public native boolean dispatchKeyEvent(android.view.KeyEvent keyEvent);
 
    // ...
}

main_activity.rs

use jni_sys::{jboolean, jobject, JNI_TRUE}; // TODO: Replace with safer equivalent
use jni_glue::Env;
 
#[no_mangle] pub extern "system"
fn Java_com_maulingmonkey_example_MainActivity_dispatchKeyEvent<'env>(
    _env:       &Env,
    _this:      jobject, // TODO: Replace with safer equivalent
    _key_event: jobject  // TODO: Replace with safer equivalent
) -> jboolean {
    // ...
    JNI_TRUE
}

Methods

impl Env

pub unsafe fn from_ptr<'env>(ptr: *const JNIEnv) -> &'env Env

pub fn as_jni_env(&self) -> *mut JNIEnv

pub unsafe fn new_string(&self, chars: *const jchar, len: jsize) -> jstring

pub unsafe fn get_string_length(&self, string: jstring) -> jsize

pub unsafe fn get_string_chars(&self, string: jstring) -> *const jchar

pub unsafe fn release_string_chars(&self, string: jstring, chars: *const jchar)

pub unsafe fn require_class(&self, class: &str) -> jclass

pub unsafe fn require_method(
    &self,
    class: jclass,
    method: &str,
    descriptor: &str
) -> jmethodID

pub unsafe fn require_static_method(
    &self,
    class: jclass,
    method: &str,
    descriptor: &str
) -> jmethodID

pub unsafe fn require_field(
    &self,
    class: jclass,
    field: &str,
    descriptor: &str
) -> jfieldID

pub unsafe fn require_static_field(
    &self,
    class: jclass,
    field: &str,
    descriptor: &str
) -> jfieldID

pub unsafe fn require_class_method(
    &self,
    class: &str,
    method: &str,
    descriptor: &str
) -> (jclass, jmethodID)

pub unsafe fn require_class_static_method(
    &self,
    class: &str,
    method: &str,
    descriptor: &str
) -> (jclass, jmethodID)

pub unsafe fn require_class_field(
    &self,
    class: &str,
    method: &str,
    descriptor: &str
) -> (jclass, jfieldID)

pub unsafe fn require_class_static_field(
    &self,
    class: &str,
    method: &str,
    descriptor: &str
) -> (jclass, jfieldID)

pub unsafe fn new_object_a<'env, R: AsValidJObjectAndEnv, E: ThrowableType>(
    &'env self,
    class: jclass,
    method: jmethodID,
    args: *const jvalue
) -> Result<Local<'env, R>, Local<'env, E>>

pub unsafe fn call_object_method_a<'env, R: AsValidJObjectAndEnv, E: ThrowableType>(
    &'env self,
    this: jobject,
    method: jmethodID,
    args: *const jvalue
) -> Result<Option<Local<'env, R>>, Local<'env, E>>

pub unsafe fn call_boolean_method_a<'env, E: ThrowableType>(
    &self,
    this: jobject,
    method: jmethodID,
    args: *const jvalue
) -> Result<bool, Local<'env, E>>

pub unsafe fn call_byte_method_a<'env, E: ThrowableType>(
    &self,
    this: jobject,
    method: jmethodID,
    args: *const jvalue
) -> Result<jbyte, Local<'env, E>>

pub unsafe fn call_char_method_a<'env, E: ThrowableType>(
    &self,
    this: jobject,
    method: jmethodID,
    args: *const jvalue
) -> Result<jchar, Local<'env, E>>

pub unsafe fn call_short_method_a<'env, E: ThrowableType>(
    &self,
    this: jobject,
    method: jmethodID,
    args: *const jvalue
) -> Result<jshort, Local<'env, E>>

pub unsafe fn call_int_method_a<'env, E: ThrowableType>(
    &self,
    this: jobject,
    method: jmethodID,
    args: *const jvalue
) -> Result<jint, Local<'env, E>>

pub unsafe fn call_long_method_a<'env, E: ThrowableType>(
    &self,
    this: jobject,
    method: jmethodID,
    args: *const jvalue
) -> Result<jlong, Local<'env, E>>

pub unsafe fn call_float_method_a<'env, E: ThrowableType>(
    &self,
    this: jobject,
    method: jmethodID,
    args: *const jvalue
) -> Result<jfloat, Local<'env, E>>

pub unsafe fn call_double_method_a<'env, E: ThrowableType>(
    &self,
    this: jobject,
    method: jmethodID,
    args: *const jvalue
) -> Result<jdouble, Local<'env, E>>

pub unsafe fn call_void_method_a<'env, E: ThrowableType>(
    &self,
    this: jobject,
    method: jmethodID,
    args: *const jvalue
) -> Result<(), Local<'env, E>>

pub unsafe fn call_static_object_method_a<'env, R: AsValidJObjectAndEnv, E: ThrowableType>(
    &'env self,
    class: jclass,
    method: jmethodID,
    args: *const jvalue
) -> Result<Option<Local<'env, R>>, Local<'env, E>>

pub unsafe fn call_static_boolean_method_a<'env, E: ThrowableType>(
    &self,
    class: jclass,
    method: jmethodID,
    args: *const jvalue
) -> Result<bool, Local<'env, E>>

pub unsafe fn call_static_byte_method_a<'env, E: ThrowableType>(
    &self,
    class: jclass,
    method: jmethodID,
    args: *const jvalue
) -> Result<jbyte, Local<'env, E>>

pub unsafe fn call_static_char_method_a<'env, E: ThrowableType>(
    &self,
    class: jclass,
    method: jmethodID,
    args: *const jvalue
) -> Result<jchar, Local<'env, E>>

pub unsafe fn call_static_short_method_a<'env, E: ThrowableType>(
    &self,
    class: jclass,
    method: jmethodID,
    args: *const jvalue
) -> Result<jshort, Local<'env, E>>

pub unsafe fn call_static_int_method_a<'env, E: ThrowableType>(
    &self,
    class: jclass,
    method: jmethodID,
    args: *const jvalue
) -> Result<jint, Local<'env, E>>

pub unsafe fn call_static_long_method_a<'env, E: ThrowableType>(
    &self,
    class: jclass,
    method: jmethodID,
    args: *const jvalue
) -> Result<jlong, Local<'env, E>>

pub unsafe fn call_static_float_method_a<'env, E: ThrowableType>(
    &self,
    class: jclass,
    method: jmethodID,
    args: *const jvalue
) -> Result<jfloat, Local<'env, E>>

pub unsafe fn call_static_double_method_a<'env, E: ThrowableType>(
    &self,
    class: jclass,
    method: jmethodID,
    args: *const jvalue
) -> Result<jdouble, Local<'env, E>>

pub unsafe fn call_static_void_method_a<'env, E: ThrowableType>(
    &self,
    class: jclass,
    method: jmethodID,
    args: *const jvalue
) -> Result<(), Local<'env, E>>

pub unsafe fn get_object_field<'env, R: AsValidJObjectAndEnv>(
    &'env self,
    this: jobject,
    field: jfieldID
) -> Option<Local<'env, R>>

pub unsafe fn get_boolean_field(&self, this: jobject, field: jfieldID) -> bool

pub unsafe fn get_byte_field(&self, this: jobject, field: jfieldID) -> jbyte

pub unsafe fn get_char_field(&self, this: jobject, field: jfieldID) -> jchar

pub unsafe fn get_short_field(&self, this: jobject, field: jfieldID) -> jshort

pub unsafe fn get_int_field(&self, this: jobject, field: jfieldID) -> jint

pub unsafe fn get_long_field(&self, this: jobject, field: jfieldID) -> jlong

pub unsafe fn get_float_field(&self, this: jobject, field: jfieldID) -> jfloat

pub unsafe fn get_double_field(&self, this: jobject, field: jfieldID) -> jdouble

pub unsafe fn set_object_field<'env, 'obj, R: 'obj + AsValidJObjectAndEnv>(
    &'env self,
    this: jobject,
    field: jfieldID,
    value: impl Into<Option<&'obj R>>
)

pub unsafe fn set_boolean_field(
    &self,
    this: jobject,
    field: jfieldID,
    value: bool
)

pub unsafe fn set_byte_field(
    &self,
    this: jobject,
    field: jfieldID,
    value: jbyte
)

pub unsafe fn set_char_field(
    &self,
    this: jobject,
    field: jfieldID,
    value: jchar
)

pub unsafe fn set_short_field(
    &self,
    this: jobject,
    field: jfieldID,
    value: jshort
)

pub unsafe fn set_int_field(&self, this: jobject, field: jfieldID, value: jint)

pub unsafe fn set_long_field(
    &self,
    this: jobject,
    field: jfieldID,
    value: jlong
)

pub unsafe fn set_float_field(
    &self,
    this: jobject,
    field: jfieldID,
    value: jfloat
)

pub unsafe fn set_double_field(
    &self,
    this: jobject,
    field: jfieldID,
    value: jdouble
)

pub unsafe fn get_static_object_field<'env, R: AsValidJObjectAndEnv>(
    &'env self,
    class: jclass,
    field: jfieldID
) -> Option<Local<'env, R>>

pub unsafe fn get_static_boolean_field(
    &self,
    class: jclass,
    field: jfieldID
) -> bool

pub unsafe fn get_static_byte_field(
    &self,
    class: jclass,
    field: jfieldID
) -> jbyte

pub unsafe fn get_static_char_field(
    &self,
    class: jclass,
    field: jfieldID
) -> jchar

pub unsafe fn get_static_short_field(
    &self,
    class: jclass,
    field: jfieldID
) -> jshort

pub unsafe fn get_static_int_field(
    &self,
    class: jclass,
    field: jfieldID
) -> jint

pub unsafe fn get_static_long_field(
    &self,
    class: jclass,
    field: jfieldID
) -> jlong

pub unsafe fn get_static_float_field(
    &self,
    class: jclass,
    field: jfieldID
) -> jfloat

pub unsafe fn get_static_double_field(
    &self,
    class: jclass,
    field: jfieldID
) -> jdouble

pub unsafe fn set_static_object_field<'env, 'obj, R: 'obj + AsValidJObjectAndEnv>(
    &'env self,
    class: jclass,
    field: jfieldID,
    value: impl Into<Option<&'obj R>>
)

pub unsafe fn set_static_boolean_field(
    &self,
    class: jclass,
    field: jfieldID,
    value: bool
)

pub unsafe fn set_static_byte_field(
    &self,
    class: jclass,
    field: jfieldID,
    value: jbyte
)

pub unsafe fn set_static_char_field(
    &self,
    class: jclass,
    field: jfieldID,
    value: jchar
)

pub unsafe fn set_static_short_field(
    &self,
    class: jclass,
    field: jfieldID,
    value: jshort
)

pub unsafe fn set_static_int_field(
    &self,
    class: jclass,
    field: jfieldID,
    value: jint
)

pub unsafe fn set_static_long_field(
    &self,
    class: jclass,
    field: jfieldID,
    value: jlong
)

pub unsafe fn set_static_float_field(
    &self,
    class: jclass,
    field: jfieldID,
    value: jfloat
)

pub unsafe fn set_static_double_field(
    &self,
    class: jclass,
    field: jfieldID,
    value: jdouble
)