Home | History | Annotate | Download | only in android 
      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