Home | History | Annotate | Download | only in nativehelper 
      1 /*
      2  * Copyright (C) 2007 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 /*
     18  * JNI helper functions.
     19  *
     20  * This file may be included by C or C++ code, which is trouble because jni.h
     21  * uses different typedefs for JNIEnv in each language.
     22  */
     23 #ifndef NATIVEHELPER_JNIHELP_H_
     24 #define NATIVEHELPER_JNIHELP_H_
     25 
     26 #include "jni.h"
     27 #include "cutils/log.h"
     28 #include <unistd.h>
     29 
     30 #ifndef NELEM
     31 # define NELEM(x) ((int) (sizeof(x) / sizeof((x)[0])))
     32 #endif
     33 
     34 #ifdef __cplusplus
     35 extern "C" {
     36 #endif
     37 
     38 /*
     39  * Register one or more native methods with a particular class.
     40  * "className" looks like "java/lang/String".
     41  */
     42 int jniRegisterNativeMethods(C_JNIEnv* env, const char* className, const JNINativeMethod* gMethods, int numMethods);
     43 
     44 /*
     45  * Throw an exception with the specified class and an optional message.
     46  *
     47  * The "className" argument will be passed directly to FindClass, which
     48  * takes strings with slashes (e.g. "java/lang/Object").
     49  *
     50  * If an exception is currently pending, we log a warning message and
     51  * clear it.
     52  *
     53  * Returns 0 on success, nonzero if something failed (e.g. the exception
     54  * class couldn't be found, so *an* exception will still be pending).
     55  *
     56  * Currently aborts the VM if it can't throw the exception.
     57  */
     58 int jniThrowException(C_JNIEnv* env, const char* className, const char* msg);
     59 
     60 /*
     61  * Throw a java.lang.NullPointerException, with an optional message.
     62  */
     63 int jniThrowNullPointerException(C_JNIEnv* env, const char* msg);
     64 
     65 /*
     66  * Throw a java.lang.RuntimeException, with an optional message.
     67  */
     68 int jniThrowRuntimeException(C_JNIEnv* env, const char* msg);
     69 
     70 /*
     71  * Throw a java.io.IOException, generating the message from errno.
     72  */
     73 int jniThrowIOException(C_JNIEnv* env, int errnum);
     74 
     75 /*
     76  * Return a pointer to a locale-dependent error string explaining errno
     77  * value 'errnum'. The returned pointer may or may not be equal to 'buf'.
     78  * This function is thread-safe (unlike strerror) and portable (unlike
     79  * strerror_r).
     80  */
     81 const char* jniStrError(int errnum, char* buf, size_t buflen);
     82 
     83 /*
     84  * Returns a new java.io.FileDescriptor for the given int fd.
     85  */
     86 jobject jniCreateFileDescriptor(C_JNIEnv* env, int fd);
     87 
     88 /*
     89  * Returns the int fd from a java.io.FileDescriptor.
     90  */
     91 int jniGetFDFromFileDescriptor(C_JNIEnv* env, jobject fileDescriptor);
     92 
     93 /*
     94  * Sets the int fd in a java.io.FileDescriptor.
     95  */
     96 void jniSetFileDescriptorOfFD(C_JNIEnv* env, jobject fileDescriptor, int value);
     97 
     98 /*
     99  * Log a message and an exception.
    100  * If exception is NULL, logs the current exception in the JNI environment.
    101  */
    102 void jniLogException(C_JNIEnv* env, int priority, const char* tag, jthrowable exception);
    103 
    104 #ifdef __cplusplus
    105 }
    106 #endif
    107 
    108 
    109 /*
    110  * For C++ code, we provide inlines that map to the C functions.  g++ always
    111  * inlines these, even on non-optimized builds.
    112  */
    113 #if defined(__cplusplus)
    114 inline int jniRegisterNativeMethods(JNIEnv* env, const char* className, const JNINativeMethod* gMethods, int numMethods) {
    115     return jniRegisterNativeMethods(&env->functions, className, gMethods, numMethods);
    116 }
    117 
    118 inline int jniThrowException(JNIEnv* env, const char* className, const char* msg) {
    119     return jniThrowException(&env->functions, className, msg);
    120 }
    121 
    122 extern "C" int jniThrowExceptionFmt(C_JNIEnv* env, const char* className, const char* fmt, va_list args);
    123 
    124 /*
    125  * Equivalent to jniThrowException but with a printf-like format string and
    126  * variable-length argument list. This is only available in C++.
    127  */
    128 inline int jniThrowExceptionFmt(JNIEnv* env, const char* className, const char* fmt, ...) {
    129     va_list args;
    130     va_start(args, fmt);
    131     return jniThrowExceptionFmt(&env->functions, className, fmt, args);
    132     va_end(args);
    133 }
    134 
    135 inline int jniThrowNullPointerException(JNIEnv* env, const char* msg) {
    136     return jniThrowNullPointerException(&env->functions, msg);
    137 }
    138 
    139 inline int jniThrowRuntimeException(JNIEnv* env, const char* msg) {
    140     return jniThrowRuntimeException(&env->functions, msg);
    141 }
    142 
    143 inline int jniThrowIOException(JNIEnv* env, int errnum) {
    144     return jniThrowIOException(&env->functions, errnum);
    145 }
    146 
    147 inline jobject jniCreateFileDescriptor(JNIEnv* env, int fd) {
    148     return jniCreateFileDescriptor(&env->functions, fd);
    149 }
    150 
    151 inline int jniGetFDFromFileDescriptor(JNIEnv* env, jobject fileDescriptor) {
    152     return jniGetFDFromFileDescriptor(&env->functions, fileDescriptor);
    153 }
    154 
    155 inline void jniSetFileDescriptorOfFD(JNIEnv* env, jobject fileDescriptor, int value) {
    156     jniSetFileDescriptorOfFD(&env->functions, fileDescriptor, value);
    157 }
    158 
    159 inline void jniLogException(JNIEnv* env, int priority, const char* tag, jthrowable exception = NULL) {
    160     jniLogException(&env->functions, priority, tag, exception);
    161 }
    162 #endif
    163 
    164 /* Logging macros.
    165  *
    166  * Logs an exception.  If the exception is omitted or NULL, logs the current exception
    167  * from the JNI environment, if any.
    168  */
    169 #define LOG_EX(env, priority, tag, ...) \
    170     IF_LOG(priority, tag) jniLogException(env, ANDROID_##priority, tag, ##__VA_ARGS__)
    171 #define LOGV_EX(env, ...) LOG_EX(env, LOG_VERBOSE, LOG_TAG, ##__VA_ARGS__)
    172 #define LOGD_EX(env, ...) LOG_EX(env, LOG_DEBUG, LOG_TAG, ##__VA_ARGS__)
    173 #define LOGI_EX(env, ...) LOG_EX(env, LOG_INFO, LOG_TAG, ##__VA_ARGS__)
    174 #define LOGW_EX(env, ...) LOG_EX(env, LOG_WARN, LOG_TAG, ##__VA_ARGS__)
    175 #define LOGE_EX(env, ...) LOG_EX(env, LOG_ERROR, LOG_TAG, ##__VA_ARGS__)
    176 
    177 /*
    178  * TEMP_FAILURE_RETRY is defined by some, but not all, versions of
    179  * <unistd.h>. (Alas, it is not as standard as we'd hoped!) So, if it's
    180  * not already defined, then define it here.
    181  */
    182 #ifndef TEMP_FAILURE_RETRY
    183 /* Used to retry syscalls that can return EINTR. */
    184 #define TEMP_FAILURE_RETRY(exp) ({         \
    185     typeof (exp) _rc;                      \
    186     do {                                   \
    187         _rc = (exp);                       \
    188     } while (_rc == -1 && errno == EINTR); \
    189     _rc; })
    190 #endif
    191 
    192 #endif  /* NATIVEHELPER_JNIHELP_H_ */
    193