1# Associating Data with a Running Environment to Tide Their Lifecycle Using Node-API 2 3## Introduction 4 5Use Node-API to associate specific data with the currently running environment so that the data can be retrieved later when required. 6 7## Basic Concepts 8 9By associating the data with the currently running environment, the lifecycle of the C++ data struct is associated with that of the environment. This means the associated data remains valid as long as the running environment exists. 10 11## Available APIs 12 13The following table lists the APIs. 14| API| Description| 15| -------- | -------- | 16| napi_set_instance_data | Associates data with the currently running environment.| 17| napi_get_instance_data | Retrieves the data that was previously associated with the currently running environment.| 18 19## Example 20 21### napi_set_instance_data 22 23Associate data with the currently running environment. 24 25CPP code 26 27```cpp 28// Define a struct to store instance data. 29struct InstanceData { 30 int32_t value; 31}; 32 33// Callback to be invoked to clear the instance data when the object is released. 34void FinalizeCallback(napi_env env, void *finalize_data, void *finalize_hint) 35{ 36 if (finalize_data) { 37 InstanceData *data = reinterpret_cast<InstanceData *>(finalize_data); 38 // Release the memory and clear the address pointed by the pointer. 39 delete (data); 40 *(InstanceData **)finalize_data = nullptr; 41 } 42} 43 44static napi_value SetInstanceData(napi_env env, napi_callback_info info) 45{ 46 size_t argc = 1; 47 napi_value argv[1]; 48 napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); 49 int32_t instanceDataValue; 50 napi_get_value_int32(env, argv[0], &instanceDataValue); 51 InstanceData *instanceData = new InstanceData; 52 instanceData->value = instanceDataValue; 53 // Call napi_set_instance_data to associate the instance data with the Node-API environment and specify the FinalizeCallback function. 54 napi_status status = napi_set_instance_data(env, instanceData, FinalizeCallback, nullptr); 55 bool success = true; 56 napi_value result; 57 if (status == napi_ok) { 58 napi_get_boolean(env, success, &result); 59 } 60 return result; 61} 62``` 63 64API declaration 65 66```ts 67// index.d.ts 68export const setInstanceData: (data: number) => boolean; 69``` 70 71ArkTS code 72 73```ts 74let data = 5; 75let value = testNapi.setInstanceData(data); 76hilog.info(0x0000, 'testTag', 'Test NAPI napi_set_instance_data:%{public}s', value); 77``` 78 79### napi_get_instance_data 80 81Retrieve the data that was previously associated with the currently running environment. 82 83CPP code 84 85```cpp 86static napi_value GetInstanceData(napi_env env, napi_callback_info info) { 87 InstanceData *resData = nullptr; 88 // Call napi_get_instance_data to obtain the data. 89 napi_get_instance_data(env, (void **)&resData); 90 napi_value result; 91 napi_create_int32(env, resData->value, &result); 92 return result; 93} 94``` 95 96API declaration 97 98```ts 99// index.d.ts 100export const getInstanceData: () => number; 101``` 102 103ArkTS code 104 105```ts 106let data = 5; 107testNapi.setInstanceData(data); 108let value = testNapi.getInstanceData(); 109hilog.info(0x0000, 'testTag', 'Test NAPI napi_set_instance_data:%{public}d', value); 110``` 111 112### Configuring Compile Settings and Registering a Module 113 114- Configure compile settings. 115 116```text 117// CMakeLists.txt 118# the minimum version of CMake. 119cmake_minimum_required(VERSION 3.4.1) 120project(AboutEnvironmentalLifeCycle) 121 122set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR}) 123 124include_directories(${NATIVERENDER_ROOT_PATH} 125 ${NATIVERENDER_ROOT_PATH}/include) 126 127add_library(entry SHARED environmental_life_cycle.cpp) 128target_link_libraries(entry PUBLIC libace_napi.z.so) 129``` 130 131- Register the module. 132 133```cpp 134// environmental_life_cycle.cpp 135EXTERN_C_START 136static napi_value Init(napi_env env, napi_value exports) 137{ 138 napi_property_descriptor desc[] = { 139 {"setInstanceData", nullptr, SetInstanceData, nullptr, nullptr, nullptr, napi_default, nullptr}, 140 {"getInstanceData", nullptr, GetInstanceData, nullptr, nullptr, nullptr, napi_default, nullptr} 141 }; 142 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 143 return exports; 144} 145EXTERN_C_END 146``` 147