1 // Copyright (c) 2012 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_ANDROID_H_
6 #define BASE_ANDROID_JNI_ANDROID_H_
7 
8 #include <jni.h>
9 #include <sys/types.h>
10 
11 #include <string>
12 
13 #include "base/android/scoped_java_ref.h"
14 #include "base/atomicops.h"
15 #include "base/base_export.h"
16 #include "base/compiler_specific.h"
17 
18 namespace base {
19 namespace android {
20 
21 // Used to mark symbols to be exported in a shared library's symbol table.
22 #define JNI_EXPORT __attribute__ ((visibility("default")))
23 
24 // Used to disable manual JNI registration in binaries that prefer to use native
25 // JNI exports for startup performance. This is not compatible with the crazy
26 // linker and so defaults to off. Call DisableManualJniRegistration at the very
27 // beginning of JNI_OnLoad to use this.
28 BASE_EXPORT bool IsManualJniRegistrationDisabled();
29 BASE_EXPORT void DisableManualJniRegistration();
30 
31 // Contains the registration method information for initializing JNI bindings.
32 struct RegistrationMethod {
33   const char* name;
34   bool (*func)(JNIEnv* env);
35 };
36 
37 // Attaches the current thread to the VM (if necessary) and return the JNIEnv*.
38 BASE_EXPORT JNIEnv* AttachCurrentThread();
39 
40 // Same to AttachCurrentThread except that thread name will be set to
41 // |thread_name| if it is the first call. Otherwise, thread_name won't be
42 // changed. AttachCurrentThread() doesn't regard underlying platform thread
43 // name, but just resets it to "Thread-???". This function should be called
44 // right after new thread is created if it is important to keep thread name.
45 BASE_EXPORT JNIEnv* AttachCurrentThreadWithName(const std::string& thread_name);
46 
47 // Detaches the current thread from VM if it is attached.
48 BASE_EXPORT void DetachFromVM();
49 
50 // Initializes the global JVM.
51 BASE_EXPORT void InitVM(JavaVM* vm);
52 
53 // Returns true if the global JVM has been initialized.
54 BASE_EXPORT bool IsVMInitialized();
55 
56 // Initializes the global ClassLoader used by the GetClass and LazyGetClass
57 // methods. This is needed because JNI will use the base ClassLoader when there
58 // is no Java code on the stack. The base ClassLoader doesn't know about any of
59 // the application classes and will fail to lookup anything other than system
60 // classes.
61 BASE_EXPORT void InitReplacementClassLoader(
62     JNIEnv* env,
63     const JavaRef<jobject>& class_loader);
64 
65 // Finds the class named |class_name| and returns it.
66 // Use this method instead of invoking directly the JNI FindClass method (to
67 // prevent leaking local references).
68 // This method triggers a fatal assertion if the class could not be found.
69 // Use HasClass if you need to check whether the class exists.
70 BASE_EXPORT ScopedJavaLocalRef<jclass> GetClass(JNIEnv* env,
71                                                 const char* class_name);
72 
73 // The method will initialize |atomic_class_id| to contain a global ref to the
74 // class. And will return that ref on subsequent calls.  It's the caller's
75 // responsibility to release the ref when it is no longer needed.
76 // The caller is responsible to zero-initialize |atomic_method_id|.
77 // It's fine to simultaneously call this on multiple threads referencing the
78 // same |atomic_method_id|.
79 BASE_EXPORT jclass LazyGetClass(
80     JNIEnv* env,
81     const char* class_name,
82     base::subtle::AtomicWord* atomic_class_id);
83 
84 // This class is a wrapper for JNIEnv Get(Static)MethodID.
85 class BASE_EXPORT MethodID {
86  public:
87   enum Type {
88     TYPE_STATIC,
89     TYPE_INSTANCE,
90   };
91 
92   // Returns the method ID for the method with the specified name and signature.
93   // This method triggers a fatal assertion if the method could not be found.
94   template<Type type>
95   static jmethodID Get(JNIEnv* env,
96                        jclass clazz,
97                        const char* method_name,
98                        const char* jni_signature);
99 
100   // The caller is responsible to zero-initialize |atomic_method_id|.
101   // It's fine to simultaneously call this on multiple threads referencing the
102   // same |atomic_method_id|.
103   template<Type type>
104   static jmethodID LazyGet(JNIEnv* env,
105                            jclass clazz,
106                            const char* method_name,
107                            const char* jni_signature,
108                            base::subtle::AtomicWord* atomic_method_id);
109 };
110 
111 // Returns true if an exception is pending in the provided JNIEnv*.
112 BASE_EXPORT bool HasException(JNIEnv* env);
113 
114 // If an exception is pending in the provided JNIEnv*, this function clears it
115 // and returns true.
116 BASE_EXPORT bool ClearException(JNIEnv* env);
117 
118 // This function will call CHECK() macro if there's any pending exception.
119 BASE_EXPORT void CheckException(JNIEnv* env);
120 
121 // This returns a string representation of the java stack trace.
122 BASE_EXPORT std::string GetJavaExceptionInfo(JNIEnv* env,
123                                              jthrowable java_throwable);
124 
125 }  // namespace android
126 }  // namespace base
127 
128 #endif  // BASE_ANDROID_JNI_ANDROID_H_
129