From a0701f821359fb3a4e216eba752ecb3b97582dfb Mon Sep 17 00:00:00 2001 From: hellohyh001 Date: Mon, 4 Dec 2023 03:25:45 +0000 Subject: [PATCH] add native-vibrator-guidelines Signed-off-by: hellohyh001 --- .../napi/native-sensor-guidelines.md | 156 ++++++++++++++++++ .../napi/native-vibrator-guidelines.md | 78 +++++++++ 2 files changed, 234 insertions(+) create mode 100644 zh-cn/application-dev/napi/native-sensor-guidelines.md create mode 100644 zh-cn/application-dev/napi/native-vibrator-guidelines.md diff --git a/zh-cn/application-dev/napi/native-sensor-guidelines.md b/zh-cn/application-dev/napi/native-sensor-guidelines.md new file mode 100644 index 00000000000..bf01e0d999a --- /dev/null +++ b/zh-cn/application-dev/napi/native-sensor-guidelines.md @@ -0,0 +1,156 @@ +# sensor开发指导 + +## 场景介绍 + +sensor模块提供了获取传感器数据的能力，包括获取传感器属性列表，订阅传感器数据，以及取消订阅传感器数据。 + +## 接口说明 + +| 接口名 | 描述 | +| ------------------------------------------------------------ | ------------------------------------------------------ | +| OH_Sensor_GetInfos(Sensor_Info **infos, uint32_t *count) | 获取有关设备上所有传感器的信息 | +| OH_Sensor_Subscribe(const Sensor_SubscriptionId *id,
const Sensor_SubscriptionAttribute *attribute, const Sensor_Subscriber *subscriber) | 订阅传感器数据，系统将以指定的频率向用户报告传感器数据 | +| OH_Sensor_Unsubscribe(const Sensor_SubscriptionId *id,
const Sensor_Subscriber *subscriber) | 取消订阅传感器数据 | +| OH_Sensor_CreateInfos(uint32_t count) | 创建给定数量传感器信息实例数组 | +| OH_SensorInfo_GetName(Sensor_Info* sensor, char *sensorName, uint32_t *length) | 从传感器信息中获取传感器名称 | +| OH_SensorInfo_GetVendorName(Sensor_Info* sensor, char *vendorName, uint32_t *length) | 从传感器信息中获取传感器供应商名称 | +| OH_SensorInfo_GetType(Sensor_Info* sensor, Sensor_Type *sensorType) | 从传感器信息中获取传感器类型 | +| OH_SensorInfo_GetResolution(Sensor_Info* sensor, float *resolution); | 从传感器信息中获取传感器分辨率 | +| OH_SensorInfo_GetMinSamplingInterval(Sensor_Info* sensor, int64_t *minSamplingInterval); | 从传感器信息中获取传感器最小数据上报时间间隔 | +| OH_SensorInfo_GetMaxSamplingInterval(Sensor_Info* sensor, int64_t \*maxSamplingInterval) | 从传感器信息中获取传感器最大数据上报时间间隔 | +| OH_Sensor_DestroyInfos(Sensor_Info **sensors, uint32_t count) | 销毁传感器信息实例数组并回收内存 | +| OH_Sensor_CreateSubscriber(void) | 创建传感器订阅者实例 | +| OH_Sensor_DestroySubscriber(Sensor_Subscriber *subscriber) | 销毁传感器订阅者实例并回收内存 | +| OH_SensorSubscriber_SetCallback(Sensor_Subscriber* subscriber, const Sensor_EventCallback callback) | 设置传感器订阅者的回调函数 | +| OH_SensorSubscriber_GetCallback(Sensor_Subscriber* subscriber, Sensor_EventCallback *callback) | 获取用于报告传感器数据的回调函数 | +| OH_Sensor_CreateSubscriptionId(void) | 创建传感器订阅ID实例 | +| OH_Sensor_DestroySubscriptionId(Sensor_SubscriptionId *id) | 销毁传感器订阅ID实例并回收内存 | +| OH_SensorEvent_GetType(Sensor_Event* sensorEvent, Sensor_Type *sensorType) | 从传感器数据信息中获取传感器类型 | +| OH_SensorEvent_GetTimestamp(Sensor_Event* sensorEvent, int64_t *timestamp) | 从传感器上报事件中获取时间戳 | +| OH_SensorEvent_GetAccuracy(Sensor_Event* sensorEvent, Sensor_Accuracy *accuracy) | 从传感器上报事件中获取数据精度 | +| OH_SensorEvent_GetData(Sensor_Event* sensorEvent, float **data, uint32_t *length) | 从传感器上报事件中获取数据 | +| OH_SensorSubscriptionId_GetType(Sensor_SubscriptionId* id, Sensor_Type *sensorType) | 从传感器订阅ID中获取传感器类型 | +| OH_SensorSubscriptionId_SetType(Sensor_SubscriptionId* id, const Sensor_Type sensorType) | 设置传感器类型 | +| OH_Sensor_CreateSubscriptionAttribute(void) | 创建传感器订阅属性的实例 | +| OH_Sensor_DestroySubscriptionAttribute(Sensor_SubscriptionAttribute *attribute) | 销毁传感器订阅属性的实例并回收内存 | +| OH_SensorSubscriptionAttribute_SetSamplingInterval(Sensor_SubscriptionAttribute* attribute, const int64_t samplingInterval) | 给传感器属性实例中设置数据上报时间间隔 | +| OH_SensorSubscriptionAttribute_GetSamplingInterval(Sensor_SubscriptionAttribute* attribute, int64_t *samplingInterval) | 传感器属性实例中获取数据上报时间间隔 | + +## 开发步骤 + +**添加权限** + +检查是否已经配置相应权限，具体配置方式请参考[权限申请声明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/accesstoken-guidelines.md)。 + +| 传感器 | 权限名 | 敏感级别 | 权限描述 | +| -------------------------------------------------- | -------------------------------- | ------------ | ------------------------------------------------------------ | +| 加速度传感器，加速度未校准传感器，线性加速度传感器 | ohos.permission.ACCELEROMETER | system_grant | 允许应用读取加速度传感器的数据，包括：加速度传感器、加速度未校准传感器、线性加速度传感器。 | +| 陀螺仪传感器，陀螺仪未校准传感器 | ohos.permission.GYROSCOPE | system_grant | 允许应用读取陀螺仪传感器的数据，包括：陀螺仪传感器、陀螺仪未校准传感器。 | +| 计步器 | ohos.permission.ACTIVITY_MOTION | user_grant | 该权限允许应用读取用户当前的运动状态。例如：判断用户是否处于运动中、记录用户行走步数。 | +| 心率计 | ohos.permission.READ_HEALTH_DATA | user_grant | 该权限允许应用读取用户的健康数据，如：心率数据等。 | + +**添加动态链接库** + +CMakeLists.txt中添加以下lib。 + +``` +libohsensor.so +``` + +头文件 + +``` +#include "sensors/oh_sensor.h" +#include "sensors/oh_sensor_type.h" +``` + +获取有关设备上所有传感器的信息 + +``` +uint32_t count = 0; +if (OH_Sensor_GetInfos(nullptr, &count) != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, TAG, "OH_Sensor_GetInfos count failed"); + return nullptr; +} +// 创建具有给定数量的实例数组，返回指向实例数组的双指针 +Sensor_Info **sensors = OH_Sensor_CreateInfos(count); +if (OH_Sensor_GetInfos(sensors, &count) != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, TAG, "OH_Sensor_GetInfos failed"); + return nullptr; +} +...... +// 销毁实例数组并回收内存 +OH_Sensor_DestroyInfos(sensors, count); +``` + +定义回调函数 + +``` +void SensorCallback(Sensor_Event *event) +{ + Sensor_Event *sensorEvent = event; + // 从传感器数据信息中获取传感器类型 + if (OH_SensorEvent_GetType(event, &sensorData.sensorType) != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, TAG, "OH_SensorEvent_GetType failed"); + return; + } + // 从传感器上报事件中获取时间戳 + if (OH_SensorEvent_GetTimestamp(sensorEvent, &sensorData.timestamp) != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, TAG, "OH_SensorEvent_GetTimestamp failed"); + return; + } + // 从传感器上报事件中获取数据精度 + if (OH_SensorEvent_GetAccuracy(sensorEvent, &sensorData.sensorAccuracy) != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, TAG, "OH_SensorEvent_GetAccuracy failed"); + return; + } + // 从传感器上报事件中获取数据 + if (OH_SensorEvent_GetData(sensorEvent, &sensorData.data, &sensorData.length) != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, TAG, "OH_SensorEvent_GetData failed"); + return; + } +} +``` + +订阅传感器数据，系统将以指定的频率向用户报告传感器数据 + +``` +// 创建传感器订阅id的实例 +Sensor_SubscriptionId *id = OH_Sensor_CreateSubscriptionId(); +// 设置传感器类型 +OH_SensorSubscriptionId_SetType(id, SENSOR_TYPE_ACCELEROMETER); +// 创建传感器订阅属性的实例 +Sensor_SubscriptionAttribute *attr = OH_Sensor_CreateSubscriptionAttribute(); +// 设置传感器数据报告间隔 +OH_SensorSubscriptionAttribute_SetSamplingInterval(attr, 200000000); +// 创建一个传感器用户实例 +Sensor_Subscriber *user = OH_Sensor_CreateSubscriber(); +// 设置一个回调函数来报告传感器数据 +OH_SensorSubscriber_SetCallback(user, SensorCallback); +if (OH_Sensor_Subscribe(id, attr, user) != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, TAG, "OH_Sensor_Subscribe failed"); + return nullptr; +} +``` + +取消订阅传感器数据 + +``` +if (OH_Sensor_Unsubscribe(id, user) != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, TAG, "OH_Sensor_Unsubscribe failed"); + return nullptr; +} +if (id != nullptr) { + // 销毁Sensor_SubscriptionId实例并回收内存 + OH_Sensor_DestroySubscriptionId(id); +} +if (attr != nullptr) { + // 销毁Sensor_SubscriptionAttribute实例并回收内存 + OH_Sensor_DestroySubscriptionAttribute(attr); +} +if (user != nullptr) { + // 销毁Sensor_Subscriber实例并回收内存 + OH_Sensor_DestroySubscriber(user); +} +``` + diff --git a/zh-cn/application-dev/napi/native-vibrator-guidelines.md b/zh-cn/application-dev/napi/native-vibrator-guidelines.md new file mode 100644 index 00000000000..55259b49b10 --- /dev/null +++ b/zh-cn/application-dev/napi/native-vibrator-guidelines.md @@ -0,0 +1,78 @@ +# Vibrator开发指导 + +## 场景介绍 + +当设备需要设置不同的振动效果时，可以调用Vibrator模块，例如：设备的按键可以设置不同强度和不同时长的振动，闹钟和来电可以设置不同强度和时长的单次或周期振动。 + +## 接口说明 + +| 接口名 | 描述 | +| ------------------------------------------------------------ | ---------------------------------------- | +| OH_Vibrator_PlayVibration(int32_t duration, Vibrator_Attribute attribute) | 根据指定振动时间和振动属性触发马达振动。 | +| OH_Vibrator_PlayVibrationCustom(Vibrator_FileDescription fileDescription, Vibrator_Attribute vibrateAttribute) | 根据指定振动文件和振动属性触发马达振动。 | +| OH_Vibrator_Cancel() | 停止马达的振动。 | + +## 开发步骤 + +**添加权限** + +控制设备上的振动器，需要申请权限ohos.permission.VIBRATE。具体配置方式请参考[权限申请声明](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/accesstoken-guidelines.md)。 + +**添加动态链接库** + +CMakeLists.txt中添加以下lib。 + +``` +libohvibrator.z.so +``` + +**头文件** + +``` +#include "sensors/vibrator_type.h" +#include "sensors/vibrator.h" +``` + +按照指定持续时间触发马达振动： + +``` + Vibrator_Attribute vibrateAttribute; + // 可以缺省赋值，默认为0 + vibrateAttribute.vibratorId = 0; + // 可以缺省赋值，默认为VIBRATOR_USAGE_RING + vibrateAttribute.usage = VIBRATOR_USAGE_RING; + // 触发马达按照指定时间振动 + int32_t ret = OHOS::Sensors::OH_Vibrator_PlayVibration(1000, vibrateAttribute); +``` + +按照自定义振动配置文件触发马达振动： + +``` + // 需要开发者引入振动配置文件 + int32_t fd = open("test_event.json", O_RDONLY); + Vibrator_FileDescription fileDescription; + struct stat64 statbuf = { 0 }; + fileDescription.fd = fd; + fileDescription.offset = 0; + if (fstat64(fileDescription.fd, &statbuf) != 0) { + // 文件的状态信息获取失败 + } + fileDescription.length = statbuf.st_size; + + Vibrator_Attribute vibrateAttribute; + // 可以缺省赋值，默认为0 + vibrateAttribute.vibratorId = 0; + // 可以缺省赋值，默认为VIBRATOR_USAGE_RING + vibrateAttribute.usage = VIBRATOR_USAGE_RING; + // 触发马达自定义振动 + int32_t ret = OHOS::Sensors::OH_Vibrator_PlayVibrationCustom(fileDescription, vibrateAttribute); + +``` + +停止马达的振动： + +``` + + int32_t ret = OHOS::Sensors::OH_Vibrator_Cancel(); + +``` \ No newline at end of file -- Gitee