JNI之函数介绍四之数组操作

前言

今天介绍一下JNI中数组相关操作函数。

正文

GetArrayLength

# env： JNI 接口指针
# array： Java 数组对象
jsize GetArrayLength(JNIEnv *env, jarray array);

返回数组中的元素数(数组的长度)。

NewObjectArray

# env： JNI 接口指针
# length：数组大小
# elementClass：数组元素类
# initialElement：初始值
jarray NewObjectArray(JNIEnv *env, jsize length,jclass elementClass, jobject initialElement);

构造新的数组，保存类 elementClass 中的对象，所有元素初始值均设为initialElement 。

# 创建一个Person数组，每个元素为NULL
jobjectArray array = env->NewObjectArray(length, clazz_Person, NULL);

没怎么用过~_~

如果成功，返回数组对象，否则返回NULL。

GetObjectArrayElement

# env： JNI 接口指针
# array： Java 数组
# index：数组下标
jobject GetObjectArrayElement(JNIEnv *env,jobjectArray array, jsize index);

返回 Object 数组的元素。

如果 index 不是数组中的有效下标，抛出异常ArrayIndexOutOfBoundsException。

SetObjectArrayElement

# env： JNI 接口指针
# array： Java 数组
# index：数组下标
# value：新值
void SetObjectArrayElement(JNIEnv *env, jobjectArray array,jsize index, jobject value);

设置 Object 数组的元素。

如果 index 不是数组中的有效下标，抛出ArrayIndexOutOfBoundsException。

如果 value 的类不是数组元素类的子类，抛出ArrayStoreException。

New<PrimitiveType>Array

# env： JNI 接口指针
# length：数组长度
ArrayType New<PrimitiveType>Array(JNIEnv *env, jsize length);

创建对应<PrimitiveType>类型的数组。

NewBooleanArray()   jbooleanArray
NewByteArray()      jbyteArray
NewCharArray()      jcharArray
NewShortArray()     jshortArray
NewIntArray()       jintArray
NewLongArray()      jlongArray
NewFloatArray()     jfloatArray
NewDoubleArray()    jdoubleArray

NewIntArray

以int类型为例

jintArray NewIntArray(JNIEnv *env, jsize length);

Get<PrimitiveType>ArrayElements

# env： JNI 接口指针
# array： Java 字符串对象
# isCopy：指向布尔值的指针
NativeType *Get<PrimitiveType>ArrayElements(JNIEnv *env,ArrayType array, jboolean *isCopy);

一组返回基本类型数组体的函数。结果在调用相应的Release<PrimitiveType>ArrayElements() 函数前将一直有效。 由于返回的数组可能是 Java 数组的副本， 因此对返回数组的更改不必在基本类型数组中反映出来，直到调用了 Release<PrimitiveType>ArrayElements()。

如果 isCopy 不是 NULL， *isCopy 在复制完成后即被设为 JNI_TRUE。 如果未复制，则设为 JNI_FALSE。

注意事项：

1. Get<PrimitiveType>ArrayElements 替换为表中某个实际的基本类型 元素访问器例程名

2. 将 ArrayType 替换为对应的数组类型。

3. 将 NativeType 替换为该例程对应的本地类型。

GetIntArrayElements

以int类为例

jint * GetIntArrayElements(JNIEnv *env, jintArray array, jboolean *isCopy);

Release<PrimitiveType>ArrayElements

# env： JNI 接口指针
# array： Java 数组对象
# elems：指向数组元素的指针
# mode：释放模式
void Release<PrimitiveType>ArrayElements(JNIEnv *env,ArrayType array, NativeType *elems, jint mode);

通知虚拟机平台相关代码无需再访问 elems 的一组函数。 elems 参数是一个通过使用对应的 Get<PrimitiveType>ArrayElements() 函数由 array 导出的指针。必要时，该函数将把对 elems 的修改复制回基本类型数组。

mode 参数将提供有关如何释放数组缓冲区的信息。如果 elems 不是 array 中数组元素的副本， mode 将无效。否则， mode 将具有下表所述的功能：

1. 0 复制回内容并释放 elems 缓冲区

2. JNI_COMMIT 复制回内容但不释放 elems 缓冲区

3. JNI_ABORT 释放缓冲区但不复制回变化

多数情况下，编程人员将把“ 0” 传给 mode 参数以确保固定的数组和复制的数组保持一致。 其它选项可以使编程人员进一步控制内存管理， 但使用时务必慎重。

ReleaseIntArrayElements

以int类为例

void ReleaseIntArrayElements(JNIEnv *env,jintArray array, jint *elems, jint mode);

Set<PrimitiveType>ArrayRegion

# env： JNI 接口指针
# array: Java 数组
# start：起始下标
# len：要复制的元素数
# buf：源缓冲区
void Set<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,jsize start, jsize len, NativeType *buf);

将基本类型数组的某一区域从缓冲区中复制回来的一组函数。

如果区域中的某个下标无效，就抛出ArrayIndexOutOfBoundsException

Get<PrimitiveType>ArrayRegion

# env： JNI 接口指针
# array： Java 指针
# start：起始下标
# len：要复制的元素数
# buf：目的缓冲区
void Get<PrimitiveType>ArrayRegion(JNIEnv *env, ArrayType array,jsize start, jsize len, NativeType *buf);

将基本类型数组某一区域复制到缓冲区中的一组函数。

如果区域中的某个下标无效，抛出ArrayIndexOutOfBoundsException。

参考文章

1. 《JNI完全手册]》

2. 《NDK中jni.h头文件完整内容》

3. 《 JNI引用类型数组操作 》