Java Native Interface 仕様

4 - JNI 関数

この章は、JNI の関数のリファレンスです。この章では、JNI の関数をすべて取り上げます。また、JNI 関数テーブルの配置そのままに記載されています。

「しなければならない」(または「する必要がある」) という表現は、JNI プログラマに対する制約を表していることに注意してください。たとえば、ある JNI 関数について、それが NULL 以外のオブジェクトを受け取らなければならないと説明されている場合、プログラマの責任において、その JNI 関数に NULL を渡さないようにしなければならないという意味になります。それによって、JNI 実装の際に、その JNI 関数における NULL のポインタチェックを行う必要がなくなります。

この章の一部は Netscape^TM の JRI ドキュメントから改作したものです。

参照資料は、関数を用途によってグループ化しています。参照セクションは、次の機能分野から構成されています。

インタフェース関数テーブル

各関数には、JNIEnv 引数を介し、固定オフセットでアクセスすることが可能です。JNIEnv 型は、すべての JNI 関数のポインタを格納する構造体を指すポインタです。これは次のように定義されます。

    typedef const struct JNINativeInterface *JNIEnv;

VM は、コード例 4-1 に示されているように関数テーブルを初期化します。最初の 3 エントリは、将来の COM との互換性のために予約されていることに注意してください。さらに、関数テーブルの始めの近辺にいくつかの追加の NULL エントリを予約してあります。したがって、たとえば、これから現われる、クラス関連の JNI 演算は、表の終わりではなく FindClass のあとに追加することができます。

関数テーブルは、すべての JNI インタフェースポインタの間で共用されることに注意してください。

コード例 4-1
const struct JNINativeInterface ... = {
NULL,
NULL,
NULL,
NULL,
GetVersion,

DefineClass,
FindClass,
NULL,
NULL,
NULL,
GetSuperclass,
IsAssignableFrom,
NULL,

Throw,
ThrowNew,
ExceptionOccurred,
ExceptionDescribe,
ExceptionClear,
FatalError,
NULL,
NULL,

NewGlobalRef,
DeleteGlobalRef,
DeleteLocalRef,
IsSameObject,
NULL,
NULL,

AllocObject,
NewObject,
NewObjectV,
NewObjectA,

GetObjectClass,
IsInstanceOf,

GetMethodID,

CallObjectMethod,
CallObjectMethodV,
CallObjectMethodA,
CallBooleanMethod,
CallBooleanMethodV,
CallBooleanMethodA,
CallByteMethod,
CallByteMethodV,
CallByteMethodA,
CallCharMethod,
CallCharMethodV,
CallCharMethodA,
CallShortMethod,
CallShortMethodV,
CallShortMethodA,
CallIntMethod,
CallIntMethodV,
CallIntMethodA,
CallLongMethod,
CallLongMethodV,
CallLongMethodA,
CallFloatMethod,
CallFloatMethodV,
CallFloatMethodA,
CallDoubleMethod,
CallDoubleMethodV,
CallDoubleMethodA,
CallVoidMethod,
CallVoidMethodV,
CallVoidMethodA,

CallNonvirtualObjectMethod,
CallNonvirtualObjectMethodV,
CallNonvirtualObjectMethodA,
CallNonvirtualBooleanMethod,
CallNonvirtualBooleanMethodV,
CallNonvirtualBooleanMethodA,
CallNonvirtualByteMethod,
CallNonvirtualByteMethodV,
CallNonvirtualByteMethodA,
CallNonvirtualCharMethod,
CallNonvirtualCharMethodV,
CallNonvirtualCharMethodA,
CallNonvirtualShortMethod,
CallNonvirtualShortMethodV,
CallNonvirtualShortMethodA,
CallNonvirtualIntMethod,
CallNonvirtualIntMethodV,
CallNonvirtualIntMethodA,
CallNonvirtualLongMethod,
CallNonvirtualLongMethodV,
CallNonvirtualLongMethodA,
CallNonvirtualFloatMethod,
CallNonvirtualFloatMethodV,
CallNonvirtualFloatMethodA,
CallNonvirtualDoubleMethod,
CallNonvirtualDoubleMethodV,
CallNonvirtualDoubleMethodA,
CallNonvirtualVoidMethod,
CallNonvirtualVoidMethodV,
CallNonvirtualVoidMethodA,

GetFieldID,

GetObjectField,
GetBooleanField,
GetByteField,
GetCharField,
GetShortField,
GetIntField,
GetLongField,
GetFloatField,
GetDoubleField,
SetObjectField,
SetBooleanField,
SetByteField,
SetCharField,
SetShortField,
SetIntField,
SetLongField,
SetFloatField,
SetDoubleField,

GetStaticMethodID,

CallStaticObjectMethod,
CallStaticObjectMethodV,
CallStaticObjectMethodA,
CallStaticBooleanMethod,
CallStaticBooleanMethodV,
CallStaticBooleanMethodA,
CallStaticByteMethod,
CallStaticByteMethodV,
CallStaticByteMethodA,
CallStaticCharMethod,
CallStaticCharMethodV,
CallStaticCharMethodA,
CallStaticShortMethod,
CallStaticShortMethodV,
CallStaticShortMethodA,
CallStaticIntMethod,
CallStaticIntMethodV,
CallStaticIntMethodA,
CallStaticLongMethod,
CallStaticLongMethodV,
CallStaticLongMethodA,
CallStaticFloatMethod,
CallStaticFloatMethodV,
CallStaticFloatMethodA,
CallStaticDoubleMethod,
CallStaticDoubleMethodV,
CallStaticDoubleMethodA,
CallStaticVoidMethod,
CallStaticVoidMethodV,
CallStaticVoidMethodA,

GetStaticFieldID,

GetStaticObjectField,
GetStaticBooleanField,
GetStaticByteField,
GetStaticCharField,
GetStaticShortField,
GetStaticIntField,
GetStaticLongField,
GetStaticFloatField,
GetStaticDoubleField,

SetStaticObjectField,
SetStaticBooleanField,
SetStaticByteField,
SetStaticCharField,
SetStaticShortField,
SetStaticIntField,
SetStaticLongField,
SetStaticFloatField,
SetStaticDoubleField,

NewString,
GetStringLength,
GetStringChars,
ReleaseStringChars,

NewStringUTF,
GetStringUTFLength,
GetStringUTFChars,
ReleaseStringUTFChars,

GetArrayLength,

NewObjectArray,
GetObjectArrayElement,
SetObjectArrayElement,

NewBooleanArray,
NewByteArray,
NewCharArray,
NewShortArray,
NewIntArray,
NewLongArray,
NewFloatArray,
NewDoubleArray,

GetBooleanArrayElements,
GetByteArrayElements,
GetCharArrayElements,
GetShortArrayElements,
GetIntArrayElements,
GetLongArrayElements,
GetFloatArrayElements,
GetDoubleArrayElements,

ReleaseBooleanArrayElements,
ReleaseByteArrayElements,
ReleaseCharArrayElements,
ReleaseShortArrayElements,
ReleaseIntArrayElements,
ReleaseLongArrayElements,
ReleaseFloatArrayElements,
ReleaseDoubleArrayElements,

GetBooleanArrayRegion,
GetByteArrayRegion,
GetCharArrayRegion,
GetShortArrayRegion,
GetIntArrayRegion,
GetLongArrayRegion,
GetFloatArrayRegion,
GetDoubleArrayRegion,
SetBooleanArrayRegion,
SetByteArrayRegion,
SetCharArrayRegion,
SetShortArrayRegion,
SetIntArrayRegion,
SetLongArrayRegion,
SetFloatArrayRegion,
SetDoubleArrayRegion,

RegisterNatives,
UnregisterNatives,

MonitorEnter,
MonitorExit,

GetJavaVM,
};

バージョン情報

GetVersion

jint GetVersion(JNIEnv *env);

ネイティブメソッドインタフェースのバージョンを返します。

パラメータ:

env: JNI インタフェースポインタ

戻り値:

メジャーバージョン番号を高位の 16 ビットで、マイナーバージョン番号を下位の 16 ビットで返します。

JDK 1.1 では、GetVersion() が 0x00010001 を返します。

クラスオペレーション

DefineClass

jclass DefineClass(JNIEnv *env, jobject loader, 

     const jbyte *buf, jsize bufLen);

raw クラスデータのバッファからクラスをロードします。

パラメータ:

env: JNI インタフェースポインタ

loader: 定義されたクラスに割り当てられるクラスローダ

buf: .classファイルデータを含むバッファ

bufLen: バッファ長

戻り値:

クラスオブジェクトを返します。エラーが発生した場合は NULL を返します。

例外:

ClassFormatError: クラスデータが有効なクラスを指定しなかった場合

ClassCircularityError: クラスまたはインタフェースが、それ自体のスーパークラスまたはスーパーインタフェースになる場合

OutOfMemoryError: システムがメモリ不足の場合

FindClass

jclass FindClass(JNIEnv *env, const char *name);

この関数は、局所的に定義されたクラスをロードします。また、指定された名前を持つクラスに対して CLASSPATH 環境変数が指定するディレクトリおよび ZIP ファイルを検索します。

パラメータ:

env: JNI インタフェースポインタ

name: 完全修飾クラス名 (「/」で区切ったあとにクラス名を付けたパッケージ名)。その名前が「[」(配列シグニチャー文字) で開始されている場合は、配列クラスを返します。

戻り値:

完全修飾名からクラスオブジェクトを返します。クラスが見つからない場合は、NULL を返します。

例外:

ClassFormatError: クラスデータが有効なクラスを指定しなかった場合

ClassCircularityError: クラスまたはインタフェースが、それ自体のスーパークラスまたはスーパーインタフェースになる場合

NoClassDefFoundError: 要求されたクラスまたはインタフェースに対する定義が見つからなかった場合

OutOfMemoryError: システムがメモリ不足の場合

GetSuperclass

jclass GetSuperclass(JNIEnv *env, jclass clazz);

clazz がクラス Object 以外のクラスを表す場合、この関数は、clazz によって指定されたクラスのスーパークラスを表すオブジェクトを返します。

clazz がクラス Object を指定する場合、または、clazz がインタフェースを表す場合は、この関数は NULL を返します。

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

戻り値:

clazz によって表されるクラスのスーパークラスまたは NULL を返します。

IsAssignableFrom

jboolean IsAssignableFrom(JNIEnv *env, jclass clazz1, 

     jclass clazz2);

clazz1 のオブジェクトが安全に clazz2 へキャストされるかどうかを決定します。

パラメータ:

env: JNI インタフェースポインタ

clazz1: 最初のクラス引数

clazz2: 2 番目のクラス引数

戻り値:

次のいずれかが真の場合に JNI_TRUE を返します。

最初と 2 番目のクラス引数が同じ Java クラスを表している
最初のクラスが 2 番目のクラスのサブクラスである
最初のクラスがそのインタフェースとして 2 番目のクラスを持っている

例外

Throw

jint Throw(JNIEnv *env, jthrowable obj);

java.lang.Throwable オブジェクトがスローされます。

パラメータ:

env: JNI インタフェースポインタ

obj: java.lang.Throwable オブジェクト

戻り値:

成功の場合は 0 を返し、失敗の場合は負の値を返します。

例外:

 java.lang.Throwable Object obj

ThrowNew

jint ThrowNew(JNIEnv *env, jclass clazz, 

     const char *message);

message によって指定されたメッセージを使用して、指定されたクラスから例外オブジェクトを構築し、その例外がスローされるようにします。

パラメータ:

env: JNI インタフェースポインタ

clazz: java.lang.Throwable のサブクラス

message: java.lang.Throwable オブジェクトの構築に使用するメッセージ

戻り値:

成功の場合は 0 を返し、失敗の場合は負の値を返します。

例外:

新しく構築された java.lang.Throwable オブジェクト

ExceptionOccurred

jthrowable ExceptionOccurred(JNIEnv *env);

例外がスローされるかどうかを決定します。例外は、ネイティブコードが ExceptionClear() を呼び出すか、または Java コードがその例外を処理するまでスローされた状態を続けます。

パラメータ:

env: JNI インタフェースポインタ

戻り値:

現在スローされている例外オブジェクトを返します。現在、スローされている例外がない場合は、NULL を返します。

ExceptionDescribe

void ExceptionDescribe(JNIEnv *env);

stderr など、例外およびスタックのバックトレースをシステムエラーのレポーティングチャネルにプリントします。これは、デバッグのために提供されている便利なルーチンです。

パラメータ:

env: JNI インタフェースポインタ

ExceptionClear

void ExceptionClear(JNIEnv *env);

現在スローされている例外があればそれをクリアします。現在スローされている例外がない場合は、このルーチンは影響を及ぼしません。

パラメータ:

env: JNI インタフェースポインタ

FatalError

void FatalError(JNIEnv *env, const char *msg);

致命的エラーを発生させます。VM による回復は期待されません。この関数は値を返しません。

パラメータ:

env: JNI インタフェースポインタ

msg: エラーメッセージ

グローバル参照およびローカル参照

NewGlobalRef

jobject NewGlobalRef(JNIEnv *env, jobject obj);

obj 引数によって参照されたオブジェクトの新しいグローバル参照を作成します。obj 引数は、グローバル参照またはローカル参照のどちらでも構いません。グローバル参照は、DeleteGlobalRef() を呼び出すことによって、必ず明示的に処理しておく必要があります。

パラメータ:

env: JNI インタフェースポインタ

obj: グローバル参照またはローカル参照

戻り値:

グローバル参照を返します。システムがメモリ不足の場合は NULL を返します。

DeleteGlobalRef

void DeleteGlobalRef(JNIEnv *env, jobject globalRef);

globalRef によって示されたグローバル参照を削除します。

パラメータ:

env: JNI インタフェースポインタ

globalRef: グローバル参照

DeleteLocalRef

void DeleteLocalRef(JNIEnv *env, jobject localRef);

localRef によって示されたローカル参照を削除します。

パラメータ:

env: JNI インタフェースポインタ

localRef: ローカル参照

オブジェクトオペレーション

AllocObject

jobject AllocObject(JNIEnv *env, jclass clazz);

オブジェクト用としてコンストラクタを呼び出さずに、新しい Java オブジェクトを割り当てます。オブジェクトに対する参照を返します。

clazz 引数は、配列クラスを参照してはなりません。

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

戻り値:

Java オブジェクトを返します。オブジェクトが構築できない場合は NULL を返します。

例外:

InstantiationException: クラスがインタフェースまたは abstract クラスの場合

OutOfMemoryError: システムがメモリ不足の場合

NewObject
NewObjectA
NewObjectV

jobject NewObject(JNIEnv *env, jclass clazz, 

     jmethodID methodID, ...);

jobject NewObjectA(JNIEnv *env, jclass clazz, jmethodID methodID, jvalue *args);

jobject NewObjectV(JNIEnv *env, jclass clazz, jmethodID methodID, va_list args);

Java オブジェクトを構築します。メソッド ID は、呼び出すべきコンストラクタメソッドを表しています。この ID は、メソッド名として <init> を、また戻り値の型として void (V) を使用して GetMethodID() を呼び出すことによって取得しなければなりません。

clazz 引数は、配列クラスを参照してはなりません。

NewObject

プログラマは、コンストラクタに渡す引数をすべて、methodID 引数のすぐあとに置きます。 NewObject() は、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

NewObjectA

プログラマは、コンストラクタに渡す引数をすべて、methodID 引数のすぐあとに続く jvalues の args 配列内に置きます。 NewObjectA() はこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

NewObjectV

プログラマは、コンストラクタに渡す引数をすべて、methodID 引数のすぐあとに続く型 va_list の args 引数内に置きます。 NewObjectV() はこれらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

methodID: コンストラクタのメソッド ID

NewObject に必要な追加パラメータ:

コンストラクタの引数

NewObjectA に必要な追加パラメータ:

args: コンストラクタの引数の配列

NewObjectV に必要な追加パラメータ:

args: コンストラクタの引数の va_list

戻り値:

Java オブジェクトを返します。Java オブジェクトが構築できなかった場合は、 NULL を返します。

例外:

InstantiationException: クラスがインタフェースまたは abstract クラスの場合

OutOfMemoryError: システムがメモリ不足の場合

コンストラクタによってスローされるすべての例外

GetObjectClass

jclass GetObjectClass(JNIEnv *env, jobject obj);

オブジェクトのクラスを返します。

パラメータ:

env: JNI インタフェースポインタ

obj: Java オブジェクト (NULL であってはならない)

戻り値:

Java クラスオブジェクトを返します。

IsInstanceOf

jboolean IsInstanceOf(JNIEnv *env, jobject obj, 

     jclass clazz);

オブジェクトがクラスのインスタンスであるかどうかをチェックします。

パラメータ:

env: JNI インタフェースポインタ

obj: Java オブジェクト

clazz: Java クラスオブジェクト

戻り値:

obj を clazz にキャストすることができる場合は、JNI_TRUE を返します。そうでない場合は、 JNI_FALSE を返します。NULL オブジェクトは、どのクラスにもキャストすることができます。

IsSameObject

jboolean IsSameObject(JNIEnv *env, jobject ref1, 

     jobject ref2);

2 つの参照が同じ Java オブジェクトを参照するかどうかをテストします。

パラメータ:

env: JNI インタフェースポインタ

ref1: Java オブジェクト

ref2: Java オブジェクト

戻り値:

ref1 と ref2 が同じ Java オブジェクトを参照する場合、または、両方が NULL である場合は、JNI_TRUE を返します。それ以外の場合は、JNI_FALSE を返します。

オブジェクトのフィールドへのアクセス

GetFieldID

jfieldID GetFieldID(JNIEnv *env, jclass clazz, 

     const char *name, const char *sig);

クラスのインスタンス (非 static) フィールドを表すフィールド ID を返します。このフィールドは、その名前およびシグニチャーで指定します。アクセス用関数の Get<type>Field ファミリと Set<type>Field ファミリは、フィールド ID を使用してオブジェクトフィールドを検索します。

GetFieldID() によって、まだ初期化されていないクラスが初期化されます。

配列の長さフィールドを得るために GetFieldID() を使用することはできません。代わりに、 GetArrayLength() を使用してください。

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

name: 0 で終了する UTF-8 文字列内のフィールド名

sig: 0 で終了する UTF-8 文字列内のフィールドシグニチャー

戻り値:

フィールド ID を返します。演算が失敗した場合は NULL を返します。

例外:

NoSuchFieldError: 指定されたフィールドが見つからない場合

ExceptionInInitializerError: 例外のために、クラス初期化が失敗した場合

OutOfMemoryError: システムがメモリ不足の場合

Get<type>Field ルーチン

NativeType Get<type>Field

(JNIEnv *env, jobject obj, 

     jfieldID fieldID);

このアクセス用ルーチンのファミリは、オブジェクトのインスタンス (非 static) フィールドの値を返します。アクセスすべきフィールドは、GetFieldID() を呼び出すことによって取得されるフィールド ID を使用して指定します。

次の表には、Get<type>Field ルーチン名と結果の型が示されています。Get<type>Field 内の type をフィールドの Java 型と置き換えるか、あるいは表の実際のルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-1 アクセス用ルーチンの Get<type>Field ファミリ

Get<type>Field ルーチン名ネイティブ型
GetObjectField() jobject
GetBooleanField() jboolean
GetByteField() jbyte
GetCharField() jchar
GetShortField() jshort
GetIntField() jint
GetLongField() jlong
GetFloatField() jfloat
GetDoubleField() jdouble

表 4-1 アクセス用ルーチンの Get<type>Field ファミリ
Get<type>Field ルーチン名	ネイティブ型
`GetObjectField()`	jobject
`GetBooleanField()`	jboolean
`GetByteField()`	jbyte
`GetCharField()`	jchar
`GetShortField()`	jshort
`GetIntField()`	jint
`GetLongField()`	jlong
`GetFloatField()`	jfloat
`GetDoubleField()`	jdouble

パラメータ:

env: JNI インタフェースポインタ

obj: Java オブジェクト (NULL であってはならない)

fieldID: 有効フィールド ID

戻り値:

フィールドの内容を返します。

Set<type>Field ルーチン

void Set<type>Field

(JNIEnv *env, jobject obj, jfieldID fieldID,

NativeType

 value);

このアクセス用ルーチンのファミリは、オブジェクトのインスタンス (非 static) フィールドの値を設定します。アクセスすべきフィールドは、 GetFieldID() を呼び出すことによって得られるフィールド ID を使用して指定します。

次の表には、Set<type>Field ルーチン名と結果の型が示されています。Set<type>Field 内の type をフィールドの Java 型と置き換えるか、あるいは表の実際のルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-2 アクセス用ルーチンの Set<type>Field ファミリ
Set<type>Field ルーチン	ネイティブ型
`SetObjectField()`	jobject
S`etBooleanField()`	jboolean
`SetByteField()`	jbyte
`SetCharField()`	jchar
`SetShortField()`	jshort
`SetIntField()`	jint
`SetLongField()`	jlong
`SetFloatField()`	jfloat
`SetDoubleField()`	jdouble

パラメータ:

env: JNI インタフェースポインタ

obj: Java オブジェクト (NULL であってはならない)

fieldID: 有効フィールド ID

value: そのフィールドの新しい値

インスタンスメソッドの呼び出し

GetMethodID

jmethodID GetMethodID(JNIEnv *env, jclass clazz, 

     const char *name, const char *sig);

クラスまたはインタフェースのインスタンス (非 static) メソッドを表すメソッド ID を返します。このメソッドは、clazz のスーパークラスの 1 つの中で定義し、clazz によって継承できます。このメソッドは、その名前およびシグニチャーによって決定されます。

GetMethodID() によって、まだ初期化されていないクラスが初期化されます。

コンストラクタのメソッド ID を取得するには、メソッド名として <init> を指定し、戻り値の型として void (V) を指定します。

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

name: 0 で終了する UTF-8 文字列内のメソッド名

sig: 0 で終了する UTF-8 文字列内のメソッドシグニチャー

戻り値:

メソッド ID を返します。指定されたメソッドが見つからなかった場合は、NULL を返します。

例外:

NoSuchMethodError: 指定されたメソッドが見つからない場合

ExceptionInInitializerError: 例外のために、クラス初期化が失敗した場合

OutOfMemoryError: システムがメモリ不足の場合

Call<type>Method ルーチン
Call<type>MethodA ルーチン
Call<type>MethodV ルーチン

NativeType Call<type>Method

(JNIEnv *env, jobject obj, 

     jmethodID methodID, ...);

NativeType Call<type>MethodA(JNIEnv *env, jobject obj, jmethodID methodID, jvalue *args);

NativeType Call<type>MethodV(JNIEnv *env, jobject obj, jmethodID methodID, va_list args);

これら 3 種類の演算ファミリは、ネイティブメソッドから Java インスタンスメソッドを呼び出す際に使用されます。これら 3 種類のファミリは、呼び出したメソッドにパラメータを渡す機構が異なるだけです。

これらの演算ファミリは、指定されたメソッド ID に従って、Java オブジェクト上のインスタンス (非 static) メソッドを呼び出します。methodID 引数は、GetMethodID() を呼び出すことによって取得する必要があります。

これらの関数を private メソッドやコンストラクタを呼び出すために使用する場合は、メソッド ID を obj の実クラスのスーパークラスの 1 つからではなく、実クラス自体から導き出す必要があります。

Call<type>Method ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数のすぐあとに置きます。Call<type>Method ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

Call<type>MethodA ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数のすぐあとに続く jvalues の args 配列内に置きます。Call<type>MethodA ルーチンはこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

Call<type>MethodV ルーチン

プログラマは、そのメソッドに渡す引数をすべて、methodID 引数のすぐあとに続く型 va_list の args 引数内に置きます。Call<type>MethodV ルーチンはこれらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

次の表には、メソッド呼び出しルーチンの各々がその結果の型に応じて示されています。Call<type>Method 内の type を呼び出しているメソッドの Java 型と置き換え (または、表の実際のメソッド呼び出しルーチン名の 1 つを使用する)、かつ NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-3 インスタンスメソッドを呼び出すルーチン
Call<type>Method ルーチン名	ネイティブ型
`CallVoidMethod()` `CallVoidMethodA()` `CallVoidMethodV()`	void
`CallObjectMethod()` `CallObjectMethodA()` `CallObjectMethodV()`	jobject
`CallBooleanMethod()` `CallBooleanMethodA()` `CallBooleanMethodV()`	jboolean
`CallByteMethod()` `CallByteMethodA()` `CallByteMethodV()`	jbyte
`CallCharMethod()` `CallCharMethodA()` `CallCharMethodV()`	jchar
`CallShortMethod()` `CallShortMethodA()` `CallShortMethodV()`	jshort
`CallIntMethod()` `CallIntMethodA()` `CallIntMethodV()`	jint
`CallLongMethod()` `CallLongMethodA()` `CallLongMethodV()`	jlong
`CallFloatMethod()` `CallFloatMethodA()` `CallFloatMethodV()`	jfloat
`CallDoubleMethod()` `CallDoubleMethodA()` `CallDoubleMethodV()`	jdouble

パラメータ:

env: JNI インタフェースポインタ

obj: Java オブジェクト

methodID: メソッド ID

Call<type>Method ルーチンに必要な追加パラメータ:

Java メソッドの引数

Call<type>MethodA ルーチンに必要な追加パラメータ:

args: 引数の配列

Call<type>MethodV ルーチンに必要な追加パラメータ:

args: 引数の va_list

戻り値:

Java メソッドを呼び出した結果を返します。

例外:

Java メソッドを実行している間に発生した例外

CallNonvirtual<type>Method ルーチン
CallNonvirtual<type>MethodA ルーチン
CallNonvirtual<type>MethodV ルーチン

NativeType CallNonvirtual<type>Method

(JNIEnv *env, jobject obj, 

     jclass clazz, jmethodID methodID, ...);

NativeType CallNonvirtual<type>MethodA(JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, jvalue *args);

NativeType CallNonvirtual<type>MethodV(JNIEnv *env, jobject obj, jclass clazz, jmethodID methodID, va_list args);

これらの演算ファミリは、指定されたクラスおよびメソッド ID に従って、Java オブジェクト上のインスタンス (非 static) メソッドを呼び出します。methodID 引数は、clazz 上の GetMethodID() を呼び出すことによって取得する必要があります。

CallNonvirtual<type>Method ルーチンファミリと Call<type>Method ルーチンファミリとは異なります。Call<type>Method ルーチンは、オブジェクトのクラスに基づいてメソッドを呼び出しますが、CallNonvirtual<type>Method ルーチンの方は、メソッド ID が得られるクラス (clazz パラメータによって指定) に基づいてメソッドを呼び出します。メソッド ID は、このオブジェクトの実クラスまたはその実クラスのスーパークラスの 1 つから取得しなければなりません。

CallNonvirtual<type>Method ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数のすぐあとに置きます。CallNonvirtual<type>Method ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

CallNonvirtual<type>MethodA ルーチン

プログラマは、メソッドに渡す引数をすべて、methodID 引数のすぐあとに続く jvalues の args 配列内に置きます。CallNonvirtual<type>MethodA ルーチンはこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドにそれらを渡します。

CallNonvirtual<type>MethodV ルーチン

プログラマは、そのメソッドに渡す引数をすべて、methodID 引数のすぐあとに続く型 va_list の args 引数内に置きます。CallNonvirtualMethodV ルーチンはこれらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

次の表には、メソッド呼び出しルーチンの各々がその結果の型に応じて示されています。CallNonvirtual<type>Method 内の type をメソッドの Java 型と置き換えるか、あるいは表から実際のメソッド呼び出しルーチン名の 1 つを使用して、 NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-4 CallNonvirtual<type>Method ルーチン
CallNonvirtual<type>Method ルーチン名	ネイティブ型
`CallNonvirtualVoidMethod()` `CallNonvirtualVoidMethodA()` `CallNonvirtualVoidMethodV()`	void
`CallNonvirtualObjectMethod()` `CallNonvirtualObjectMethodA()` `CallNonvirtualObjectMethodV()`	jobject
`CallNonvirtualBooleanMethod()` `CallNonvirtualBooleanMethodA()` `CallNonvirtualBooleanMethodV()`	jboolean
`CallNonvirtualByteMethod()` `CallNonvirtualByteMethodA()` `CallNonvirtualByteMethodV()`	jbyte
`CallNonvirtualCharMethod()` `CallNonvirtualCharMethodA()` `CallNonvirtualCharMethodV()`	jchar
`CallNonvirtualShortMethod()` `CallNonvirtualShortMethodA()` `CallNonvirtualShortMethodV()`	jshort
`CallNonvirtualIntMethod()` `CallNonvirtualIntMethodA()` `CallNonvirtualIntMethodV()`	jint
`CallNonvirtualLongMethod()` `CallNonvirtualLongMethodA()` `CallNonvirtualLongMethodV()`	jlong
`CallNonvirtualFloatMethod()` `CallNonvirtualFloatMethodA()` `CallNonvirtualFloatMethodV()`	jfloat
`CallNonvirtualDoubleMethod()` `CallNonvirtualDoubleMethodA()` `CallNonvirtualDoubleMethodV()`	jdouble

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラス

obj: Java オブジェクト

methodID: メソッド ID

CallNonvirtual<type>Method ルーチンに必要な追加パラメータ:

メソッドに対する引数

CallNonvirtual<type>MethodA ルーチンに必要な追加パラメータ:

args: 引数の配列

CallNonvirtual<type>MethodV ルーチンに必要な追加パラメータ:

args: 引数の va_list

戻り値:

Java メソッドを呼び出した結果を返します。

例外:

Java メソッドを実行している間に発生した例外

static フィールドへのアクセス

GetStaticFieldID

jfieldID GetStaticFieldID(JNIEnv *env, jclass clazz, 

     const char *name, const char *sig);

クラスの static フィールドを表すフィールド ID を返します。このフィールドは、その名前とシグニチャーで指定します。GetStatic<type>Field と SetStatic<type>Field ファミリのアクセス用関数は、フィールド ID を使用して static フィールドを取り出します。

GetStaticFieldID() によって、まだ初期化されていないクラスが初期化されます。

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

name: 0 で終了する UTF-8 文字列内の static フィールド

sig: 0 で終了する UTF-8 文字列内のフィールドシグニチャー

戻り値:

フィールド ID を返します。指定された static フィールドが見つからなかった場合は、NULL を返します。

例外:

NoSuchFieldError: 指定された static フィールドが見つからない場合

ExceptionInInitializerError: 例外のためにクラス初期化が失敗した場合

OutOfMemoryError: システムがメモリ不足の場合

GetStatic<type>Field ルーチン

NativeType GetStatic<type>Field

(JNIEnv *env, jclass clazz,

     jfieldID fieldID);

このアクセス用ルーチンのファミリは、オブジェクトの static フィールドを返します。アクセスするフィールドはフィールド ID で指定します。フィールド ID は、GetStaticFieldID()を呼び出すことによって取得することができます。

次の表には、 get ルーチン名のファミリと結果の型が示されています。GetStatic<type>Field 内の type をフィールドの Java 型と置き換える、あるいは表の実際の static フィールドアクセス用ルーチン名の 1 つを使って NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-5 アクセス用ルーチンの GetStatic<type>Field ファミリ
GetStatic<type>Field ルーチン名	ネイティブ型
`GetStaticObjectField()`	jobject
`GetStaticBooleanField()`	jboolean
`GetStaticByteField()`	jbyte
`GetStaticCharField()`	jchar
`GetStaticShortField()`	jshort
`GetStaticIntField()`	jint
`GetStaticLongField()`	jlong
`GetStaticFloatField()`	jfloat
`GetStaticDoubleField()`	jdouble

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

fieldID: static フィールド ID

戻り値:

static フィールドの内容を返します。

SetStatic<type>Field ルーチン

void SetStatic<type>Field

(JNIEnv *env, jclass clazz, 

     jfieldID fieldID,

NativeType

 value);

このアクセス用ルーチンのファミリは、オブジェクトの static フィールドの値を設定します。アクセスするフィールドは、フィールド ID で指定します。フィールド ID は、GetStaticFieldID() を呼び出すことによって取得することができます。

次の表には、セットルーチン名と値の型が示されています。SetStatic<type>Field 内の type をフィールドの Java 型と置き換えるか、あるいは表の実際のセット static フィールドルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-6 アクセス用ルーチンの SetStatic<type>Field ファミリ
SetStatic<type>Field ルーチン名	ネイティブ型
`SetStaticObjectField()`	jobject
`SetStaticBooleanField()`	jboolean
`SetStaticByteField()`	jbyte
`SetStaticCharField()`	jchar
`SetStaticShortField()`	jshort
`SetStaticIntField()`	jint
`SetStaticLongField()`	jlong
`SetStaticFloatField()`	jfloat
`SetStaticDoubleField()`	jdouble

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

fieldID: static フィールド ID

value: そのフィールドの新しい値

static メソッドの呼び出し

GetStaticMethodID

jmethodID GetStaticMethodID(JNIEnv *env, jclass clazz,

     const char *name, const char *sig);

クラスの static メソッドを表すメソッド ID を返します。このメソッドは、その名前とシグニチャーで指定します。

GetStaticMethodID() によって、まだ初期化されていないクラスが初期化されます。

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

name: 0 で終了する UTF-8 文字列内の static メソッド名

sig: 0 で終了する UTF-8 文字列内のメソッドシグニチャー

戻り値:

メソッド ID を返します。演算が失敗した場合は NULL を返します。

例外:

NoSuchMethodError: 指定された static メソッドが見つからない場合

ExceptionInInitializerError: 例外のため、クラス初期化が失敗した場合

OutOfMemoryError: システムがメモリ不足の場合

CallStatic<type>Method ルーチン
CallStatic<type>MethodA ルーチン
CallStatic<type>MethodV ルーチン

NativeType CallStatic<type>Method

(JNIEnv *env, jclass clazz,

     jmethodID methodID, ...);

NativeType CallStatic<type>MethodA(JNIEnv *env, jclass clazz, jmethodID methodID, jvalue *args);

NativeType CallStatic<type>MethodV(JNIEnv *env, jclass clazz, jmethodID methodID, va_list args);

この演算のファミリは、指定されたメソッド ID に従って、Java オブジェクト上の static メソッドを呼び出します。methodID 引数は、GetStaticMethodID()を呼び出すことによって取得しなければなりません。

メソッド ID は、clazz のスーパークラスの 1 つからではなく、clazz 自体から導き出す必要があります。

CallStatic<type>Method ルーチン

プログラマは、メソッドに渡す引数はすべて、methodID 引数のすぐあとに置かなければなりません。CallStatic<type>Method ルーチンは、これらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

CallStatic<type>MethodA ルーチン

プログラマは、メソッドに渡す引数はすべて、methodID 引数のすぐあとに続く jvalues の args 配列内に置かなければなりません。CallStaticMethodA ルーチンはこの配列内の引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

CallStatic<type>MethodV ルーチン

プログラマは、メソッドに渡す引数はすべて、methodID 引数のすぐあとに続く型 va_list の args 引数内に置かなければなりません。 CallStaticMethodV はこれらの引数を受け取り、プログラマが呼び出したい Java メソッドに渡します。

次の表には、メソッド呼び出しルーチンが各々その結果の型によって示されています。CallStatic<type>Method 内の type をメソッドの Java 型と置き換えるか、あるいは表の実際のメソッド呼び出しルーチン名の 1 つを使用して、NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

表 4-7 CallStatic<type>Method 呼び出しルーチン

CallStatic<type>Method ルーチン名ネイティブ型
CallStaticVoidMethod() CallStaticVoidMethodA() CallStaticVoidMethodV() void
CallStaticObjectMethod() CallStaticObjectMethodA() CallStaticObjectMethodV() jobject
CallStaticBooleanMethod() CallStaticBooleanMethodA() CallStaticBooleanMethodV() jboolean
CallStaticByteMethod() CallStaticByteMethodA() CallStaticByteMethodV() jbyte
CallStaticCharMethod() CallStaticCharMethodA() CallStaticCharMethodV() jchar
CallStaticShortMethod() CallStaticShortMethodA() CallStaticShortMethodV() jshort
CallStaticIntMethod() CallStaticIntMethodA() CallStaticIntMethodV() jint
CallStaticLongMethod() CallStaticLongMethodA() CallStaticLongMethodV() jlong
CallStaticFloatMethod() CallStaticFloatMethodA() CallStaticFloatMethodV() jfloat
CallStaticDoubleMethod() CallStaticDoubleMethodA() CallStaticDoubleMethodV() jdouble

表 4-7 CallStatic<type>Method 呼び出しルーチン
CallStatic<type>Method ルーチン名	ネイティブ型
`CallStaticVoidMethod()` `CallStaticVoidMethodA()` `CallStaticVoidMethodV()`	void
`CallStaticObjectMethod()` `CallStaticObjectMethodA()` `CallStaticObjectMethodV()`	jobject
`CallStaticBooleanMethod()` `CallStaticBooleanMethodA()` `CallStaticBooleanMethodV()`	jboolean
`CallStaticByteMethod()` `CallStaticByteMethodA()` `CallStaticByteMethodV()`	jbyte
`CallStaticCharMethod()` `CallStaticCharMethodA()` `CallStaticCharMethodV()`	jchar
`CallStaticShortMethod()` `CallStaticShortMethodA()` `CallStaticShortMethodV()`	jshort
`CallStaticIntMethod()` `CallStaticIntMethodA()` `CallStaticIntMethodV()`	jint
`CallStaticLongMethod()` `CallStaticLongMethodA()` `CallStaticLongMethodV()`	jlong
`CallStaticFloatMethod()` `CallStaticFloatMethodA()` `CallStaticFloatMethodV()`	jfloat
`CallStaticDoubleMethod()` `CallStaticDoubleMethodA()` `CallStaticDoubleMethodV()`	jdouble

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

methodID: static メソッド ID

CallStatic<type>Method ルーチンに必要な追加パラメータ:

static メソッドの引数

CallStatic<type>MethodA ルーチンに必要な追加パラメータ:

args: 引数の配列

CallStatic<type>MethodV ルーチンに必要な追加パラメータ:

args: 引数の va_list

戻り値:

static Java メソッドを呼び出した結果を返します。

例外:

Java メソッドを実行している間に発生した例外

文字列オペレーション

NewString

jstring NewString(JNIEnv *env, const jchar *unicodeChars,

     jsize len);

Unicode 文字配列から新しい java.lang.String オブジェクトを構築します。

パラメータ:

env: JNI インタフェースポインタ

unicodeChars: Unicode 文字列を参照するポインタ

len: Unicode 文字列の長さ

戻り値:

Java 文字列オブジェクトを返します。文字列が構築できない場合は、NULL を返します。

例外:

OutOfMemoryError: システムがメモリ不足の場合

GetStringLength

jsize GetStringLength(JNIEnv *env, jstring string);

Java 文字列の長さ (Unicode 文字のカウント) を返します。

パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

戻り値:

Java 文字列の長さを返します。

GetStringChars

const jchar * GetStringChars(JNIEnv *env, jstring string,

     jboolean *isCopy);

文字列の Unicode 文字の配列を参照するポインタを返します。このポインタは、ReleaseStringchars() が呼び出されるまで有効です。

isCopy が NULL ではない場合にコピーが作成されると、*isCopy は JNI_TRUE に設定されます。コピーが作成されない場合は、JNI_FALSE に設定されます。

パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

isCopy: ブール値に対するポインタ

戻り値:

Unicode 文字列を参照するポインタをします。演算が失敗した場合は NULL を返します。

ReleaseStringChars

void ReleaseStringChars(JNIEnv *env, jstring string, 

     const jchar *chars);

ネイティブコードが chars へのアクセスをもはや必要としていないことを VM に知らせます。chars 引数は、GetStringChars() を使用してstring から取得することができるポインタです。

パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

chars: Unicode 文字列を参照するポインタ

NewStringUTF

jstring NewStringUTF(JNIEnv *env, const char *bytes);

UTF-8 文字の配列から新しい java.lang.String オブジェクトを構築します。

パラメータ:

env: JNI インタフェースポインタ。文字列が構築できない場合は NULL

bytes: UTF-8 文字列を参照するポインタ

戻り値:

Java 文字列オブジェクトをします。字列が構築できない場合は NULL を返します。

例外:

OutOfMemoryError: システムがメモリ不足の場合

GetStringUTFLength

jsize GetStringUTFLength(JNIEnv *env, jstring string);

文字列のバイトで UTF-8 長を返します。

パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

戻り値:

文字列の UTF-8 長を返します。

GetStringUTFChars

const char* GetStringUTFChars(JNIEnv *env, jstring string, 

     jboolean *isCopy);

UTF-8 文字の文字列配列を参照するポインタを返します。この配列は、ReleaseStringUTFChars() によって解放されるまで有効です。

パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

isCopy: ブール値に対するポインタ

戻り値:

UTF-8 文字列を参照するポインタを返します。演算が失敗した場合は NULL を返します。

ReleaseStringUTFChars

void ReleaseStringUTFChars(JNIEnv *env, jstring string,

     const char *utf);

ネイティブコードが utf へのアクセスをもはや必要としていないことを VM に知らせます。utf 引数は、GetStringUTFChars() を使用して string から取得することができるポインタです。

パラメータ:

env: JNI インタフェースポインタ

string: Java 文字列オブジェクト

utf: UTF-8 文字列を参照するポインタ

配列オペレーション

GetArrayLength

jsize GetArrayLength(JNIEnv *env, jarray array);

配列内の要素の数を返します。

パラメータ:

env: JNI インタフェースポインタ

array: Java 配列オブジェクト

戻り値:

配列の長さを返します。

NewObjectArray

jarray NewObjectArray(JNIEnv *env, jsize length, 

     jclass elementClass, jobject initialElement);

クラス elementClass にオブジェクトを持つ新しい配列を構築します。要素はすべて、最初に initialElement に設定されます。

パラメータ:

env: JNI インタフェースポインタ

length: 配列サイズ

elementClass: 配列要素クラス

initialElement: 初期化値

戻り値:

Java 配列オブジェクトをします。配列が構築できない場合は NULL を返します。

例外:

OutOfMemoryError: システムがメモリ不足の場合

GetObjectArrayElement

jobject GetObjectArrayElement(JNIEnv *env, 

     jobjectArray array, jsize index);

Object 配列の要素を返します。

パラメータ:

env: JNI インタフェースポインタ

array: Java 配列

index: 配列添字

戻り値:

Java オブジェクトを返します。

例外:

ArrayIndexOutOfBoundsException: index が配列内に有効な添字を指定しなかった場合

SetObjectArrayElement

void SetObjectArrayElement(JNIEnv *env, jobjectArray array, 

     jsize index, jobject value);

オブジェクト配列の要素を設定します。

パラメータ:

env: JNI インタフェースポインタ

array: Java 配列

index: 配列添字

value: 新しい値

例外:

ArrayIndexOutOfBoundsException: index が配列内に有効な添字の値を指定しなかった場合

ArrayStoreException: value のクラスが、配列の要素クラスのサブクラスではない場合

New<PrimitiveType>Array ルーチン

ArrayType New<PrimitiveType>Array

(JNIEnv *env, jsize length);

新しいプリミティブ配列オブジェクトを構築するために使用される演算のファミリ。表 4-8 には、特定のプリミティブ配列コンストラクタが示されています。 New<PrimitiveType>Array を、次の表の実際のプリミティブ配列コンストラクタルーチン名の 1 つと置き換え、ArrayType をそのルーチンに対応する配列型と置き換える必要があります。

表 4-8 配列コンストラクタの New<PrimitiveType>Array ファミリ
New<PrimitiveType>Array ルーチン	配列型
`NewBooleanArray()`	jbooleanArray
`NewByteArray()`	jbyteArray
`NewCharArray()`	jcharArray
`NewShortArray()`	jshortArray
`NewIntArray()`	jintArray
`NewLongArray()`	jlongArray
`NewFloatArray()`	jfloatArray
`NewDoubleArray()`	jdoubleArray

パラメータ:

env: JNI インタフェースポインタ

length: 配列長

戻り値:

Java 配列を返します。Java 配列が構築できなかった場合は NULL を返します。

Get<PrimitiveType>ArrayElements ルーチン

NativeType *Get<PrimitiveType>ArrayElements

(JNIEnv *env,

ArrayType

 array, jboolean *isCopy);

プリミティブ配列の本体を返す関数のファミリです。その結果は、対応する Release<PrimitiveType>ArrayElements() 関数が呼び出されるまで有効です。返された配列は Java 配列のコピーである場合もあるため、その返された配列に加えられている変更は、Release<PrimitiveType>ArrayElements() が呼び出されるまでは、必ずしも元の array に反映されているとは限りません。

次の表には、特定のプリミティブ配列要素アクセス機能を示されています。次の置換を行う必要があります

Get<PrimitiveType>ArrayElements を、表の実際のプリミティブ要素アクセス機能ルーチン名の 1 つと置き換える
ArrayType を対応する配列型と置き換える
NativeType をそのルーチンに対応するネイティブ型と置き換える

Java VM 内でブール配列がどのように表されているかにかかわらず、GetBooleanArrayElements() は常に jbooleans を参照するポインタを返してきます。各バイトが 1 つの要素を表しています (アンパック表示)。その他の型の配列はすべて、メモリ内で必ず隣接するようになっています。

表 4-9 アクセス機能ルーチンの Get<PrimitiveType>ArrayElements ファミリ
Get<PrimitiveType>ArrayElements ルーチン	配列型	ネイティブ型
`GetBooleanArrayElements()`	jbooleanArray	jboolean
`GetByteArrayElements()`	jbyteArray	jbyte
`GetCharArrayElements()`	jcharArray	jchar
`GetShortArrayElements()`	jshortArray	jshort
`GetIntArrayElements()`	jintArray	jint
`GetLongArrayElements()`	jlongArray	jlong
`GetFloatArrayElements()`	jfloatArray	jfloat
`GetDoubleArrayElements()`	jdoubleArray	jdouble

パラメータ:

env: JNI インタフェースポインタ

array: Java 文字列オブジェクト

isCopy: ブール値に対するポインタ

戻り値:

配列要素を参照するポインタを返します。演算が失敗した場合は、NULL を返します。

Release<PrimitiveType>ArrayElements ルーチン

void Release<PrimitiveType>ArrayElements

(JNIEnv *env,

ArrayType array, NativeType

 *elems, jint mode);

ネイティブコードが elems へのアクセスをもはや必要としていないことを VM に知らせる関数のファミリです。elems 引数は、対応する Get<PrimitiveType>ArrayElements() 関数を使用して、array から導き出されるポインタです。必要に応じて、この関数は、 elems に施された変更をすべて元の配列にコピーし直します。

mode 引数は、配列バッファの解放方法に関する情報を提供します。mode は、elems が array 内の要素のコピーではない場合は、影響を及ぼしません。mode が array 内の要素のコピーである場合は、次の表に示されているような影響を及ぼします。

表 4-10 プリミティブ配列解放モード
モード	動作
`0`	内容をコピーバックし、`elems` バッファを解放する
`JNI_COMMIT`	内容をコピーバックするが、`elems` バッファを解放しない
`JNI_ABORT`	変更の可能性があってもその変更をコピーバックせずに、バッファを解放する

多くの場合、プログラマは、ピン配列とコピー配列の両方に対して一貫した動作を保証するために、0 を mode 引数に渡します。0 以外を渡す場合は、プログラマはメモリを十分に注意して管理する必要があります。

次の表には、プリミティブ配列処置機能のファミリを構成する特定のルーチンが示されています。次の置換を行う必要があります。

Release<PrimitiveType>ArrayElements を、表 4-11 に示されている実際のプリミティブ配列処置機能ルーチン名の 1 つと置き換える
ArrayType を対応する配列型と置き換える
NativeType をそのルーチンに対応するネイティブ型と置き換える

表 4-11 配列ルーチンの Release<PrimitiveType>ArrayElements ファミリ
Release<PrimitiveType>ArrayElements ルーチン	配列型	ネイティブ型
`ReleaseBooleanArrayElements()`	jbooleanArray	jboolean
`ReleaseByteArrayElements()`	jbyteArray	jbyte
`ReleaseCharArrayElements()`	jcharArray	jchar
`ReleaseShortArrayElements()`	jshortArray	jshort
`ReleaseIntArrayElements()`	jintArray	jint
`ReleaseLongArrayElements()`	jlongArray	jlong
`ReleaseFloatArrayElements()`	jfloatArray	jfloat
`ReleaseDoubleArrayElements()`	jdoubleArray	jdouble

パラメータ:

env: JNI インタフェースポインタ

array: Java 配列オブジェクト

elems: 配列要素を参照するポインタ

mode: 解放モード

Get<PrimitiveType>ArrayRegion ルーチン

void Get<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType

 array,

     jsize start, jsize len,

NativeType

 *buf);

プリミティブ配列の領域をバッファにコピーする機能のファミリです。

次の表には、特定のプリミティブ配列要素アクセス機能が示されています。次の置換を行う必要があります。

Get<PrimitiveType>ArrayRegion を、表 4-12 に示されている実際のプリミティブ要素アクセス機能ルーチン名の 1 つと置き換える
ArrayType を、対応する配列型と置き換える
NativeType をそのルーチンに対応するネイティブ型と置き換える

表 4-12 配列アクセス機能ルーチンの Get<PrimitiveType>ArrayRegion ファミリ
Get<PrimitiveType>ArrayRegion ルーチン	配列型	ネイティブ型
`GetBooleanArrayRegion()`	jbooleanArray	jboolean
`GetByteArrayRegion()`	jbyteArray	jbyte
`GetCharArrayRegion()`	jcharArray	jchar
`GetShortArrayRegion()`	jshortArray	jhort
`GetIntArrayRegion()`	jintArray	jint
`GetLongArrayRegion()`	jlongArray	jlong
`GetFloatArrayRegion()`	jfloatArray	jloat
`GetDoubleArrayRegion()`	jdoubleArray	jdouble

パラメータ:

env: JNI インタフェースポインタ

array: Java 配列

start: 開始添字

len: コピー対象の要素の数

buf: 転送先バッファ

例外:

ArrayIndexOutOfBoundsException: 領域内の添字の 1 つでも有効ではない場合

Set<PrimitiveType>ArrayRegion ルーチン

void Set<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType

 array, 

     jsize start, jsize len,

NativeType

 *buf);

バッファからのプリミティブ配列の領域をコピーバックする機能のファミリです。

次の表には、特定のプリミティブ配列要素アクセス機能が示されています。次の置換を行う必要があります。

Set<PrimitiveType>ArrayRegion を、表に示されている実際のプリミティブ要素アクセス機能ルーチン名の 1 つと置き換える
ArrayType を対応する配列型と置き換える

NativeType を、そのルーチンに対応するネイティブ型と置き換える

表 4-13 配列アクセス機能ルーチンの Set<PrimitiveType>ArrayRegion ファミリ
Set<PrimitiveType>ArrayRegion ルーチン	配列型	ネイティブ型
`SetBooleanArrayRegion()`	jbooleanArray	jboolean
`SetByteArrayRegion()`	jbyteArray	jbyte
`SetCharArrayRegion()`	jcharArray	jchar
`SetShortArrayRegion()`	jshortArray	jshort
`SetIntArrayRegion()`	jintArray	jint
`SetLongArrayRegion()`	jlongArray	jlong
`SetFloatArrayRegion()`	jfloatArray	jfloat
`SetDoubleArrayRegion()`	jdoubleArray	jdouble

パラメータ:

env: JNI インタフェースポインタ

array: Java 配列

start: 開始添字

len: コピー対象の要素の数

buf: 転送元バッファ

例外:

ArrayIndexOutOfBoundsException: 領域内の添字の 1 つでも有効ではない場合

ネイティブメソッドの登録

RegisterNatives

jint RegisterNatives(JNIEnv *env, jclass clazz, 

     const JNINativeMethod *methods, jint nMethods);

clazz 引数によって指定されたクラスでネイティブメソッドを登録します。 methods パラメータは、そのネイティブメソッドの名前、シグニチャー、関数ポインタを含む JNINativeMethod 構造体の配列を指定します。 nMethods パラメータは、配列内のネイティブメソッドの数を指定します。JNINativeMethod 構造体は次のように定義されます。

    typedef struct {
        char *name;
        char *signature;
        void *fnPtr;
    } JNINativeMethod;

関数ポインタは、形式上、次のシグニチャーを備えている必要があります。

    ReturnType (*fnPtr)(JNIEnv *env, jobject objectOrClass, ...);

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

methods: クラス内のネイティブメソッド

nMethods: そのクラス内のネイティブメソッドの数

戻り値:

成功の場合は 0 を、失敗の場合は負の値を返します。

例外:

NoSuchMethodError: 指定されたメソッドが見つからなかった場合、または、そのメソッドがネイティブではなかった場合

UnregisterNatives

jint UnregisterNatives(JNIEnv *env, jclass clazz);

あるクラスのネイティブメソッドの登録を抹消します。そのクラスは、そのネイティブメソッド機能にリンクされる前または再登録される前の状態に戻ります。

この関数は、通常のネイティブコードでは使用するべきではありません。その代わりに、特別なプログラムにネイティブライブラリを再ロードしたり再リンクしたりする方法を提供します。

パラメータ:

env: JNI インタフェースポインタ

clazz: Java クラスオブジェクト

戻り値:

成功の場合は 0 を、失敗の場合は負の値を返します。

モニターオペレーション

MonitorEnter

jint MonitorEnter(JNIEnv *env, jobject obj);

obj によって参照される基底の Java オブジェクトに関連するモニターに入ります。

Java オブジェクトは、それぞれ、関連するモニターを持っています。現在のスレッドがすでに obj に関連するモニターを持つ場合は、このスレッドがモニターに入った回数を表すモニター内のカウンタが増加されます。obj に関連するモニターがどのスレッドにも所有されていない場合は、現在のスレッドがそのモニターの所有者となり、このモニターのエントリカウントを 1 に設定します。別のスレッドがすでに obj に関連するモニターを持つ場合は、現在のスレッドはモニターが解放されるのを待ち、再度、所有を試みます。

パラメータ:

env: JNI インタフェースポインタ

obj: 通常の Java オブジェクトまたはクラスオブジェクト

戻り値:

成功の場合は 0 を、失敗の場合は負の値を返します。

MonitorExit

jint MonitorExit(JNIEnv *env, jobject obj);

現在のスレッドは、obj によって参照された基底の Java オブジェクトに関連するモニターの所有者でなければなりません。このスレッドは、このモニターに入った回数を表すカウンタを減少させます。カウンタの値がゼロになると、現在のスレッドはモニターを解放します。

パラメータ:

env: JNI インタフェースポインタ

obj: 通常の Java オブジェクトまたはクラスオブジェクト

戻り値:

成功の場合は 0 を、失敗の場合は負の値を返します。

Java VM インタフェース

GetJavaVM

jint GetJavaVM(JNIEnv *env, JavaVM **vm);

現在のスレッドに関連する Java VM インタフェース (呼び出し API で使用) を返します。その結果は、2 番目の引数 vm で示された位置に置かれます。

パラメータ:

env: JNI インタフェースポインタ

vm: 結果を返すポインタ

戻り値:

成功の場合は 0 を、失敗の場合は負の値を返します。

目次 | 前の項目 | 次の項目

4 - JNI 関数

インタフェース関数テーブル

コード例 4-1

バージョン情報

GetVersion

パラメータ:

戻り値:

クラスオペレーション

DefineClass

パラメータ:

戻り値:

例外:

FindClass

パラメータ:

戻り値:

例外:

GetSuperclass

パラメータ:

戻り値:

IsAssignableFrom

パラメータ:

戻り値:

例外

Throw

パラメータ:

戻り値:

例外:

ThrowNew

パラメータ:

戻り値:

例外:

ExceptionOccurred

パラメータ:

戻り値:

ExceptionDescribe

パラメータ:

ExceptionClear

パラメータ:

FatalError

パラメータ:

グローバル参照およびローカル参照

NewGlobalRef

パラメータ:

戻り値:

DeleteGlobalRef

パラメータ:

DeleteLocalRef

パラメータ:

オブジェクトオペレーション

AllocObject

パラメータ:

戻り値:

例外:

NewObject NewObjectA NewObjectV

NewObject

NewObjectA

NewObjectV

パラメータ:

NewObject に必要な追加パラメータ:

NewObjectA に必要な追加パラメータ:

NewObjectV に必要な追加パラメータ:

戻り値:

例外:

GetObjectClass

パラメータ:

戻り値:

IsInstanceOf

パラメータ:

戻り値:

IsSameObject

パラメータ:

戻り値:

オブジェクトのフィールドへのアクセス

GetFieldID

パラメータ:

戻り値:

例外:

Get<type>Field ルーチン

表 4-1 アクセス用ルーチンの Get<type>Field ファミリ

パラメータ:

NewObject
NewObjectA
NewObjectV

Call<type>Method ルーチン
Call<type>MethodA ルーチン
Call<type>MethodV ルーチン

CallNonvirtual<type>Method ルーチン
CallNonvirtual<type>MethodA ルーチン
CallNonvirtual<type>MethodV ルーチン

CallStatic<type>Method ルーチン
CallStatic<type>MethodA ルーチン
CallStatic<type>MethodV ルーチン