native_bridge.h revision cd2ef4c1af69727231b84ebc82864c170ff0e8ad 
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// Check whether a native bridge is available (initialized). Requires a prior call to
33// SetupNativeBridge to make sense.
34bool NativeBridgeAvailable();
35
36// Load a shared library that is supported by the native bridge.
37void* NativeBridgeLoadLibrary(const char* libpath, int flag);
38
39// Get a native bridge trampoline for specified native method.
40void* NativeBridgeGetTrampoline(void* handle, const char* name, const char* shorty, uint32_t len);
41
42// True if native library is valid and is for an ABI that is supported by native bridge.
43bool NativeBridgeIsSupported(const char* libpath);
44
45// Returns whether we have seen a native bridge error. This could happen because the library
46// was not found, rejected, could not be initialized and so on.
47//
48// This functionality is mainly for testing.
49bool NativeBridgeError();
50
51// Returns whether a given string is acceptable as a native bridge library filename.
52//
53// This functionality is exposed mainly for testing.
54bool NativeBridgeNameAcceptable(const char* native_bridge_library_filename);
55
56// Native bridge interfaces to runtime.
57struct NativeBridgeCallbacks {
58  // Initialize native bridge. Native bridge's internal implementation must ensure MT safety and
59  // that the native bridge is initialized only once. Thus it is OK to call this interface for an
60  // already initialized native bridge.
61  //
62  // Parameters:
63  //   runtime_cbs [IN] the pointer to NativeBridgeRuntimeCallbacks.
64  // Returns:
65  //   true iff initialization was successful.
66  bool (*initialize)(const NativeBridgeRuntimeCallbacks* runtime_cbs);
67
68  // Load a shared library that is supported by the native bridge.
69  //
70  // Parameters:
71  //   libpath [IN] path to the shared library
72  //   flag [IN] the stardard RTLD_XXX defined in bionic dlfcn.h
73  // Returns:
74  //   The opaque handle of the shared library if sucessful, otherwise NULL
75  void* (*loadLibrary)(const char* libpath, int flag);
76
77  // Get a native bridge trampoline for specified native method. The trampoline has same
78  // sigature as the native method.
79  //
80  // Parameters:
81  //   handle [IN] the handle returned from loadLibrary
82  //   shorty [IN] short descriptor of native method
83  //   len [IN] length of shorty
84  // Returns:
85  //   address of trampoline if successful, otherwise NULL
86  void* (*getTrampoline)(void* handle, const char* name, const char* shorty, uint32_t len);
87
88  // Check whether native library is valid and is for an ABI that is supported by native bridge.
89  //
90  // Parameters:
91  //   libpath [IN] path to the shared library
92  // Returns:
93  //   TRUE if library is supported by native bridge, FALSE otherwise
94  bool (*isSupported)(const char* libpath);
95};
96
97// Runtime interfaces to native bridge.
98struct NativeBridgeRuntimeCallbacks {
99  // Get shorty of a Java method. The shorty is supposed to be persistent in memory.
100  //
101  // Parameters:
102  //   env [IN] pointer to JNIenv.
103  //   mid [IN] Java methodID.
104  // Returns:
105  //   short descriptor for method.
106  const char* (*getMethodShorty)(JNIEnv* env, jmethodID mid);
107
108  // Get number of native methods for specified class.
109  //
110  // Parameters:
111  //   env [IN] pointer to JNIenv.
112  //   clazz [IN] Java class object.
113  // Returns:
114  //   number of native methods.
115  uint32_t (*getNativeMethodCount)(JNIEnv* env, jclass clazz);
116
117  // Get at most 'method_count' native methods for specified class 'clazz'. Results are outputed
118  // via 'methods' [OUT]. The signature pointer in JNINativeMethod is reused as the method shorty.
119  //
120  // Parameters:
121  //   env [IN] pointer to JNIenv.
122  //   clazz [IN] Java class object.
123  //   methods [OUT] array of method with the name, shorty, and fnPtr.
124  //   method_count [IN] max number of elements in methods.
125  // Returns:
126  //   number of method it actually wrote to methods.
127  uint32_t (*getNativeMethods)(JNIEnv* env, jclass clazz, JNINativeMethod* methods,
128                               uint32_t method_count);
129};
130
131};  // namespace android
132
133#endif  // NATIVE_BRIDGE_H_
134