1# libnativehelper
2
3libnativehelper is a collection of JNI related utilities used in Android.
4
5There are several header and binary libraries here and not all of the
6functionality fits together well. The header libraries are mostly C++
7based. The binary libraries are entirely written in C with no C++
8dependencies. This is by design as the code here can be distributed in
9multiple ways, including mainline modules, so keeping the size down
10benefits everyone with smaller downloads and a stable ABI.
11
12## Header Libraries
13
14### jni_headers
15
16This is a header library that provides the API in the JNI Specification 1.6.
17Any project in Android that includes `jni.h` should depend on this.
18
19See:
20
21* [jni.h](include_jni/jni.h)
22
23### libnativehelper_header_only
24
25Header library that provide utilities defined entirely within the headers. There
26are scoped resource classes that make common JNI patterns of acquiring and
27releasing resources safer to use than the JNI specification equivalents.
28Examples being `ScopedLocalRef` to manage the lifetime of local references and
29`ScopedUtfChars` to manage the lifetime of Java strings in native code and
30provide access to utf8 characters.
31
32See:
33
34* [nativehelper/nativehelper_utils.h](header_only_include/nativehelper/nativehelper_utils.h)
35* [nativehelper/scoped_utf_chars.h](header_only_include/nativehelper/scoped_utf_chars.h)
36* [nativehelper/scoped_string_chars.h](header_only_include/nativehelper/scoped_string_chars.h)
37* [nativehelper/scoped_primitive_array.h](header_only_include/nativehelper/scoped_primitive_array.h)
38* [nativehelper/scoped_local_ref.h](header_only_include/nativehelper/scoped_local_ref.h)
39* [nativehelper/scoped_local_frame.h](header_only_include/nativehelper/scoped_local_frame.h)
40* [nativehelper/utils.h](header_only_include/nativehelper/utils.h)
41
42### jni_platform_headers
43
44The `jni_macros.h` header provide compile time checking of JNI methods
45implemented in C++. They ensure the C++ method declaration match the
46Java signature they are associated with.
47
48See:
49
50* [nativehelper/jni_macros.h](include_platform_header_only/nativehelper/jni_macros.h)
51
52## Libraries
53
54### libnativehelper
55
56A shared library distributed in the ART module. It provides the JNI invocation
57API from the JNI Specification, which is part of the public NDK. It also
58contains the glue that connects the API implementation to the ART runtime, which
59is platform only and is used with the Zygote and the standalone dalvikvm.
60
61See:
62
63* [nativehelper/JniInvocation.h](include_platform/nativehelper/JniInvocation.h)
64* [nativehelper/JNIPlatformHelp.h](include_platform/nativehelper/JNIPlatformHelp.h)
65* libnativehelper_compat_libc++ headers below
66
67### libnativehelper_compat_libc++
68
69This shared and static library contains a subset of the helper routines in
70libnativehelper based only on public stable JNI APIs. It gets distributed with
71the caller code and is preferrably linked statically since it is very thin (less
72than 20 KB). The name of this library is a misnomer since it contains no C++
73code.
74
75See:
76
77* [nativehelper/JNIHelp.h](include/nativehelper/JNIHelp.h)
78* [nativehelper/ScopedUtfChars.h](include/nativehelper/ScopedUtfChars.h)
79* [nativehelper/ScopedLocalFrame.h](include/nativehelper/ScopedLocalFrame.h)
80* [nativehelper/ScopedLocalRef.h](include/nativehelper/ScopedLocalRef.h)
81* [nativehelper/ScopedPrimitiveArray.h](include/nativehelper/ScopedPrimitiveArray.h)
82* [nativehelper/ScopedStringChars.h](include/nativehelper/ScopedStringChars.h)
83* [nativehelper/toStringArray.h](include/nativehelper/toStringArray.h)
84* [nativehelper/Utils.h](include/nativehelper/Utils.h)
85