Low level: C++ and JNI data transfer

In most of the cases it is only necessary to transfer simple data structures. For this purpose it is fairly enough to only work with static methods. The ARES Touch SDK provides a handful helper classes to avoid working directly with the JNI interfaces and Java environment. The utility class is called FxJavaUtils and provides a large set of classes. These are the steps to address a simple data transfer between the host app and the C++ app part and vice versa.

1.Transfer data from Java to C++ JAVA C++

1.1 Create a Java class and add a public native static method

public static native RETURNTYPE JAVA_TO_CPP( PARAMS );

The RETURNTYPE as well as the PARAMS must be declared with Java known data types. The method name JAVA_TO_CPP does not need to contain characters like _ , may be just JAVATOCPP.

Java Type	Description

Java Type	Description
boolean	unsigned 8 bits
byte	signed 8 bits
char	unsigned 16 bits
short	signed 16 bits
int	signed 32 bits
long	signed 64 bits
float	32 bits
double	64 bits
void	N/A
java/lang/String	String class
android/util/ArrayMap	Array map class
For more details check official Java documentation:	java.lang (Java Platform SE 7 ) java.util (Java Platform SE 7 )

1.2 Create an equivalent C++ method that exactly matches the Java class method C++

Declare your matching C++ method and make sure it matches exactly in RETURNTYPE, PARAMS and name JAVA_TO_CPP else you will more likely face an unsatisfied linker error on runtime. Keep an eye that PATH_TO_YOUR_CLASS exactly refers to the location of your Java class/file based on the root “src/main/java” folder.
e.g.: …/YOUR_ANDROID_PROJECT/src/main/java/PATH_TO_YOUR_CLASS
e.g.: …/YOUR_ANDROID_PROJECT/src/main/java/com/domain/folder/CLASSNAME
e.g.: Java_com_domain_folder_CLASSNAME_JAVA_TO_CPP()

C++

#ifndef __JNI_H__
#define __JNI_H__
#include <jni.h>

extern "C"
{
    JNIEXPORT RETURNTYPE JNICALL Java_PATH_TO_YOUR_CLASS_JAVA_TO_CPP( JNIEnv * env, jclass clazz [, PARAMS ...] );
}
#endif //__JNI_H__

C++

JNIEXPORT RETURNTYPE JNICALL Java_PATH_TO_YOUR_CLASS_JAVA_TO_CPP( JNIEnv * env, jclass clazz [, PARAMS ...] )
{
    // RETURNTYPE
    // void just return; or ignore
    // else return RETURNTYPE;
}

In the case you specify PARAMS and RETURNTYPE please declare the data types in the JNI matching pairs.

Java Type	Native Type	Description

Java Type	Native Type	Description
boolean	jboolean	unsigned 8 bits
byte	jbyte	signed 8 bits
char	jchar	unsigned 16 bits
short	jshort	signed 16 bits
int	jint	signed 32 bits
long	jlong	signed 64 bits
float	jfloat	32 bits
double	jdouble	64 bits
void	void	N/A
java/lang/String	jstring	String class
android/util/ArrayMap	jobjectarray	Array map class
For more details check official Java documentation:	JNI Types and Data Structures

1.3 Call the native method from Java JAVA

Whenever a native method is called from the host application it must be executed from the working thread.

JAVA

private void METHOD()
{
    CFxARESInstance.instance().runOnWorkingThread(new Runnable()
    {
        @Override
        public void run()
        {
            CLASS.JAVA_TO_CPP( PARAMS );
        }
    });
}

1.4 Return values back from C++ to Java JAVA C++

In general returning back values to Java is quite easy but there is one important fact that must be considered. In the case the C++ method returns back an class object it must be returned strongly. This means it is not allowed to be destroyed inside the C++method else it will lead to a crash. Java is taking care about freeing the object after it is processed on Java side else it is always necessary to clean up object references to avoid running into limit of possible references. All FxJavaUtils class objects destroy the JNI reference automatically. Only in case the C++ method needs to return an Java class object it is highly important to use methods like GetStrongJObject() or GetStrongJString() else GetJObject() or GetJString() do the job. The usage of complex objects to carry more data can be read in the topic High level: C++ and JNI data transfer .

C++

JAVA

ARES Touch Partner Documentation

Low level: C++ and JNI data transfer

Analytics

Related content