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
18namespace base {
19namespace 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// Contains the registration method information for initializing JNI bindings.
25struct RegistrationMethod {
26  const char* name;
27  bool (*func)(JNIEnv* env);
28};
29
30// Attaches the current thread to the VM (if necessary) and return the JNIEnv*.
31BASE_EXPORT JNIEnv* AttachCurrentThread();
32
33// Same to AttachCurrentThread except that thread name will be set to
34// |thread_name| if it is the first call. Otherwise, thread_name won't be
35// changed. AttachCurrentThread() doesn't regard underlying platform thread
36// name, but just resets it to "Thread-???". This function should be called
37// right after new thread is created if it is important to keep thread name.
38BASE_EXPORT JNIEnv* AttachCurrentThreadWithName(const std::string& thread_name);
39
40// Detaches the current thread from VM if it is attached.
41BASE_EXPORT void DetachFromVM();
42
43// Initializes the global JVM. It is not necessarily called before
44// InitApplicationContext().
45BASE_EXPORT void InitVM(JavaVM* vm);
46
47// Returns true if the global JVM has been initialized.
48BASE_EXPORT bool IsVMInitialized();
49
50// Initializes the global application context object. The |context| can be any
51// valid reference to the application context. Internally holds a global ref to
52// the context. InitVM and InitApplicationContext maybe called in either order.
53BASE_EXPORT void InitApplicationContext(JNIEnv* env,
54                                        const JavaRef<jobject>& context);
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.
61BASE_EXPORT void InitReplacementClassLoader(
62    JNIEnv* env,
63    const JavaRef<jobject>& class_loader);
64
65// Gets a global ref to the application context set with
66// InitApplicationContext(). Ownership is retained by the function - the caller
67// must NOT release it.
68const BASE_EXPORT jobject GetApplicationContext();
69
70// Finds the class named |class_name| and returns it.
71// Use this method instead of invoking directly the JNI FindClass method (to
72// prevent leaking local references).
73// This method triggers a fatal assertion if the class could not be found.
74// Use HasClass if you need to check whether the class exists.
75BASE_EXPORT ScopedJavaLocalRef<jclass> GetClass(JNIEnv* env,
76                                                const char* class_name);
77
78// The method will initialize |atomic_class_id| to contain a global ref to the
79// class. And will return that ref on subsequent calls.  It's the caller's
80// responsibility to release the ref when it is no longer needed.
81// The caller is responsible to zero-initialize |atomic_method_id|.
82// It's fine to simultaneously call this on multiple threads referencing the
83// same |atomic_method_id|.
84BASE_EXPORT jclass LazyGetClass(
85    JNIEnv* env,
86    const char* class_name,
87    base::subtle::AtomicWord* atomic_class_id);
88
89// This class is a wrapper for JNIEnv Get(Static)MethodID.
90class BASE_EXPORT MethodID {
91 public:
92  enum Type {
93    TYPE_STATIC,
94    TYPE_INSTANCE,
95  };
96
97  // Returns the method ID for the method with the specified name and signature.
98  // This method triggers a fatal assertion if the method could not be found.
99  template<Type type>
100  static jmethodID Get(JNIEnv* env,
101                       jclass clazz,
102                       const char* method_name,
103                       const char* jni_signature);
104
105  // The caller is responsible to zero-initialize |atomic_method_id|.
106  // It's fine to simultaneously call this on multiple threads referencing the
107  // same |atomic_method_id|.
108  template<Type type>
109  static jmethodID LazyGet(JNIEnv* env,
110                           jclass clazz,
111                           const char* method_name,
112                           const char* jni_signature,
113                           base::subtle::AtomicWord* atomic_method_id);
114};
115
116// Returns true if an exception is pending in the provided JNIEnv*.
117BASE_EXPORT bool HasException(JNIEnv* env);
118
119// If an exception is pending in the provided JNIEnv*, this function clears it
120// and returns true.
121BASE_EXPORT bool ClearException(JNIEnv* env);
122
123// This function will call CHECK() macro if there's any pending exception.
124BASE_EXPORT void CheckException(JNIEnv* env);
125
126}  // namespace android
127}  // namespace base
128
129#endif  // BASE_ANDROID_JNI_ANDROID_H_
130