base/android/jni_android.h

   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. It is not necessarily called before
  51 // InitApplicationContext().
  52 BASE_EXPORT void InitVM(JavaVM* vm);
  53
  54 // Returns true if the global JVM has been initialized.
  55 BASE_EXPORT bool IsVMInitialized();
  56
  57 // Initializes the global application context object. The |context| can be any
  58 // valid reference to the application context. Internally holds a global ref to
  59 // the context. InitVM and InitApplicationContext maybe called in either order.
  60 BASE_EXPORT void InitApplicationContext(JNIEnv* env,
  61                                         const JavaRef<jobject>& context);
  62
  63 // Initializes the global ClassLoader used by the GetClass and LazyGetClass
  64 // methods. This is needed because JNI will use the base ClassLoader when there
  65 // is no Java code on the stack. The base ClassLoader doesn't know about any of
  66 // the application classes and will fail to lookup anything other than system
  67 // classes.
  68 BASE_EXPORT void InitReplacementClassLoader(
  69     JNIEnv* env,
  70     const JavaRef<jobject>& class_loader);
  71
  72 // Gets a global ref to the application context set with
  73 // InitApplicationContext(). Ownership is retained by the function - the caller
  74 // must NOT release it.
  75 const BASE_EXPORT jobject GetApplicationContext();
  76
  77 // Finds the class named |class_name| and returns it.
  78 // Use this method instead of invoking directly the JNI FindClass method (to
  79 // prevent leaking local references).
  80 // This method triggers a fatal assertion if the class could not be found.
  81 // Use HasClass if you need to check whether the class exists.
  82 BASE_EXPORT ScopedJavaLocalRef<jclass> GetClass(JNIEnv* env,
  83                                                 const char* class_name);
  84
  85 // The method will initialize |atomic_class_id| to contain a global ref to the
  86 // class. And will return that ref on subsequent calls.  It's the caller's
  87 // responsibility to release the ref when it is no longer needed.
  88 // The caller is responsible to zero-initialize |atomic_method_id|.
  89 // It's fine to simultaneously call this on multiple threads referencing the
  90 // same |atomic_method_id|.
  91 BASE_EXPORT jclass LazyGetClass(
  92     JNIEnv* env,
  93     const char* class_name,
  94     base::subtle::AtomicWord* atomic_class_id);
  95
  96 // This class is a wrapper for JNIEnv Get(Static)MethodID.
  97 class BASE_EXPORT MethodID {
  98  public:
  99   enum Type {
 100     TYPE_STATIC,
 101     TYPE_INSTANCE,
 102   };
 103
 104   // Returns the method ID for the method with the specified name and signature.
 105   // This method triggers a fatal assertion if the method could not be found.
 106   template<Type type>
 107   static jmethodID Get(JNIEnv* env,
 108                        jclass clazz,
 109                        const char* method_name,
 110                        const char* jni_signature);
 111
 112   // The caller is responsible to zero-initialize |atomic_method_id|.
 113   // It's fine to simultaneously call this on multiple threads referencing the
 114   // same |atomic_method_id|.
 115   template<Type type>
 116   static jmethodID LazyGet(JNIEnv* env,
 117                            jclass clazz,
 118                            const char* method_name,
 119                            const char* jni_signature,
 120                            base::subtle::AtomicWord* atomic_method_id);
 121 };
 122
 123 // Returns true if an exception is pending in the provided JNIEnv*.
 124 BASE_EXPORT bool HasException(JNIEnv* env);
 125
 126 // If an exception is pending in the provided JNIEnv*, this function clears it
 127 // and returns true.
 128 BASE_EXPORT bool ClearException(JNIEnv* env);
 129
 130 // This function will call CHECK() macro if there's any pending exception.
 131 BASE_EXPORT void CheckException(JNIEnv* env);
 132
 133 // This returns a string representation of the java stack trace.
 134 BASE_EXPORT std::string GetJavaExceptionInfo(JNIEnv* env,
 135                                              jthrowable java_throwable);
 136
 137 }  // namespace android
 138 }  // namespace base
 139
 140 #endif  // BASE_ANDROID_JNI_ANDROID_H_