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