• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 使用JSVM-API接口进行ArrayBuffer相关开发
2<!--Kit: NDK Development-->
3<!--Subsystem: arkcompiler-->
4<!--Owner: @yuanxiaogou; @string_sz-->
5<!--Designer: @knightaoko-->
6<!--Tester: @test_lzz-->
7<!--Adviser: @fang-jinxu-->
8
9## 简介
10
11ArrayBuffer 是 JavaScript 中的一种数据类型，用于表示通用的、固定长度的原始二进制数据缓冲区。它提供了一种在 JavaScript 中有效地表示和操作原始二进制数据的方式。
12
13## 基本概念
14
15- **ArrayBuffer**：ArrayBuffer 对象用来表示一个通用的、固定长度的原始二进制数据缓冲区。不能直接操作 ArrayBuffer 的内容，而是需要通过包装成 TypedArray 对象或 DataView 对象来读写。ArrayBuffer 常用于处理固定长度的原始二进制数据，如文件、网络数据包等。
16- **生命周期和内存管理**：在使用 JSVM 处理 ArrayBuffer 时，需要特别注意对象的生命周期管理，确保及时释放内存。
17
18## 接口说明
19
20| 接口                         | 功能说明                                   |
21| ---------------------------- | ------------------------------------------ |
22| OH_JSVM_GetArraybufferInfo    | 检索 ArrayBuffer 的底层数据缓冲区及其长度。 |
23| OH_JSVM_IsArraybuffer        | 判断一个 JavaScript 对象是否为 ArrayBuffer 类型对象。        |
24| OH_JSVM_DetachArraybuffer    | 调用 ArrayBuffer 对象的 Detach 操作。            |
25| OH_JSVM_IsDetachedArraybuffer | 检查给定的 ArrayBuffer 是否已被分离(Detached)。        |
26| OH_JSVM_CreateArraybuffer      | 创建一个指定大小的 ArrayBuffer 对象。   |
27
28## 使用示例
29
30JSVM-API 接口开发流程参考[使用JSVM-API实现JS与C/C++语言交互开发流程](use-jsvm-process.md)，本文仅对接口对应 C++ 相关代码进行展示。
31
32### OH_JSVM_GetArraybufferInfo
33
34检索 ArrayBuffer 的底层数据缓冲区及其长度。
35
36cpp部分代码：
37
38```cpp
39// hello.cpp
40#include "napi/native_api.h"
41#include "ark_runtime/jsvm.h"
42#include <hilog/log.h>
43// OH_JSVM_GetArraybufferInfo的样例方法
44static JSVM_Value GetArraybufferInfo(JSVM_Env env, JSVM_CallbackInfo info)
45{
46    size_t argc = 1;
47    JSVM_Value args[1] = {nullptr};
48    // 解析传递的参数
49    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
50    // 检查参数是否为ArrayBuffer
51    bool isArrayBuffer = false;
52    OH_JSVM_IsArraybuffer(env, args[0], &isArrayBuffer);
53    if (!isArrayBuffer) {
54        OH_LOG_ERROR(LOG_APP, "JSVM GetArraybufferInfo isArrayBuffer:false");
55        return nullptr;
56    }
57    void *data;
58    size_t byteLength = 0;
59    // 获取ArrayBuffer的底层数据缓冲区和长度
60    JSVM_Status status = OH_JSVM_GetArraybufferInfo(env, args[0], &data, &byteLength);
61    if (status != JSVM_OK) {
62        OH_LOG_ERROR(LOG_APP, "JSVM GetArraybufferInfo: failed");
63    } else {
64        OH_LOG_INFO(LOG_APP, "JSVM GetArraybufferInfo: success");
65    }
66    return args[0];
67}
68// GetArraybufferInfo注册回调
69static JSVM_CallbackStruct param[] = {
70    {.data = nullptr, .callback = GetArraybufferInfo},
71};
72static JSVM_CallbackStruct *method = param;
73// GetArraybufferInfo方法别名，供JS调用
74static JSVM_PropertyDescriptor descriptor[] = {
75    {"getArraybufferInfo", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
76};
77// 样例测试js
78const char *srcCallNative = R"JS(
79getArraybufferInfo(new ArrayBuffer(10));
80)JS";
81```
82
83预期结果：
84```
85JSVM GetArraybufferInfo: success
86```
87
88<!-- @[oh_jsvm_get_arraybuffer_info](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArraybuffer/getarraybufferinfo/src/main/cpp/hello.cpp) -->
89
90### OH_JSVM_IsArraybuffer
91
92判断一个 JavaScript 对象是否为 ArrayBuffer 类型对象。
93
94cpp部分代码：
95
96```cpp
97// hello.cpp
98#include "napi/native_api.h"
99#include "ark_runtime/jsvm.h"
100#include <hilog/log.h>
101// OH_JSVM_IsArraybuffer的样例方法
102static JSVM_Value IsArrayBuffer(JSVM_Env env, JSVM_CallbackInfo info)
103{
104    size_t argc = 1;
105    JSVM_Value args[1] = {nullptr};
106    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
107    // 调用OH_JSVM_IsArraybuffer接口判断给定入参是否为ArrayBuffer数据
108    bool isArrayBuffer = false;
109    JSVM_Status status = OH_JSVM_IsArraybuffer(env, args[0], &isArrayBuffer);
110    if (status != JSVM_OK) {
111        OH_LOG_ERROR(LOG_APP, "JSVM IsArrayBuffer: failed");
112    } else {
113        OH_LOG_INFO(LOG_APP, "JSVM IsArrayBuffer: success");
114        OH_LOG_INFO(LOG_APP, "JSVM IsArrayBuffer: %{public}d", isArrayBuffer);
115    }
116    JSVM_Value boolean = nullptr;
117    OH_JSVM_GetBoolean(env, isArrayBuffer, &boolean);
118    return boolean;
119}
120// IsArrayBuffer注册回调
121static JSVM_CallbackStruct param[] = {
122    {.data = nullptr, .callback = IsArrayBuffer},
123};
124static JSVM_CallbackStruct *method = param;
125// IsArrayBuffer方法别名，供JS调用
126static JSVM_PropertyDescriptor descriptor[] = {
127    {"isArrayBuffer", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
128};
129// 样例测试js
130const char *srcCallNative = R"JS(
131isArrayBuffer(new ArrayBuffer(8));
132)JS";
133```
134
135预期结果：
136```
137JSVM IsArrayBuffer: success
138JSVM IsArrayBuffer: 1
139```
140
141<!-- @[oh_jsvm_is_arraybuffer](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArraybuffer/isarraybuffer/src/main/cpp/hello.cpp) -->
142
143### OH_JSVM_DetachArraybuffer
144
145调用 ArrayBuffer 对象的 Detach 操作。
146
147### OH_JSVM_IsDetachedArraybuffer
148
149检查给定的 ArrayBuffer 是否已被分离。
150
151cpp部分代码：
152
153```cpp
154// hello.cpp
155#include "napi/native_api.h"
156#include "ark_runtime/jsvm.h"
157#include <hilog/log.h>
158// OH_JSVM_DetachArraybuffer、OH_JSVM_IsDetachedArraybuffer的样例方法
159static JSVM_Value DetachArraybuffer(JSVM_Env env, JSVM_CallbackInfo info)
160{
161    size_t argc = 1;
162    JSVM_Value args[1] = {nullptr};
163    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
164    JSVM_Value arraybuffer = args[0];
165    JSVM_Status status = OH_JSVM_DetachArraybuffer(env, arraybuffer);
166    if (status != JSVM_OK) {
167        OH_LOG_ERROR(LOG_APP, "JSVM DetachArraybuffer: failed");
168    } else {
169        OH_LOG_INFO(LOG_APP, "JSVM DetachArraybuffer: success");
170    }
171    return arraybuffer;
172}
173static JSVM_Value IsDetachedArraybuffer(JSVM_Env env, JSVM_CallbackInfo info)
174{
175    size_t argc = 1;
176    JSVM_Value args[1] = {nullptr};
177    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
178    JSVM_Value arraybuffer = args[0];
179    OH_JSVM_DetachArraybuffer(env, arraybuffer);
180    bool result = false;
181    JSVM_Status status = OH_JSVM_IsDetachedArraybuffer(env, arraybuffer, &result);
182    if (status != JSVM_OK) {
183        OH_LOG_ERROR(LOG_APP, "JSVM IsDetachedArraybuffer: failed");
184    } else {
185        OH_LOG_INFO(LOG_APP, "JSVM IsDetachedArraybuffer: success");
186        OH_LOG_INFO(LOG_APP, "JSVM IsArrayBuffer: %{public}d", result);
187    }
188    JSVM_Value isDetached = nullptr;
189    OH_JSVM_GetBoolean(env, result, &isDetached);
190    return isDetached;
191}
192// DetachArraybuffer、IsDetachedArraybuffer注册回调
193static JSVM_CallbackStruct param[] = {
194    {.data = nullptr, .callback = DetachArraybuffer},
195    {.data = nullptr, .callback = IsDetachedArraybuffer},
196};
197static JSVM_CallbackStruct *method = param;
198// DetachArraybuffer、IsDetachedArraybuffer方法别名，TS侧调用
199static JSVM_PropertyDescriptor descriptor[] = {
200    {"detachArraybuffer", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
201    {"isDetachedArraybuffer", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
202};
203// 样例测试js
204const char *srcCallNative = R"JS(
205let arrayBuffer = new ArrayBuffer(10);
206detachArraybuffer(arrayBuffer);
207isDetachedArraybuffer(arrayBuffer);
208)JS";
209```
210
211预期结果：
212```
213JSVM DetachArraybuffer: success
214JSVM IsDetachedArraybuffer: success
215JSVM IsArrayBuffer: 1
216```
217
218<!-- @[oh_jsvm_is_detached_arraybuffer](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArraybuffer/isdetachedarraybuffer/src/main/cpp/hello.cpp) -->
219
220### OH_JSVM_CreateArraybuffer
221
222创建一个指定大小的 ArrayBuffer 对象。
223
224cpp部分代码：
225
226```cpp
227// hello.cpp
228#include "napi/native_api.h"
229#include "ark_runtime/jsvm.h"
230#include <hilog/log.h>
231// OH_JSVM_CreateArraybuffer的样例方法
232static JSVM_Value CreateArraybuffer(JSVM_Env env, JSVM_CallbackInfo info)
233{
234    size_t argc = 1;
235    JSVM_Value argv[1] = {nullptr};
236    JSVM_Value result = nullptr;
237    // 解析传递的参数
238    OH_JSVM_GetCbInfo(env, info, &argc, argv, nullptr, nullptr);
239    int32_t value = 0;
240    size_t length = 0;
241    JSVM_CALL(OH_JSVM_GetValueInt32(env, argv[0], &value));
242    length = size_t(value);
243    void *data;
244    // 创建一个新的ArrayBuffer
245    JSVM_Status status = OH_JSVM_CreateArraybuffer(env, length, &data, &result);
246    if (status != JSVM_OK) {
247        OH_LOG_ERROR(LOG_APP, "JSVM CreateArraybuffer: failed");
248        return nullptr;
249    } else {
250        OH_LOG_INFO(LOG_APP, "JSVM CreateArraybuffer: success");
251        OH_LOG_INFO(LOG_APP, "JSVM ArrayBuffer length: %{public}d", length);
252    }
253    // 返回创建好的ArrayBuffer
254    return result;
255}
256// CreateArraybuffer注册回调
257static JSVM_CallbackStruct param[] = {
258    {.data = nullptr, .callback = CreateArraybuffer},
259};
260static JSVM_CallbackStruct *method = param;
261// CreateArraybuffer方法别名，供TS侧调用
262static JSVM_PropertyDescriptor descriptor[] = {
263    {"createArraybuffer", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
264};
265// 样例测试js
266const char *srcCallNative = R"JS(
267createArraybuffer(8);
268)JS";
269```
270
271预期结果：
272```
273JSVM CreateArraybuffer: success
274JSVM ArrayBuffer length: 8
275```
276
277<!-- @[oh_jsvm_create_arraybuffer](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArraybuffer/createarraybuffer/src/main/cpp/hello.cpp) -->
278