Java ネイティブインタフェース仕様

4 - JNI 関数

本章は、JNI の関数を参照するためのもです。本章では、JNI の関数をすべて取り上げます。また、JNI 関数表の配置そのままに記載されています。

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

本章の一部は Netscape の 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 ビットで返します。

JDK1.1 では、GetVersion() が 0x00010001 を返します。

クラスオペレーション

DefineClass

jclass DefineClass(JNIEnv *env, jobject loader, 

     const jbyte *buf, jsize bufLen);

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

パラメータ:

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

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

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

bufLen: バッファ長

返り値:

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

例外:

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

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

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

FindClass

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

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

パラメータ:

env: the 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 オブジェクト obj

ThrowNew

jint ThrowNew(JNIEnv *env, jclass clazz, 

     const char *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 型と置き換えるか、あるいは表の実際のルーチン名のひとつを使用するかする必要と、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 型と置き換えるか、あるいは表の実際のルーチン名のひとつを使用するかする必要と、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 のスーパークラスのひとつの中で定義し、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 の実クラスのスーパークラスのひとつからではなく、実クラス自体から導き出す必要があります。

Call<type>Method ルーチン

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

Call<type>MethodA ルーチン

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

Call<type>MethodV ルーチン

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

次の表には、メソッド呼び出しルーチンの各々がその結果の型に応じて示されています。Call<type>Method 内の type を呼び出しているメソッドの Java 型と置き換え (または、表の実際のメソッド呼び出しルーチン名のひとつを使用する)、かつ 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 は、このオブジェクトの実クラスまたはその実クラスのスーパークラスのひとつから取得しなければなりません。

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 型と置き換えるか、あるいは表から実際のメソッド呼び出しルーチン名のひとつを使用するかする必要と、 NativeType をそのルーチンに対応するネイティブ型と置き換える必要があります。

Table 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: a 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 フィールドアクセス用ルーチン名のひとつを使用って 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 フィールドルーチン名のひとつを使用するかする必要と、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 のスーパークラスのひとつからではなく、 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 型と置き換えるか、あるいは表の実際のメソッド呼び出しルーチン名のひとつを使用するかする必要と、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 jbyte* 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 を、次の表の実際のプリミティブ配列構築子ルーチン名のひとつと置き換え、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 を、表の実際のプリミティブ要素アクセス機能ルーチン名のひとつと置き換えます。
ArrayType を対応する配列型と置き換えます。
NativeType をそのルーチンに対応するネイティブ型と置き換えます。

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

表 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 に示されている実際のプリミティブ配列処置機能ルーチン名のひとつと置き換えます。
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 に示されている実際のプリミティブ要素アクセス機能ルーチン名のひとつと置き換えます。
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: 領域内の添字のひとつでも有効ではない場合

Set<PrimitiveType>ArrayRegion ルーチン

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

 array, 

     jsize start, jsize len,

NativeType

 *buf);

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

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

Set<PrimitiveType>ArrayRegion を、表に示されている実際のプリミティブ要素アクセス機能ルーチン名のひとつと置き換えます。
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: 領域内の添字のひとつでも有効ではない場合

Registering Native Methods

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,

     const JNINativeMethod *methods, jint nMethods);

あるクラスのネイティブメソッドを抹消します。そのクラスは、そのネイティブメソッド機能にリンクされる前または再登録される前の状態に戻ります。methods パラメータは、そのネイティブメソッドの名前を含む文字列の NULLで終了する配列を指定します。nMethods パラメータは、その配列内のネイティブメソッドの数を指定します。

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

パラメータ:

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

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

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

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

返り値:

成功の場合は "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 ルーチン