OLD | NEW |
| (Empty) |
1 /* | |
2 * Copyright (c) 2015 The WebRTC project authors. All Rights Reserved. | |
3 * | |
4 * Use of this source code is governed by a BSD-style license | |
5 * that can be found in the LICENSE file in the root of the source | |
6 * tree. An additional intellectual property rights grant can be found | |
7 * in the file PATENTS. All contributing project authors may | |
8 * be found in the AUTHORS file in the root of the source tree. | |
9 */ | |
10 | |
11 #ifndef WEBRTC_MODULES_AUDIO_DEVICE_ANDROID_JVM_ANDROID_H_ | |
12 #define WEBRTC_MODULES_AUDIO_DEVICE_ANDROID_JVM_ANDROID_H_ | |
13 | |
14 #include <jni.h> | |
15 | |
16 #include <memory> | |
17 #include <string> | |
18 | |
19 #include "webrtc/base/thread_checker.h" | |
20 #include "webrtc/modules/audio_device/android/helpers_android.h" | |
21 | |
22 namespace webrtc { | |
23 | |
24 // The JNI interface pointer (JNIEnv) is valid only in the current thread. | |
25 // Should another thread need to access the Java VM, it must first call | |
26 // AttachCurrentThread() to attach itself to the VM and obtain a JNI interface | |
27 // pointer. The native thread remains attached to the VM until it calls | |
28 // DetachCurrentThread() to detach. | |
29 class AttachCurrentThreadIfNeeded { | |
30 public: | |
31 AttachCurrentThreadIfNeeded(); | |
32 ~AttachCurrentThreadIfNeeded(); | |
33 | |
34 private: | |
35 rtc::ThreadChecker thread_checker_; | |
36 bool attached_; | |
37 }; | |
38 | |
39 // This class is created by the NativeRegistration class and is used to wrap | |
40 // the actual Java object handle (jobject) on which we can call methods from | |
41 // C++ in to Java. See example in JVM for more details. | |
42 // TODO(henrika): extend support for type of function calls. | |
43 class GlobalRef { | |
44 public: | |
45 GlobalRef(JNIEnv* jni, jobject object); | |
46 ~GlobalRef(); | |
47 | |
48 jboolean CallBooleanMethod(jmethodID methodID, ...); | |
49 jint CallIntMethod(jmethodID methodID, ...); | |
50 void CallVoidMethod(jmethodID methodID, ...); | |
51 | |
52 private: | |
53 JNIEnv* const jni_; | |
54 const jobject j_object_; | |
55 }; | |
56 | |
57 // Wraps the jclass object on which we can call GetMethodId() functions to | |
58 // query method IDs. | |
59 class JavaClass { | |
60 public: | |
61 JavaClass(JNIEnv* jni, jclass clazz) : jni_(jni), j_class_(clazz) {} | |
62 ~JavaClass() {} | |
63 | |
64 jmethodID GetMethodId(const char* name, const char* signature); | |
65 jmethodID GetStaticMethodId(const char* name, const char* signature); | |
66 jobject CallStaticObjectMethod(jmethodID methodID, ...); | |
67 jint CallStaticIntMethod(jmethodID methodID, ...); | |
68 | |
69 protected: | |
70 JNIEnv* const jni_; | |
71 jclass const j_class_; | |
72 }; | |
73 | |
74 // Adds support of the NewObject factory method to the JavaClass class. | |
75 // See example in JVM for more details on how to use it. | |
76 class NativeRegistration : public JavaClass { | |
77 public: | |
78 NativeRegistration(JNIEnv* jni, jclass clazz); | |
79 ~NativeRegistration(); | |
80 | |
81 std::unique_ptr<GlobalRef> NewObject( | |
82 const char* name, const char* signature, ...); | |
83 | |
84 private: | |
85 JNIEnv* const jni_; | |
86 }; | |
87 | |
88 // This class is created by the JVM class and is used to expose methods that | |
89 // needs the JNI interface pointer but its main purpose is to create a | |
90 // NativeRegistration object given name of a Java class and a list of native | |
91 // methods. See example in JVM for more details. | |
92 class JNIEnvironment { | |
93 public: | |
94 explicit JNIEnvironment(JNIEnv* jni); | |
95 ~JNIEnvironment(); | |
96 | |
97 // Registers native methods with the Java class specified by |name|. | |
98 // Note that the class name must be one of the names in the static | |
99 // |loaded_classes| array defined in jvm_android.cc. | |
100 // This method must be called on the construction thread. | |
101 std::unique_ptr<NativeRegistration> RegisterNatives( | |
102 const char* name, const JNINativeMethod *methods, int num_methods); | |
103 | |
104 // Converts from Java string to std::string. | |
105 // This method must be called on the construction thread. | |
106 std::string JavaToStdString(const jstring& j_string); | |
107 | |
108 private: | |
109 rtc::ThreadChecker thread_checker_; | |
110 JNIEnv* const jni_; | |
111 }; | |
112 | |
113 // Main class for working with Java from C++ using JNI in WebRTC. | |
114 // | |
115 // Example usage: | |
116 // | |
117 // // At initialization (e.g. in JNI_OnLoad), call JVM::Initialize. | |
118 // JNIEnv* jni = ::base::android::AttachCurrentThread(); | |
119 // JavaVM* jvm = NULL; | |
120 // jni->GetJavaVM(&jvm); | |
121 // jobject context = ::base::android::GetApplicationContext(); | |
122 // webrtc::JVM::Initialize(jvm, context); | |
123 // | |
124 // // Header (.h) file of example class called User. | |
125 // std::unique_ptr<JNIEnvironment> env; | |
126 // std::unique_ptr<NativeRegistration> reg; | |
127 // std::unique_ptr<GlobalRef> obj; | |
128 // | |
129 // // Construction (in .cc file) of User class. | |
130 // User::User() { | |
131 // // Calling thread must be attached to the JVM. | |
132 // env = JVM::GetInstance()->environment(); | |
133 // reg = env->RegisterNatives("org/webrtc/WebRtcTest", ,); | |
134 // obj = reg->NewObject("<init>", ,); | |
135 // } | |
136 // | |
137 // // Each User method can now use |reg| and |obj| and call Java functions | |
138 // // in WebRtcTest.java, e.g. boolean init() {}. | |
139 // bool User::Foo() { | |
140 // jmethodID id = reg->GetMethodId("init", "()Z"); | |
141 // return obj->CallBooleanMethod(id); | |
142 // } | |
143 // | |
144 // // And finally, e.g. in JNI_OnUnLoad, call JVM::Uninitialize. | |
145 // JVM::Uninitialize(); | |
146 class JVM { | |
147 public: | |
148 // Stores global handles to the Java VM interface and the application context. | |
149 // Should be called once on a thread that is attached to the JVM. | |
150 static void Initialize(JavaVM* jvm, jobject context); | |
151 // Clears handles stored in Initialize(). Must be called on same thread as | |
152 // Initialize(). | |
153 static void Uninitialize(); | |
154 // Gives access to the global Java VM interface pointer, which then can be | |
155 // used to create a valid JNIEnvironment object or to get a JavaClass object. | |
156 static JVM* GetInstance(); | |
157 | |
158 // Creates a JNIEnvironment object. | |
159 // This method returns a NULL pointer if AttachCurrentThread() has not been | |
160 // called successfully. Use the AttachCurrentThreadIfNeeded class if needed. | |
161 std::unique_ptr<JNIEnvironment> environment(); | |
162 | |
163 // Returns a JavaClass object given class |name|. | |
164 // Note that the class name must be one of the names in the static | |
165 // |loaded_classes| array defined in jvm_android.cc. | |
166 // This method must be called on the construction thread. | |
167 JavaClass GetClass(const char* name); | |
168 | |
169 // TODO(henrika): can we make these private? | |
170 JavaVM* jvm() const { return jvm_; } | |
171 jobject context() const { return context_; } | |
172 | |
173 protected: | |
174 JVM(JavaVM* jvm, jobject context); | |
175 ~JVM(); | |
176 | |
177 private: | |
178 JNIEnv* jni() const { return GetEnv(jvm_); } | |
179 | |
180 rtc::ThreadChecker thread_checker_; | |
181 JavaVM* const jvm_; | |
182 jobject context_; | |
183 }; | |
184 | |
185 } // namespace webrtc | |
186 | |
187 #endif // WEBRTC_MODULES_AUDIO_DEVICE_ANDROID_JVM_ANDROID_H_ | |
OLD | NEW |