1 // Copyright (c) 2013 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_ANDROID_JNI_GENERATOR_SAMPLE_FOR_TESTS_H_ 6 #define BASE_ANDROID_JNI_GENERATOR_SAMPLE_FOR_TESTS_H_ 7 8 #include <jni.h> 9 #include <map> 10 #include <string> 11 12 #include "base/android/jni_android.h" 13 14 namespace base { 15 namespace android { 16 17 // This file is used to: 18 // - document the best practices and guidelines on JNI usage. 19 // - ensure sample_for_tests_jni.h compiles and the functions declared in it 20 // as expected. 21 // 22 // Methods are called directly from Java. More documentation in 23 // SampleForTests.java. See BUILD.gn for the build rules necessary for JNI 24 // to be used in an APK. 25 // 26 // For C++ to access Java methods: 27 // - GN Build must be configured to generate bindings: 28 // # Add import at top of file: 29 // if (is_android) { 30 // import("//build/config/android/rules.gni") # For generate_jni(). 31 // } 32 // # ... 33 // # An example target that will rely on JNI: 34 // component("foo") { 35 // # ... normal sources, defines, deps. 36 // # For each jni generated .java -> .h header file in jni_headers 37 // # target there will be a single .cc file here that includes it. 38 // # 39 // # Add a dep for JNI: 40 // if (is_android) { 41 // deps += [ ":foo_jni" ] 42 // } 43 // } 44 // # ... 45 // # Create target for JNI: 46 // if (is_android) { 47 // generate_jni("jni_headers") { 48 // sources = [ 49 // "java/src/org/chromium/example/jni_generator/SampleForTests.java", 50 // ] 51 // jni_package = "foo" 52 // } 53 // android_library("java") { 54 // java_files = [ 55 // "java/src/org/chromium/example/jni_generator/SampleForTests.java", 56 // "java/src/org/chromium/example/jni_generator/NonJniFile.java", 57 // ] 58 // } 59 // } 60 // The build rules above are generally that that's needed when adding new 61 // JNI methods/files. For a full GN example, see 62 // base/android/jni_generator/BUILD.gn 63 // 64 // For C++ methods to be exposed to Java: 65 // - The Java class must be part of an android_apk target that depends on 66 // a generate_jni_registration target. This generate_jni_registration target 67 // automatically generates all necessary registration functions. The 68 // generated header file exposes two functions that should be called when a 69 // library is first loaded: 70 // 1) RegisterMainDexNatives() 71 // - Registers all methods that are used outside the browser process 72 // 2) RegisterNonMainDexNatives() 73 // - Registers all methods used in the browser process 74 // 75 class CPPClass { 76 public: 77 CPPClass(); 78 ~CPPClass(); 79 80 // Java @CalledByNative methods implicitly available to C++ via the _jni.h 81 // file included in the .cc file. 82 83 class InnerClass { 84 public: 85 jdouble MethodOtherP0(JNIEnv* env, 86 const base::android::JavaParamRef<jobject>& caller); 87 }; 88 89 void Destroy(JNIEnv* env, const base::android::JavaParamRef<jobject>& caller); 90 91 jint Method(JNIEnv* env, const base::android::JavaParamRef<jobject>& caller); 92 93 void AddStructB(JNIEnv* env, 94 const base::android::JavaParamRef<jobject>& caller, 95 const base::android::JavaParamRef<jobject>& structb); 96 97 void IterateAndDoSomethingWithStructB( 98 JNIEnv* env, 99 const base::android::JavaParamRef<jobject>& caller); 100 101 base::android::ScopedJavaLocalRef<jstring> ReturnAString( 102 JNIEnv* env, 103 const base::android::JavaParamRef<jobject>& caller); 104 105 private: 106 std::map<long, std::string> map_; 107 108 DISALLOW_COPY_AND_ASSIGN(CPPClass); 109 }; 110 111 } // namespace android 112 } // namespace base 113 114 #endif // BASE_ANDROID_JNI_GENERATOR_SAMPLE_FOR_TESTS_H_ 115