native_bridge.h revision 4914fcd91bcd75400c0e023974158912f077464c 
1/*
2 * Copyright (C) 2014 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#ifndef NATIVE_BRIDGE_H_
18#define NATIVE_BRIDGE_H_
19
20#include "jni.h"
21#include <stdint.h>
22
23namespace android {
24
25struct NativeBridgeRuntimeCallbacks;
26
27// Initialize the native bridge, if any. Should be called by Runtime::Init().
28// A null library filename signals that we do not want to load a native bridge.
29void SetupNativeBridge(const char* native_bridge_library_filename,
30                       const NativeBridgeRuntimeCallbacks* runtime_callbacks);
31
32// Load a shared library that is supported by the native bridge.
33void* NativeBridgeLoadLibrary(const char* libpath, int flag);
34
35// Get a native bridge trampoline for specified native method.
36void* NativeBridgeGetTrampoline(void* handle, const char* name, const char* shorty, uint32_t len);
37
38// True if native library is valid and is for an ABI that is supported by native bridge.
39bool NativeBridgeIsSupported(const char* libpath);
40
41// Native bridge interfaces to runtime.
42struct NativeBridgeCallbacks {
43  // Initialize native bridge. Native bridge's internal implementation must ensure MT safety and
44  // that the native bridge is initialized only once. Thus it is OK to call this interface for an
45  // already initialized native bridge.
46  //
47  // Parameters:
48  //   runtime_cbs [IN] the pointer to NativeBridgeRuntimeCallbacks.
49  // Returns:
50  //   true iff initialization was successful.
51  bool (*initialize)(const NativeBridgeRuntimeCallbacks* runtime_cbs);
52
53  // Load a shared library that is supported by the native bridge.
54  //
55  // Parameters:
56  //   libpath [IN] path to the shared library
57  //   flag [IN] the stardard RTLD_XXX defined in bionic dlfcn.h
58  // Returns:
59  //   The opaque handle of the shared library if sucessful, otherwise NULL
60  void* (*loadLibrary)(const char* libpath, int flag);
61
62  // Get a native bridge trampoline for specified native method. The trampoline has same
63  // sigature as the native method.
64  //
65  // Parameters:
66  //   handle [IN] the handle returned from loadLibrary
67  //   shorty [IN] short descriptor of native method
68  //   len [IN] length of shorty
69  // Returns:
70  //   address of trampoline if successful, otherwise NULL
71  void* (*getTrampoline)(void* handle, const char* name, const char* shorty, uint32_t len);
72
73  // Check whether native library is valid and is for an ABI that is supported by native bridge.
74  //
75  // Parameters:
76  //   libpath [IN] path to the shared library
77  // Returns:
78  //   TRUE if library is supported by native bridge, FALSE otherwise
79  bool (*isSupported)(const char* libpath);
80};
81
82// Runtime interfaces to native bridge.
83struct NativeBridgeRuntimeCallbacks {
84  // Get shorty of a Java method. The shorty is supposed to be persistent in memory.
85  //
86  // Parameters:
87  //   env [IN] pointer to JNIenv.
88  //   mid [IN] Java methodID.
89  // Returns:
90  //   short descriptor for method.
91  const char* (*getMethodShorty)(JNIEnv* env, jmethodID mid);
92
93  // Get number of native methods for specified class.
94  //
95  // Parameters:
96  //   env [IN] pointer to JNIenv.
97  //   clazz [IN] Java class object.
98  // Returns:
99  //   number of native methods.
100  uint32_t (*getNativeMethodCount)(JNIEnv* env, jclass clazz);
101
102  // Get at most 'method_count' native methods for specified class 'clazz'. Results are outputed
103  // via 'methods' [OUT]. The signature pointer in JNINativeMethod is reused as the method shorty.
104  //
105  // Parameters:
106  //   env [IN] pointer to JNIenv.
107  //   clazz [IN] Java class object.
108  //   methods [OUT] array of method with the name, shorty, and fnPtr.
109  //   method_count [IN] max number of elements in methods.
110  // Returns:
111  //   number of method it actually wrote to methods.
112  uint32_t (*getNativeMethods)(JNIEnv* env, jclass clazz, JNINativeMethod* methods,
113                               uint32_t method_count);
114};
115
116};  // namespace android
117
118#endif  // NATIVE_BRIDGE_H_
119