QJniEnvironment Class

メンバ関数ドキュメント

QJniEnvironment::QJniEnvironment()

新しい JNI Environment オブジェクトを構築し、現在のスレッドを Java VM にアタッチします。

[noexcept] QJniEnvironment::~QJniEnvironment()

現在のスレッドを Java VM から切り離し、QJniEnvironment オブジェクトを破棄します。これは、checkAndClearExceptions() を呼び出すことで、保留中の例外をクリアします。

bool QJniEnvironment::checkAndClearExceptions(QJniEnvironment::OutputMode outputMode = OutputMode::Verbose)

保留中の例外は、outputMode に応じて、サイレントに消去するか、スタック・バックトレースを報告します。

例外を内部的に処理するQJniObject とは対照的に、JNIEnv を介して直接 JNI 呼び出しを行う場合、この関数を使用して呼び出し後に潜在的な例外をクリアする必要があります。例外をスローする可能性のあるJNIEnv 呼び出しの詳細については、JNI関数を参照してください。

保留中の例外がクリアされた場合、true を返す。

[static] bool QJniEnvironment::checkAndClearExceptions(JNIEnv *env, QJniEnvironment::OutputMode outputMode = OutputMode::Verbose)

env outputModeこれは、ネイティブ関数の実装など、JNIEnv ポインタをすでに持っている場合に便利です。

内部で例外を処理するQJniObject とは対照的に、JNIEnv を介して直接 JNI 呼び出しを行う場合、この関数を使用して呼び出し後に潜在的な例外をクリアする必要があります。例外をスローする可能性のあるJNIEnv 呼び出しの詳細については、JNI関数を参照してください。

保留中の例外がクリアされた場合、true を返す。

jclass QJniEnvironment::findClass(const char *className)

利用可能なすべてのクラスローダーを使ってclassName を検索します。Qt on Android は、すべての .jar ファイルをロードするためにカスタム・クラス・ローダーを使用します。デフォルトのクラス・ローダーを使用する場合、これらのクラスは表示されないため、このクラス・ローダーによって作成されたクラスを見つけるために使用する必要があります。

クラス・ポインタを返すか、className が見つからない場合は null を返します。

この関数のユースケースは、jclass を取る JNI メソッドを呼び出すためにクラスを検索することです。これは、同じクラス・オブジェクトに対して複数の JNI 呼び出しを行う場合に便利で、各呼び出しでクラス名を使用するよりも少し速くなります。さらに、この呼び出しは、JNI 呼び出しを行う前にまず内部的にキャッシュされたクラスを探し、見つかった場合はそのようなクラスを返します。次のコード・スニペットは、CustomClass クラスのインスタンスを作成し、printFromJava() メソッドを呼び出します：

QJniEnvironment env;
jclass javaClass = env.findClass("org/qtproject/example/android/CustomClass");
QJniObject javaMessage = QJniObject::fromString("findClass example");
QJniObject::callStaticMethod<void>(javaClass, "printFromJava",
                                   "(Ljava/lang/String;)V", javaMessage.object<jstring>());

[since 6.4] template <typename T> jfieldID QJniEnvironment::findField(jclass clazz, const char *fieldName)

clazz クラスのメンバ・フィールドを検索します。フィールドはfieldName で指定されます。フィールドのシグニチャは、テンプレート・パラメータから推測されます。

フィールドが見つからない場合は、フィールド ID またはnullptr を返します。

この関数は Qt 6.4 で導入されました。

[since 6.2] jfieldID QJniEnvironment::findField(jclass clazz, const char *fieldName, const char *signature)

clazz クラスのメンバ・フィールドを検索します。フィールドはfieldName とsignature で指定されます。

フィールドが見つからない場合は、フィールド ID またはnullptr を返します。

このメソッドの使用例としては、クラスのフィールドを検索してその ID をキャッシュし、後でフィールドの取得や設定に使用できるようにすることが挙げられます。

この関数は Qt 6.2 で導入されました。

[since 6.4] template <typename... Args> jmethodID QJniEnvironment::findMethod(jclass clazz, const char *methodName)

クラスのインスタンス・メソッドを検索するclazz 。メソッドはmethodName で指定され、シグネチャはテンプレート・パラメータから推測されます。

メソッドが見つからない場合は、メソッド ID またはnullptr を返します。

この関数は Qt 6.4 で導入されました。

[since 6.2] jmethodID QJniEnvironment::findMethod(jclass clazz, const char *methodName, const char *signature)

clazz クラスのインスタンス・メソッドを検索します。メソッドはmethodName とsignature で指定されます。

メソッドが見つからない場合は、メソッド ID またはnullptr を返します。

このメソッドの使用例としては、クラス・メソッドを検索してその ID をキャッシュし、後でメソッドを呼び出す際に使用できるようにすることが挙げられます。

この関数は Qt 6.2 で導入されました。

[since 6.4] template <typename T> jfieldID QJniEnvironment::findStaticField(jclass clazz, const char *fieldName)

clazz クラスの静的フィールドを検索します。フィールドはfieldName で指定されます。フィールドのシグニチャは、テンプレート・パラメーターから推測されます。

フィールドが見つからない場合は、フィールド ID またはnullptr を返します。

この関数は Qt 6.4 で導入されました。

[since 6.2] jfieldID QJniEnvironment::findStaticField(jclass clazz, const char *fieldName, const char *signature)

clazz クラスの静的フィールドを検索します。フィールドはfieldName とsignature で指定されます。

フィールドが見つからない場合は、フィールド ID またはnullptr を返します。

このメソッドの使用例としては、クラスのフィールドを検索してその ID をキャッシュし、後でフィールドの取得や設定に使用できるようにすることが挙げられます。

この関数は Qt 6.2 で導入されました。

[since 6.4] template <typename... Args> jmethodID QJniEnvironment::findStaticMethod(jclass clazz, const char *methodName)

クラスのインスタンス・メソッドを検索するclazz 。メソッドはmethodName で指定され、シグネチャはテンプレート・パラメータから推測されます。

メソッドが見つからない場合は、メソッド ID またはnullptr を返します。

QJniEnvironment env;
jclass javaClass = env.findClass("org/qtproject/example/android/CustomClass");
jmethodID methodId = env.findStaticMethod<void, jstring>(javaClass, "staticJavaMethod");
QJniObject javaMessage = QJniObject::fromString("findStaticMethod example");
QJniObject::callStaticMethod<void>(javaClass,
                                   methodId,
                                   javaMessage.object<jstring>());

この関数は Qt 6.4 で導入されました。

[since 6.2] jmethodID QJniEnvironment::findStaticMethod(jclass clazz, const char *methodName, const char *signature)

clazz クラスの静的メソッドを検索します。メソッドはmethodName とsignature で指定されます。

メソッドが見つからない場合は、メソッド ID またはnullptr を返します。

このメソッドの使用例としては、クラス・メソッドを検索してその ID をキャッシュし、後でメソッドを呼び出す際に使用できるようにすることが挙げられます。

QJniEnvironment env;
jclass javaClass = env.findClass("org/qtproject/example/android/CustomClass");
jmethodID methodId = env.findStaticMethod(javaClass,
                                          "staticJavaMethod",
                                          "(Ljava/lang/String;)V");
QJniObject javaMessage = QJniObject::fromString("findStaticMethod example");
QJniObject::callStaticMethod<void>(javaClass,
                                   methodId,
                                   javaMessage.object<jstring>());

この関数は Qt 6.2 で導入されました。

[static] JNIEnv *QJniEnvironment::getJniEnv()

現在のスレッドのJNIEnvポインタを返します。

現在のスレッドはJava VMにアタッチされます。

[since 6.2] bool QJniEnvironment::isValid() const

このインスタンスが有効なJNIEnvオブジェクトを保持している場合、true 。

この関数はQt 6.2で導入されました。

[static] JavaVM *QJniEnvironment::javaVM()

現在のプロセスのJava VMインタフェースを返します。プロセスごとに複数のJava VMを持つことが可能な場合もありますが、Androidでは1つしか許されていません。

JNIEnv *QJniEnvironment::jniEnv() const

JNI EnvironmentのJNIEnv ポインターを返します。

template <typename Class> bool QJniEnvironment::registerNativeMethods(std::initializer_list<JNINativeMethod> methods)

これはオーバーロードされた関数です。

Class で表されるJavaクラスにmethods のJavaメソッドを登録し、登録が成功したかどうかを返す。

Class 型は、Q_DECLARE_JNI_CLASS マクロを使用して、QtJniTypes 名前空間内で宣言する必要があります。自由な C または C++ 関数として実装される関数は、Q_DECLARE_JNI_NATIVE_METHOD マクロのいずれかを使用して宣言し、Q_JNI_NATIVE_METHOD マクロを使用して登録に渡す必要があります。

// C++ side

Q_DECLARE_JNI_CLASS(MyJavaType, "my/java/Type")

static void nativeFunction(JNIEnv *env, jobject thiz, jlong id)
{
    // ...
}
Q_DECLARE_JNI_NATIVE_METHOD(nativeFunction)

Q_DECL_EXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved)
{
    QJniEnvironment env;
    env.registerNativeMethods<QtJniTypes::MyJavaType>({
        Q_JNI_NATIVE_METHOD(nativeFunction)
    });
}

// Java side
public class MyJavaType
{
    native public nativeFunction(long id);
}

静的なクラス・メンバ関数として実装された関数は、macros for scoped functions を使用してください。

class NativeHandler
{
    // ...
private:
    static void handleChange(JNIEnv*, jobject, jlong id);
    Q_DECLARE_JNI_NATIVE_METHOD_IN_CURRENT_SCOPE(handleChange)
};

\dots
QJniEnvironment env;
env.registerNativeMethods<QtJniTypes::MyJavaType>({
    Q_JNI_NATIVE_SCOPED_METHOD(handleChange, NativeHandler)
});

bool QJniEnvironment::registerNativeMethods(const char *className, std::initializer_list<JNINativeMethod> methods)

これはオーバーロードされた関数です。

Java クラスclassName に対してmethods のネイティブ関数メソッドを登録する。登録が成功すればtrue を返し、そうでなければfalse を返します。

bool QJniEnvironment::registerNativeMethods(jclass clazz, std::initializer_list<JNINativeMethod> methods)

これはオーバーロードされた関数です。

Java クラスclazz に対してmethods のネイティブ関数メソッドを登録します。登録に成功した場合はtrue を返し、そうでない場合はfalse を返します。

bool QJniEnvironment::registerNativeMethods(const char *className, const JNINativeMethod[] methods, int size)

これはオーバーロードされた関数です。

サイズsize の配列methods 内の Java メソッドを登録します。各メソッドは、クラスclassName からのネイティブ C++ 関数を呼び出すことができます。これらのメソッドは、呼び出す前に登録する必要があります。

登録に成功した場合はtrue を返し、失敗した場合はfalse を返します。

メソッド配列の各要素は、以下から構成されます：

• Java メソッド名
• メソッド・シグネチャ
• 実行される C++ 関数

const JNINativeMethod methods[] =
                        {{"callNativeOne", "(I)V", reinterpret_cast<void *>(fromJavaOne)},
                        {"callNativeTwo", "(I)V", reinterpret_cast<void *>(fromJavaTwo)}};
QJniEnvironment env;
env.registerNativeMethods("org/qtproject/android/TestJavaClass", methods, 2);

bool QJniEnvironment::registerNativeMethods(jclass clazz, const JNINativeMethod[] methods, int size)

これはオーバーロードされた関数です。

このオーバーロードは、以前にキャッシュされた jclass インスタンスclazz を使用します。

JNINativeMethod methods[] {{"callNativeOne", "(I)V", reinterpret_cast<void *>(fromJavaOne)},
                           {"callNativeTwo", "(I)V", reinterpret_cast<void *>(fromJavaTwo)}};
QJniEnvironment env;
jclass clazz = env.findClass("org/qtproject/android/TestJavaClass");
env.registerNativeMethods(clazz, methods, 2);

JNIEnv &QJniEnvironment::operator*() const

JNI Environment のJNIEnv オブジェクトを返します。

JNIEnv *QJniEnvironment::operator->() const

JNI Environment のJNIEnv ポインタへのアクセスを提供します。