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