Native Bundle Development

When to Use

Use the native bundle APIs to obtain application information.

Available APIs

The following table lists the common APIs. For details, see Native_Bundle.

API	Description
OH_NativeBundle_GetCurrentApplicationInfo	Obtains the information about the current application.
OH_NativeBundle_GetAppId	Obtains the appId information about the application.
OH_NativeBundle_GetAppIdentifier	Obtains the appIdentifier information about the application.
OH_NativeBundle_GetMainElementName	Obtains the entry information of the application.
OH_NativeBundle_GetCompatibleDeviceType	Obtains the compatible device type of the application.
OH_NativeBundle_IsDebugMode	Queries the debug mode of the application. This API is supported since API version 20.
OH_NativeBundle_GetModuleMetadata	Obtains the metadata information of the application. This API is supported since API version 20.
OH_NativeBundle_GetAbilityResourceInfo	Obtains a list of ability resource information that supports opening a specific file type. This API is supported since API version 21.

How to Develop

**1. Create a project.

**2. Add dependencies.

After the project is created, the cpp directory is created in the project directory. In the cpp directory, there are files such as types/libentry/index.d.ts, napi_init.cpp, and CMakeLists.txt.

1. Open the src/main/cpp/CMakeLists.txt file, and add libbundle_ndk.z.so to target_link_libraries.

   target_link_libraries(entry PUBLIC libace_napi.z.so libbundle_ndk.z.so)
   

2. Open the src/main/cpp/napi_init.cpp file, and add the header file.

   // Include the header file required for napi.
   #include "napi/native_api.h"
   // Include the header file required for native APIs.
   #include "bundle/ability_resource_info.h"
   #include "bundle/native_interface_bundle.h"
   // Include the standard library for the free() function.
   #include <cstdlib>
   

   napi_init.cpp

**3. Modify the source file.

1. When the src/main/cpp/napi_init.cpp file is opened, Init is called to initialize the API.

   EXTERN_C_START
   static napi_value Init(napi_env env, napi_value exports)
   {
       napi_property_descriptor desc[] = {
           { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr },
           // Add the getCurrentApplicationInfo method.
           { "getCurrentApplicationInfo", nullptr, GetCurrentApplicationInfo, nullptr,
               nullptr, nullptr, napi_default, nullptr},
           // Add the getAppId method.
           { "getAppId", nullptr, GetAppId, nullptr, nullptr, nullptr, napi_default, nullptr},
           // Add the getAppIdentifier method.
           { "getAppIdentifier", nullptr, GetAppIdentifier, nullptr, nullptr, nullptr, napi_default, nullptr},
           // Add the getMainElementName method.
           { "getMainElementName", nullptr, GetMainElementName, nullptr, nullptr, nullptr, napi_default, nullptr},
           // Add the getCompatibleDeviceType method.
           { "getCompatibleDeviceType", nullptr, GetCompatibleDeviceType, nullptr,
               nullptr, nullptr, napi_default, nullptr},
           // Add the isDebugMode method.
           { "isDebugMode", nullptr, IsDebugMode, nullptr, nullptr, nullptr, napi_default, nullptr},
           // Add the getModuleMetadata method.
           { "getModuleMetadata", nullptr, GetModuleMetadata, nullptr, nullptr, nullptr, napi_default, nullptr},
           // Add the getAbilityResourceInfo method.
           { "getAbilityResourceInfo", nullptr, GetAbilityResourceInfo, nullptr, nullptr, nullptr, napi_default, nullptr}
       };
       napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
       return exports;
   }
   EXTERN_C_END
   

   napi_init.cpp

2. Obtain the native bundle information object from the src/main/cpp/napi_init.cpp file and convert it to a JavaScript bundle information object. In this way, you can obtain the application information on the JavaScript side.

   static napi_value GetCurrentApplicationInfo(napi_env env, napi_callback_info info)
   {
       // Call the native API to obtain the application information.
       OH_NativeBundle_ApplicationInfo nativeApplicationInfo = OH_NativeBundle_GetCurrentApplicationInfo();
       napi_value result = nullptr;
       napi_create_object(env, &result);
       // Convert the bundle name obtained by calling the native API to the bundleName property in the JavaScript object.
       napi_value bundleName;
       napi_create_string_utf8(env, nativeApplicationInfo.bundleName, NAPI_AUTO_LENGTH, &bundleName);
       napi_set_named_property(env, result, "bundleName", bundleName);
       // Convert the fingerprint information obtained by calling the native API to the fingerprint property in the JavaScript object.
       napi_value fingerprint;
       napi_create_string_utf8(env, nativeApplicationInfo.fingerprint, NAPI_AUTO_LENGTH, &fingerprint);
       napi_set_named_property(env, result, "fingerprint", fingerprint);
       // To prevent memory leak, manually release the memory.
       free(nativeApplicationInfo.bundleName);
       free(nativeApplicationInfo.fingerprint);
       return result;
   }
   
   static napi_value GetAppId(napi_env env, napi_callback_info info)
   {
       // Call the native API to obtain the appId.
       char* appId = OH_NativeBundle_GetAppId();
       // Convert the appId obtained by calling the native API to nAppId and return it.
       napi_value nAppId;
       napi_create_string_utf8(env, appId, NAPI_AUTO_LENGTH, &nAppId);
       // To prevent memory leak, manually release the memory.
       free(appId);
       return nAppId;
   }
   
   static napi_value GetAppIdentifier(napi_env env, napi_callback_info info)
   {
       // Call the native API to obtain the appIdentifier.
       char* appIdentifier = OH_NativeBundle_GetAppIdentifier();
       // Convert the appIdentifier obtained by calling the native API to nAppIdentifier and return it.
       napi_value nAppIdentifier;
       napi_create_string_utf8(env, appIdentifier, NAPI_AUTO_LENGTH, &nAppIdentifier);
       // To prevent memory leak, manually release the memory.
       free(appIdentifier);
       return nAppIdentifier;
   }
   
   static napi_value GetMainElementName(napi_env env, napi_callback_info info)
   {
       // Call the native API to obtain the application entry information.
       OH_NativeBundle_ElementName elementName = OH_NativeBundle_GetMainElementName();
       napi_value result = nullptr;
       napi_create_object(env, &result);
       // Convert the bundle name obtained by calling the native API to the bundleName property in the JavaScript object.
       napi_value bundleName;
       napi_create_string_utf8(env, elementName.bundleName, NAPI_AUTO_LENGTH, &bundleName);
       napi_set_named_property(env, result, "bundleName", bundleName);
       // Convert the module name obtained by calling the native API to the moduleName property in the JavaScript object.
       napi_value moduleName;
       napi_create_string_utf8(env, elementName.moduleName, NAPI_AUTO_LENGTH, &moduleName);
       napi_set_named_property(env, result, "moduleName", moduleName);
       // Convert the ability name obtained by calling the native API to the abilityName property in the JavaScript object.
       napi_value abilityName;
       napi_create_string_utf8(env, elementName.abilityName, NAPI_AUTO_LENGTH, &abilityName);
       napi_set_named_property(env, result, "abilityName", abilityName);
       // To prevent memory leak, manually release the memory.
       free(elementName.bundleName);
       free(elementName.moduleName);
       free(elementName.abilityName);
       return result;
   }
   
   static napi_value GetCompatibleDeviceType(napi_env env, napi_callback_info info)
   {
       // Call the native API to obtain the device type.
       char* deviceType = OH_NativeBundle_GetCompatibleDeviceType();
       // Convert the device type obtained by calling the native API to nDeviceType and return it.
       napi_value nDeviceType;
       napi_create_string_utf8(env, deviceType, NAPI_AUTO_LENGTH, &nDeviceType);
       // To prevent memory leak, manually release the memory.
       free(deviceType);
       return nDeviceType;
   }
   
   static napi_value IsDebugMode(napi_env env, napi_callback_info info)
   {
       bool isDebug = false;
       // Call the native API to obtain the DebugMode information of the application. This API is supported since API version 20.
       bool isSuccess = OH_NativeBundle_IsDebugMode(&isDebug);
       // Throw an exception if the native API call fails
       if (isSuccess == false) {
           napi_throw_error(env, nullptr, "call failed");
           return nullptr;
       }
       // Convert the debug information obtained by calling the native API to debug and return it.
       napi_value debug;
       napi_get_boolean(env, isDebug, &debug);
       return debug;
   }
   
   static napi_value GetModuleMetadata(napi_env env, napi_callback_info info)
   {
       size_t moduleCount = 0;
       // Call the native API to obtain the metadata of the application. This API is supported since API version 20.
       OH_NativeBundle_ModuleMetadata* modules = OH_NativeBundle_GetModuleMetadata(&moduleCount);
       if (modules == nullptr || moduleCount == 0) {
           napi_throw_error(env, nullptr, "no metadata found");
           return nullptr;
       }
       napi_value result;
       napi_create_array(env, &result);
       for (size_t i = 0; i < moduleCount; i++) {
           napi_value moduleObj;
           napi_create_object(env, &moduleObj);
           // Convert the module name obtained by calling the native API to the moduleName property in the JavaScript object.
           napi_value moduleName;
           napi_create_string_utf8(env, modules[i].moduleName, NAPI_AUTO_LENGTH, &moduleName);
           napi_set_named_property(env, moduleObj, "moduleName", moduleName);
           napi_value metadataArray;
           napi_create_array(env, &metadataArray);
           for (size_t j = 0; j < modules[i].metadataArraySize; j++) {
               napi_value metadataObj;
               napi_create_object(env, &metadataObj);
               napi_value name;
               napi_value value;
               napi_value resource;
               napi_create_string_utf8(env, modules[i].metadataArray[j].name, NAPI_AUTO_LENGTH, &name);
               napi_create_string_utf8(env, modules[i].metadataArray[j].value, NAPI_AUTO_LENGTH, &value);
               napi_create_string_utf8(env, modules[i].metadataArray[j].resource, NAPI_AUTO_LENGTH, &resource);
               // Convert the metadata name obtained by calling the native API to the name property in the JavaScript object.
               napi_set_named_property(env, metadataObj, "name", name);
               // Convert the metadata value obtained by calling the native API to the value property in the JavaScript object.
               napi_set_named_property(env, metadataObj, "value", value);
               // Convert the metadata resource obtained by calling the native API to the resource property in the JavaScript object.
               napi_set_named_property(env, metadataObj, "resource", resource);
               napi_set_element(env, metadataArray, j, metadataObj);
           }
           napi_set_named_property(env, moduleObj, "metadata", metadataArray);
           napi_set_element(env, result, i, moduleObj);
       }
       // To prevent memory leak, manually release the memory.
       for (size_t i = 0; i < moduleCount; i++) {
           free(modules[i].moduleName);
           for (size_t j = 0; j < modules[i].metadataArraySize; j++) {
               free(modules[i].metadataArray[j].name);
               free(modules[i].metadataArray[j].value);
               free(modules[i].metadataArray[j].resource);
           }
           free(modules[i].metadataArray);
       }
       free(modules);
       return result;
   }
   

   napi_init.cpp

   static void AddDefaultApp(napi_env env,
       napi_value &infoObj,
       OH_NativeBundle_AbilityResourceInfo* temp)
   {
       bool isDefaultApp = true;
       // This API is supported since API version 21.
       OH_NativeBundle_CheckDefaultApp(temp, &isDefaultApp);
       napi_value defaultAppValue;
       napi_get_boolean(env, isDefaultApp, &defaultAppValue);
       napi_set_named_property(env, infoObj, "isDefaultApp", defaultAppValue);
   }
   
   static void AddAppIndex(napi_env env,
       napi_value &infoObj,
       OH_NativeBundle_AbilityResourceInfo* temp)
   {
       int appIndex = -1;
       // This API is supported since API version 21.
       OH_NativeBundle_GetAppIndex(temp, &appIndex);
       napi_value appIndexValue;
       napi_create_int32(env, appIndex, &appIndexValue);
       napi_set_named_property(env, infoObj, "appIndex", appIndexValue);
   }
   
   static void AddLabel(napi_env env,
       napi_value &infoObj,
       OH_NativeBundle_AbilityResourceInfo* temp)
   {
       char *label = nullptr;
       // This API is supported since API version 21.
       OH_NativeBundle_GetLabel(temp, &label);
       napi_value labelValue;
       if (label) {
           napi_create_string_utf8(env, label, NAPI_AUTO_LENGTH, &labelValue);
           free(label);
       } else {
           napi_get_null(env, &labelValue);
       }
       napi_set_named_property(env, infoObj, "label", labelValue);
   }
   
   static void AddBundleName(napi_env env,
       napi_value &infoObj,
       OH_NativeBundle_AbilityResourceInfo* temp)
   {
       char *bundleName = nullptr;
       // This API is supported since API version 21.
       OH_NativeBundle_GetBundleName(temp, &bundleName);
       napi_value bundleNameValue;
       if (bundleName) {
           napi_create_string_utf8(env, bundleName, NAPI_AUTO_LENGTH, &bundleNameValue);
           free(bundleName);
       } else {
           napi_get_null(env, &bundleNameValue);
       }
       napi_set_named_property(env, infoObj, "bundleName", bundleNameValue);
   }
   
   static void AddModuleName(napi_env env,
       napi_value &infoObj,
       OH_NativeBundle_AbilityResourceInfo* temp)
   {
       char *moduleName = nullptr;
       // This API is supported since API version 21.
       OH_NativeBundle_GetModuleName(temp, &moduleName);
       napi_value moduleNameValue;
       if (moduleName) {
           napi_create_string_utf8(env, moduleName, NAPI_AUTO_LENGTH, &moduleNameValue);
           free(moduleName);
       } else {
           napi_get_null(env, &moduleNameValue);
       }
       napi_set_named_property(env, infoObj, "moduleName", moduleNameValue);
   }
   
   static void AddAbilityName(napi_env env,
       napi_value &infoObj,
       OH_NativeBundle_AbilityResourceInfo* temp)
   {
       char *abilityName = nullptr;
       // This API is supported since API version 21.
       OH_NativeBundle_GetAbilityName(temp, &abilityName);
       napi_value abilityNameValue;
       if (abilityName) {
           napi_create_string_utf8(env, abilityName, NAPI_AUTO_LENGTH, &abilityNameValue);
           free(abilityName);
       } else {
           napi_get_null(env, &abilityNameValue);
       }
       napi_set_named_property(env, infoObj, "abilityName", abilityNameValue);
   }
   
   static void GetDrawableDescriptor(
       OH_NativeBundle_AbilityResourceInfo* temp)
   {
       ArkUI_DrawableDescriptor *rawDrawable = nullptr;
       // This API is supported since API version 21.
       OH_NativeBundle_GetDrawableDescriptor(temp, &rawDrawable);
       if (rawDrawable) {
           // Use the ArkUI_DrawableDescriptor object to draw an icon.
       }
   }
   
   static void AssemblyAbilityResourceInfo(napi_env env,
       napi_value &infoObj,
       OH_NativeBundle_AbilityResourceInfo* temp)
   {
       // 1. Add the default app.
       AddDefaultApp(env, infoObj, temp);
       // 2. Add an app index.
       AddAppIndex(env, infoObj, temp);
       // 3. Add a label.
       AddLabel(env, infoObj, temp);
       // 4. Add a bundle name.
       AddBundleName(env, infoObj, temp);
       // 5. Add a module name.
       AddModuleName(env, infoObj, temp);
       // 6. Add an ability name.
       AddAbilityName(env, infoObj, temp);
       // 7. Obtain the ArkUI_DrawableDescriptor object.
       GetDrawableDescriptor(temp);
   }
   
   static napi_value GetAbilityResourceInfo(napi_env env, napi_callback_info info)
   {
       size_t argc = 1;
       napi_value args[1];
       napi_status status;
       // Obtain the parameters passed in.
       status = napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
       if (status != napi_ok || argc < 1) {
           napi_throw_error(env, nullptr, "Invalid arguments. Expected fileType string.");
           return nullptr;
       }
       // Check whether the parameter is a string.
       napi_valuetype valuetype;
       status = napi_typeof(env, args[0], &valuetype);
       if (status != napi_ok || valuetype != napi_string) {
           napi_throw_error(env, nullptr, "Argument must be a string");
           return nullptr;
       }
       // Obtain the string.
       char fileType[256] = {0}; // Assume that the file type does not exceed 255 characters.
       size_t strLen;
       status = napi_get_value_string_utf8(env, args[0], fileType, sizeof(fileType) - 1, &strLen);
       if (status != napi_ok) {
           napi_throw_error(env, nullptr, "Failed to get fileType string");
           return nullptr;
       }
       size_t infosCount = 0;
       OH_NativeBundle_AbilityResourceInfo *infos = nullptr;
       // Call the native API to obtain the component resource information using the passed-in fileType. This API is supported since API version 21.
       BundleManager_ErrorCode ret = OH_NativeBundle_GetAbilityResourceInfo(fileType, &infos, &infosCount);
       if (ret == BUNDLE_MANAGER_ERROR_CODE_PERMISSION_DENIED) {
           napi_throw_error(env, nullptr, "BUNDLE_MANAGER_ERROR_CODE_PERMISSION_DENIED");
           return nullptr;
       }
       if (infos == nullptr || infosCount == 0) {
           napi_throw_error(env, nullptr, "no metadata found");
           return nullptr;
       }
       napi_value result;
       napi_create_array(env, &result);
       for (size_t i = 0; i < infosCount; i++) {
           auto temp = (OH_NativeBundle_AbilityResourceInfo *)((char *)infos + OH_NativeBundle_GetSize() * i);
           napi_value infoObj;
           napi_create_object(env, &infoObj);
           AssemblyAbilityResourceInfo(env, infoObj, temp);
           napi_set_element(env, result, i, infoObj);
       }
       // Release the memory. This API is supported since API version 21.
       OH_AbilityResourceInfo_Destroy(infos, infosCount);
       return result;
   }
   

   napi_init.cpp

**4. Expose APIs.

1. Declare the exposed APIs in the src/main/cpp/types/libentry/Index.d.ts file.

   export const add: (a: number, b: number) => number;
   export const getCurrentApplicationInfo: () => object;   // Add the exposed API getCurrentApplicationInfo.
   export const getAppId: () => string;                    // Add the exposed API getAppId.
   export const getAppIdentifier: () => string;            // Add the exposed API getAppIdentifier.
   export const getMainElementName: () => object;          // Add the exposed API getMainElementName.
   export const getCompatibleDeviceType: () => string;     // Add the exposed API getCompatibleDeviceType.
   export const isDebugMode: () => string;                 // Add the exposed API isDebugMode.
   export const getModuleMetadata: () => object;           // Add the exposed API getModuleMetadata.
   export const getAbilityResourceInfo: (fileType: string) => object;      // Add the exposed API getAbilityResourceInfo.
   

   Index.d.ts

**5. Call APIs on the JavaScript side.

1. Open the src/main/ets/pages/index.ets file, and import libentry.so.

2. Call the native APIs to print the obtained information. An example is as follows:

   import { hilog } from '@kit.PerformanceAnalysisKit';
   import testNapi from 'libentry.so';
   
   const DOMAIN = 0x0000;
   
   @Entry
   @Component
   struct Index {
     @State message: string = 'Hello World';
   
     build() {
       Row() {
         Column() {
           Text(this.message)
             .fontSize($r('app.float.page_text_font_size'))
             .fontWeight(FontWeight.Bold)
             .onClick(() => {
               this.message = 'Welcome';
               hilog.info(DOMAIN, 'testTag', 'Test NAPI 2 + 3 = %{public}d', testNapi.add(2, 3));
               let appInfo = testNapi.getCurrentApplicationInfo();
               console.info("bundleNative getCurrentApplicationInfo success, data is " + JSON.stringify(appInfo));
               let appId = testNapi.getAppId();
               console.info("bundleNative getAppId success, appId is " + appId);
               let appIdentifier = testNapi.getAppIdentifier();
               console.info("bundleNative getAppIdentifier success, appIdentifier is " + appIdentifier);
               let mainElement = testNapi.getMainElementName();
               console.info("bundleNative getMainElementName success, data is " + JSON.stringify(mainElement));
               let deviceType = testNapi.getCompatibleDeviceType();
               console.info("bundleNative getCompatibleDeviceType success, deviceType is " + deviceType);
               let isDebugMode = testNapi.isDebugMode();
               console.info("bundleNative isDebugMode success, isDebugMode is " + isDebugMode);
               let moduleMetadata = testNapi.getModuleMetadata();
               console.info("bundleNative getModuleMetadata success, data is " + JSON.stringify(moduleMetadata));
               let fileType: string = '.png';
               let abilityResourceInfo = testNapi.getAbilityResourceInfo(fileType);
               console.info("bundleNative getAbilityResourceInfo success, data is " + JSON.stringify(abilityResourceInfo));
             })
         }
         .width('100%')
       }
       .height('100%')
     }
   }
   

   Index.ets

For details about the APIs, see Native_Bundle.