JNIHelp.h revision a6f951cbffc9ba9b906b5995958396402d0a32ab 
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
35extern "C" {
36#endif
37
38/*
39 * Register one or more native methods with a particular class.
40 * "className" looks like "java/lang/String".
41 */
42int 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 */
58int jniThrowException(C_JNIEnv* env, const char* className, const char* msg);
59
60/*
61 * Throw a java.lang.NullPointerException, with an optional message.
62 */
63int jniThrowNullPointerException(C_JNIEnv* env, const char* msg);
64
65/*
66 * Throw a java.lang.RuntimeException, with an optional message.
67 */
68int jniThrowRuntimeException(C_JNIEnv* env, const char* msg);
69
70/*
71 * Throw a java.io.IOException, generating the message from errno.
72 */
73int 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 */
81const char* jniStrError(int errnum, char* buf, size_t buflen);
82
83/*
84 * Returns a new java.io.FileDescriptor for the given int fd.
85 */
86jobject jniCreateFileDescriptor(C_JNIEnv* env, int fd);
87
88/*
89 * Returns the int fd from a java.io.FileDescriptor.
90 */
91int jniGetFDFromFileDescriptor(C_JNIEnv* env, jobject fileDescriptor);
92
93/*
94 * Sets the int fd in a java.io.FileDescriptor.
95 */
96void 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 */
102void 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)
114inline int jniRegisterNativeMethods(JNIEnv* env, const char* className, const JNINativeMethod* gMethods, int numMethods) {
115    return jniRegisterNativeMethods(&env->functions, className, gMethods, numMethods);
116}
117
118inline int jniThrowException(JNIEnv* env, const char* className, const char* msg) {
119    return jniThrowException(&env->functions, className, msg);
120}
121
122extern "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 */
128inline 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
135inline int jniThrowNullPointerException(JNIEnv* env, const char* msg) {
136    return jniThrowNullPointerException(&env->functions, msg);
137}
138
139inline int jniThrowRuntimeException(JNIEnv* env, const char* msg) {
140    return jniThrowRuntimeException(&env->functions, msg);
141}
142
143inline int jniThrowIOException(JNIEnv* env, int errnum) {
144    return jniThrowIOException(&env->functions, errnum);
145}
146
147inline jobject jniCreateFileDescriptor(JNIEnv* env, int fd) {
148    return jniCreateFileDescriptor(&env->functions, fd);
149}
150
151inline int jniGetFDFromFileDescriptor(JNIEnv* env, jobject fileDescriptor) {
152    return jniGetFDFromFileDescriptor(&env->functions, fileDescriptor);
153}
154
155inline void jniSetFileDescriptorOfFD(JNIEnv* env, jobject fileDescriptor, int value) {
156    jniSetFileDescriptorOfFD(&env->functions, fileDescriptor, value);
157}
158
159inline 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