库包装器指南

本指南介绍了如何使用 Android API 库包装器。库包装器命令行工具为 Java Android API 生成 C 语言包装器代码，使您能够将 Java 库集成到原生 C/C++ Android 应用中。有关库包装器的更多详细信息，请参阅 Android API 的库包装器。

此分步指南演示了如何使用包装器工具将 Java 库集成到原生 Android 应用中。出于示例目的，本指南涵盖了集成 通知库 的 androidx.core.app 包。请参阅 创建通知 以了解有关此库的更多信息。

先决条件

本指南假设您有一个现有的原生 Android 项目。它还使用 Gradle 构建系统。如果您没有现有的项目，请使用 **Native C++** 模板在 Android Studio 中创建一个新项目。

本指南中的示例代码使用目录根目录 my_project/。原生代码位于 my_project/app/src/main/cpp/，这是 Android Studio 项目的默认目录。

如果您还没有库包装器工具，请 下载 并将软件包解压缩到您选择的目录中。此 CLI 工具需要 Java 运行时环境 (JRE)。

生成原生代码

集成 Java 库时，请使用包装器工具生成原生代码包装器。第一步是配置包装器。

创建包装器配置

您可以创建库包装器 配置文件 来控制原生代码生成器的输出。此文件的一个功能允许您指定要为其生成包装器代码的类和方法。

由于通知库中没有太多方法需要包装，因此您可以直接在 custom_classes 部分中定义它们。在项目中的任何位置创建一个新的 config.json 资源以定义这些方法。例如，您可以创建 my_project/library_wrapper/config.json 并粘贴以下示例配置

{
  "custom_classes": [
    {
      "class_name": "class java.lang.CharSequence"
    },
    {
      "class_name": "class java.lang.Object",
      "methods": [
        "java.lang.String toString()"
      ]
    },
    {
      "class_name": "class java.lang.String"
    },
    {
      "class_name": "class android.content.Context",
      "methods": [
        "java.lang.Object getSystemService(java.lang.String name)"
      ]
    },
    {
      "class_name": "class android.app.Notification"
    },
    {
      "class_name": "class android.app.NotificationManager",
      "methods": [
        "void createNotificationChannel(android.app.NotificationChannel channel)"
      ]
    },
    {
      "class_name": "class android.app.NotificationChannel",
      "methods": [
        "NotificationChannel(java.lang.String id, java.lang.CharSequence name, int importance)",
        "void setDescription(java.lang.String description)"
      ]
    },
    {
      "class_name": "class androidx.core.app.NotificationCompat"
    },
    {
      "class_name": "class androidx.core.app.NotificationCompat$Builder",
      "methods": [
        "Builder(android.content.Context context, java.lang.String channelId)",
        "androidx.core.app.NotificationCompat$Builder setContentText(java.lang.CharSequence text)",
        "androidx.core.app.NotificationCompat$Builder setContentTitle(java.lang.CharSequence title)",
        "androidx.core.app.NotificationCompat$Builder setSmallIcon(int icon)",
        "androidx.core.app.NotificationCompat$Builder setPriority(int pri)",
        "android.app.Notification build()"
      ]
    },
    {
      "class_name": "class androidx.core.app.NotificationManagerCompat",
      "methods": [
        "static androidx.core.app.NotificationManagerCompat from(android.content.Context context)",
        "void notify(int id, android.app.Notification notification)"
      ]
    }
  ]
}

在前面的示例中，您直接声明了需要原生包装器代码的 Java 类和方法。

运行库包装器

定义了包装器配置文件后，您就可以使用该工具生成原生包装器代码了。打开一个终端到您解压缩库包装器的位置，并运行以下命令

java -jar lw.jar \
  -o "my_project/app/src/main/cpp/native_wrappers" \
  -c "my_project/library_wrapper/config.json"

在前面的示例中，您使用 -c 参数指定包装器配置位置，使用 -o 参数定义生成的代码目录。运行该工具后，您现在应该拥有了从原生应用调用基于 Java 的通知 API 所需的生成代码。

实现原生通知

在本节中，您将使用生成的包装器代码将 Android 通知库集成到您的原生应用中。第一步是更新项目的应用级 gradle.build 资源（my_project/app/gradle.build）。

更新 gradle.build

1. GNI 是生成的包装器代码所需的支撑库。所有使用生成代码的项目都应引用此库。要引用此库，请将以下行添加到 build.gradle 的 dependencies 部分

   implementation 'com.google.android.gms:play-services-gni-native-c:1.0.0-beta2'
   

2. 要启用 预制件 支持，请将以下代码添加到 android 部分

   buildFeatures {
     prefab true
   }
   

3. 要配置 cmake，请在 android/defaultConfig 部分使用以下 cmake 配置

   externalNativeBuild {
     cmake {
         arguments '-DANDROID_STL=c++_shared'
     }
   }
   

您已完成的 build.gradle 配置应类似于以下内容

android {
    ...

    buildFeatures {
        prefab true
    }

    defaultConfig {
        ...

        externalNativeBuild {
            cmake {
                arguments '-DANDROID_STL=c++_shared'
            }
        }
    }
}

dependencies {
    ...
    implementation 'com.google.android.gms:play-services-gni-native-c:1.0.0-beta2'
    ...
}

修改 CMakeLists

1. 通过在文件的顶层添加以下行，将 GNI 库添加到项目的 CMakeLists.txt（my_project/app/src/main/cpp/CMakeLists.txt）中

   find_package(com.google.android.gms.gni.c REQUIRED CONFIG)
   

2. 将以下行添加到 target_link_libraries 部分

   PUBLIC com.google.android.gms.gni.c::gni_shared
   

3. 通过在文件的顶层添加以下行来添加对生成代码的引用

   file(GLOB_RECURSE native_wrappers CONFIGURE_DEPENDS "native_wrappers/*.cpp" "native_wrappers/*.cc")
   

4. 在文件末尾附近添加以下几行

   include_directories(./native_wrappers/c)
   include_directories(./native_wrappers/cpp)
   

您更新后的 CMakeLists.txt 资源应类似于以下示例

cmake_minimum_required(VERSION 3.18.1)

project("my_project")

file(GLOB_RECURSE native_wrappers CONFIGURE_DEPENDS "native_wrappers/*.cpp" "native_wrappers/*.cc")

add_library(
        my_project
        SHARED
        native-lib.cpp
        ${native_wrappers}
        )

find_library(
        log-lib
        log)

find_package(com.google.android.gms.gni.c REQUIRED CONFIG)

target_link_libraries(
        my_project
        PUBLIC com.google.android.gms.gni.c::gni_shared
        ${log-lib})

include_directories(./native_wrappers/c)
include_directories(./native_wrappers/cpp)

实现通知逻辑

1. 打开或创建您想要实现通知功能的源文件。在此文件中，包含头文件 gni.h 并定义一个新的 ShowNativeNotification() 函数

   #include "gni/gni.h"
   
   void ShowNativeNotification(JNIEnv *env, jobject main_activity, int icon_id) {
     // Get the JavaVM from the JNIEnv.
     JavaVM *java_vm;
     env->GetJavaVM(&java_vm);
   
     // Initialize the GNI runtime. This function needs to be called before any
     // call to the generated code.
     GniCore_init(java_vm, main_activity);
   }
   

2. 定义特定于通知的常量值，以及通知处理程序函数 CharSequenceFromCString() 和 CreateNotification()

   C

   const int32_t IMPORTANCE_HIGH = 4;  // NotificationManager.IMPORTANCE_HIGH
   const int32_t PRIORITY_MAX = 2;  // NotificationCompat.PRIORITY_MAX
   const int32_t NOTIFICATION_ID = 123;  // User defined notification id.
   
   // Convert a C string into CharSequence.
   CharSequence *CharSequenceFromCString(const char *text) {
      String *string = String_fromCString(text);
      // Cast String to CharSequence. In Java, a String implements CharSequence.
      CharSequence *result = GNI_CAST(CharSequence, String, string);
      // Casting creates a new object, so it needs to be destroyed as normal.
      String_destroy(string);
      return result;
   }
   
   // Create a notification.
   Notification *
   CreateNotification(Context *context, String *channel_id,
                      const char *title, const char *content,
                      int32_t icon_id) {
      // Convert C strings to CharSequence.
      CharSequence *title_chars = CharSequenceFromCString(title);
      CharSequence *content_chars = CharSequenceFromCString(content);
   
      // Create a NotificationCompat.Builder and set all required properties.
      NotificationCompat_Builder *notification_builder =
          NotificationCompat_Builder_construct(context, channel_id);
      NotificationCompat_Builder_setContentTitle(notification_builder,
                                                 title_chars);
      NotificationCompat_Builder_setContentText(notification_builder,
                                                content_chars);
      NotificationCompat_Builder_setSmallIcon(notification_builder, icon_id);
      NotificationCompat_Builder_setPriority(notification_builder,
                                             PRIORITY_MAX);
   
      // Build a notification.
      Notification *notification =
          NotificationCompat_Builder_build(notification_builder);
   
      // Clean up allocated objects.
      NotificationCompat_Builder_destroy(notification_builder);
      CharSequence_destroy(title_chars);
      CharSequence_destroy(content_chars);
   
      return notification;
   }
   

   C++

   const int32_t IMPORTANCE_HIGH = 4;  // NotificationManager.IMPORTANCE_HIGH
   const int32_t PRIORITY_MAX = 2;  // NotificationCompat.PRIORITY_MAX
   const int32_t NOTIFICATION_ID = 123;  // User defined notification id.
   
   // Convert a C string into CharSequence.
   CharSequence *CharSequenceFromCString(const char *text) {
      String *string = String_fromCString(text);
      // Cast String to CharSequence. In Java, a String implements CharSequence.
      CharSequence *result = new CharSequence(string->GetImpl());
      // Casting creates a new object, so it needs to be destroyed as normal.
      String::destroy(string);
      return result;
   }
   
   // Create a notification.
   Notification&
   CreateNotification(Context *context, String *channel_id, const char *title,
                      const char *content, int32_t icon_id) {
      // Convert C strings to CharSequence.
      CharSequence *title_chars = CharSequenceFromCString(title);
      CharSequence *content_chars = CharSequenceFromCString(content);
   
      // Create a NotificationCompat.Builder and set all required properties.
   
      NotificationCompat::Builder *notification_builder = new NotificationCompat::Builder(*context, *channel_id);
      notification_builder->setContentTitle(*title_chars);
      notification_builder->setContentText(*content_chars);
      notification_builder->setSmallIcon(icon_id);
      notification_builder->setPriority(PRIORITY_MAX);
   
      // Build a notification.
      Notification& notification = notification_builder->build();
   
      // Clean up allocated objects.
      NotificationCompat::Builder::destroy(notification_builder);
      CharSequence::destroy(title_chars);
      CharSequence::destroy(content_chars);
   
      return notification;
   }
   

   通知库的一些函数使用 CharSequence 而不是 String。 CharSequenceFromCString() 函数支持在这些对象之间进行转换。 CreateNotification() 函数使用 Java 的包装版本 NotificationCompat.Builder 来创建通知。

3. 通过粘贴以下函数 CreateNotificationChannel() 添加创建通知通道的逻辑

   C

   void CreateNotificationChannel(Context *context, String *channel_id) {
      CharSequence *channel_name = CharSequenceFromCString("channel name");
      String *channel_description = String_fromCString("channel description");
      String *system_service_name = String_fromCString("notification");
      NotificationChannel *channel =
          NotificationChannel_construct(channel_id, channel_name,
                                        IMPORTANCE_HIGH);
      NotificationChannel_setDescription(channel, channel_description);
   
      Object *notification_manager_as_object =
          Context_getSystemService(context, system_service_name);
      NotificationManager *notification_manager =
          GNI_CAST(NotificationManager, Object,
                   notification_manager_as_object);
   
      NotificationManager_createNotificationChannel(notification_manager,
                                                    channel);
   
      CharSequence_destroy(channel_name);
      String_destroy(channel_description);
      String_destroy(system_service_name);
      NotificationChannel_destroy(channel);
      Object_destroy(notification_manager_as_object);
      NotificationManager_destroy(notification_manager);
   }
   

   C++

   void CreateNotificationChannel(Context *context, String *channel_id) {
      CharSequence *channel_name = CharSequenceFromCString("channel name");
      String *channel_description = String_fromCString("channel description");
      String *system_service_name = String_fromCString("notification");
      NotificationChannel *channel =
          new NotificationChannel(*channel_id, *channel_name, IMPORTANCE_HIGH);
      channel->setDescription(*channel_description);
   
      Object& notification_manager_as_object =
          context->getSystemService(*system_service_name);
      NotificationManager *notification_manager =
          new NotificationManager(notification_manager_as_object.GetImpl());
   
      notification_manager->createNotificationChannel(*channel);
   
      CharSequence::destroy(channel_name);
      String::destroy(channel_description);
      String::destroy(system_service_name);
      NotificationChannel::destroy(channel);
      Object::destroy(&notification_manager_as_object);
      NotificationManager::destroy(notification_manager);
   }
   

4. 更新您之前创建的 ShowNativeNotification() 函数以调用 CreateNotificationChannel()。将以下代码添加到 ShowNativeNotification() 的末尾

   C

   void ShowNativeNotification(JNIEnv *env, jobject main_activity, int icon_id) {
    // ...
   
    // Create a Context object by wrapping an existing JNI reference.
    Context *context = Context_wrapJniReference(main_activity);
   
    // Create a String object.
    String *channel_id = String_fromCString("new_messages");
   
    // Create a notification channel.
    CreateNotificationChannel(context, channel_id);
   
    // Create a notification with a given title, content, and icon.
    Notification *notification =
        CreateNotification(context, channel_id, "My Native Notification",
                           "Hello!", icon_id);
   
    // Create a notification manager and use it to show the notification.
    NotificationManagerCompat *notification_manager =
        NotificationManagerCompat_from(context);
    NotificationManagerCompat_notify(notification_manager, NOTIFICATION_ID,
                                     notification);
   
    // Destroy all objects.
    Context_destroy(context);
    String_destroy(channel_id);
    Notification_destroy(notification);
    NotificationManagerCompat_destroy(notification_manager);
   }
   

   C++

   void ShowNativeNotification(JNIEnv *env, jobject main_activity, int icon_id) {
      // Get the JavaVM from the JNIEnv.
      JavaVM *java_vm;
      env->GetJavaVM(&java_vm);
   
      // Initialize the GNI runtime. This function needs to be called before any
      // call to the generated code.
      GniCore::Init(java_vm, main_activity);
   
      // Create a Context object by wrapping an existing JNI reference.
      Context *context = new Context(main_activity);
   
      // Create a String object.
      String *channel_id = String_fromCString("new_messages");
   
      // Create a notification channel.
      CreateNotificationChannel(context, channel_id);
   
      // Create a notification with a given title, content, and icon.
      Notification& notification =
          CreateNotification(context, channel_id, "My Native Notification",
                             "Hello!", icon_id);
   
      // Create a notification manager and use it to show the notification.
      NotificationManagerCompat& notification_manager =
          NotificationManagerCompat::from(*context);
      notification_manager.notify(NOTIFICATION_ID, notification);
   
      // Destroy all objects.
      Context::destroy(context);
      String::destroy(channel_id);
      Notification::destroy(&notification);
      NotificationManagerCompat::destroy(&notification_manager);
   }   

5. 定义了逻辑后，请在项目的适当位置调用 ShowNativeNotification() 来触发通知。

运行应用

编译并运行调用 ShowNativeNotification() 的代码。一个简单的通知应该会出现在测试设备屏幕的顶部。

从 JAR 生成包装器

在之前的示例中，您手动在包装器配置文件中定义了需要原生代码的 Java 类和方法。对于需要访问 API 大部分内容的场景，向包装器工具提供一个或多个库 JAR 文件更有效。然后，包装器会为其在 JAR 中找到的所有公共符号生成包装器。

以下示例通过提供库 JAR 来包装整个 Notifications API。

获取所需的 JAR 文件

Notification API 是 androidx.core 包的一部分，可从 Google Maven 存储库获取。下载库 aar 文件并将其解压缩到您选择的目录。找到 classes.jar 文件。

classes.jar 文件包含许多超出我们所需通知库的类。如果您仅向库包装器提供 classes.jar，则该工具会为 JAR 中的每个类生成原生代码，这对于我们的项目来说效率低下且没有必要。为了解决这个问题，请向包装器配置提供一个过滤器文件，以将代码生成限制在 JAR 的通知类。

定义允许过滤器

过滤器文件 是您提供给库包装器配置的纯文本文件。它们允许您定义要包含（或排除）在提供给库包装器的 JAR 文件中的类。

在您的项目中，创建一个名为 allowed-symbols.txt 的文件，并将以下行粘贴到其中

androidx.core.app.NotificationCompat*

当用作允许过滤器时，前面的代码指定仅包装名称以 androidx.core.app.NotificationCompat 开头的符号。

运行库包装器

打开终端到 JAR 目录并运行以下命令

java -jar lw.jar \
 -i classes.jar \
 -o "./generated-jar" \
 -c "./config.json" \
 -fa allowed-symbols.txt \
 --skip_deprecated_symbols

前面的示例命令将您过滤后的类的包装器代码生成到 generated-jar/ 目录。

支持

如果您在库包装器中发现问题，请告知我们。

浏览错误	提交错误
工程	bug_report
文档	bug_report

---