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)

outputMode に応じて、env の保留中の例外を、サイレントに、 またはスタック・バックトレースを報告する形でクリアする。 これは、ネイティブ関数の実装など、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 ポインタへのアクセスを提供する。