Home | History | Annotate | Download | only in jni 
      1 /*
      2  * libjingle
      3  * Copyright 2015 Google Inc.
      4  *
      5  * Redistribution and use in source and binary forms, with or without
      6  * modification, are permitted provided that the following conditions are met:
      7  *
      8  *  1. Redistributions of source code must retain the above copyright notice,
      9  *     this list of conditions and the following disclaimer.
     10  *  2. Redistributions in binary form must reproduce the above copyright notice,
     11  *     this list of conditions and the following disclaimer in the documentation
     12  *     and/or other materials provided with the distribution.
     13  *  3. The name of the author may not be used to endorse or promote products
     14  *     derived from this software without specific prior written permission.
     15  *
     16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
     17  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
     18  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
     19  * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     20  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
     22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
     23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
     24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
     25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     26  *
     27  */
     28 
     29 // This file contain convenience functions and classes for JNI.
     30 // Before using any of the methods, InitGlobalJniVariables must be called.
     31 
     32 #ifndef TALK_APP_WEBRTC_JAVA_JNI_JNI_HELPERS_H_
     33 #define TALK_APP_WEBRTC_JAVA_JNI_JNI_HELPERS_H_
     34 
     35 #include <jni.h>
     36 #include <string>
     37 
     38 #include "webrtc/base/checks.h"
     39 
     40 // Abort the process if |jni| has a Java exception pending.
     41 // This macros uses the comma operator to execute ExceptionDescribe
     42 // and ExceptionClear ignoring their return values and sending ""
     43 // to the error stream.
     44 #define CHECK_EXCEPTION(jni)        \
     45   RTC_CHECK(!jni->ExceptionCheck()) \
     46       << (jni->ExceptionDescribe(), jni->ExceptionClear(), "")
     47 
     48 // Helper that calls ptr->Release() and aborts the process with a useful
     49 // message if that didn't actually delete *ptr because of extra refcounts.
     50 #define CHECK_RELEASE(ptr) \
     51   RTC_CHECK_EQ(0, (ptr)->Release()) << "Unexpected refcount."
     52 
     53 namespace webrtc_jni {
     54 
     55 jint InitGlobalJniVariables(JavaVM *jvm);
     56 
     57 // Return a |JNIEnv*| usable on this thread or NULL if this thread is detached.
     58 JNIEnv* GetEnv();
     59 
     60 JavaVM *GetJVM();
     61 
     62 // Return a |JNIEnv*| usable on this thread.  Attaches to |g_jvm| if necessary.
     63 JNIEnv* AttachCurrentThreadIfNeeded();
     64 
     65 // Return a |jlong| that will correctly convert back to |ptr|.  This is needed
     66 // because the alternative (of silently passing a 32-bit pointer to a vararg
     67 // function expecting a 64-bit param) picks up garbage in the high 32 bits.
     68 jlong jlongFromPointer(void* ptr);
     69 
     70 // JNIEnv-helper methods that RTC_CHECK success: no Java exception thrown and
     71 // found object/class/method/field is non-null.
     72 jmethodID GetMethodID(
     73     JNIEnv* jni, jclass c, const std::string& name, const char* signature);
     74 
     75 jmethodID GetStaticMethodID(
     76     JNIEnv* jni, jclass c, const char* name, const char* signature);
     77 
     78 jfieldID GetFieldID(JNIEnv* jni, jclass c, const char* name,
     79                     const char* signature);
     80 
     81 jclass GetObjectClass(JNIEnv* jni, jobject object);
     82 
     83 jobject GetObjectField(JNIEnv* jni, jobject object, jfieldID id);
     84 
     85 jstring GetStringField(JNIEnv* jni, jobject object, jfieldID id);
     86 
     87 jlong GetLongField(JNIEnv* jni, jobject object, jfieldID id);
     88 
     89 jint GetIntField(JNIEnv* jni, jobject object, jfieldID id);
     90 
     91 bool GetBooleanField(JNIEnv* jni, jobject object, jfieldID id);
     92 
     93 // Java references to "null" can only be distinguished as such in C++ by
     94 // creating a local reference, so this helper wraps that logic.
     95 bool IsNull(JNIEnv* jni, jobject obj);
     96 
     97 // Given a UTF-8 encoded |native| string return a new (UTF-16) jstring.
     98 jstring JavaStringFromStdString(JNIEnv* jni, const std::string& native);
     99 
    100 // Given a (UTF-16) jstring return a new UTF-8 native string.
    101 std::string JavaToStdString(JNIEnv* jni, const jstring& j_string);
    102 
    103 // Return the (singleton) Java Enum object corresponding to |index|;
    104 jobject JavaEnumFromIndex(JNIEnv* jni, jclass state_class,
    105                           const std::string& state_class_name, int index);
    106 
    107 jobject NewGlobalRef(JNIEnv* jni, jobject o);
    108 
    109 void DeleteGlobalRef(JNIEnv* jni, jobject o);
    110 
    111 // Scope Java local references to the lifetime of this object.  Use in all C++
    112 // callbacks (i.e. entry points that don't originate in a Java callstack
    113 // through a "native" method call).
    114 class ScopedLocalRefFrame {
    115  public:
    116   explicit ScopedLocalRefFrame(JNIEnv* jni);
    117   ~ScopedLocalRefFrame();
    118 
    119  private:
    120   JNIEnv* jni_;
    121 };
    122 
    123 // Scoped holder for global Java refs.
    124 template<class T>  // T is jclass, jobject, jintArray, etc.
    125 class ScopedGlobalRef {
    126  public:
    127   ScopedGlobalRef(JNIEnv* jni, T obj)
    128       : obj_(static_cast<T>(jni->NewGlobalRef(obj))) {}
    129   ~ScopedGlobalRef() {
    130     DeleteGlobalRef(AttachCurrentThreadIfNeeded(), obj_);
    131   }
    132   T operator*() const {
    133     return obj_;
    134   }
    135  private:
    136   T obj_;
    137 };
    138 
    139 }  // namespace webrtc_jni
    140 
    141 #endif  // TALK_APP_WEBRTC_JAVA_JNI_JNI_HELPERS_H_
    142