From 718e894ab6489081540cb001834d8fc63223c19b Mon Sep 17 00:00:00 2001 From: kevin Date: Fri, 2 Jul 2021 16:15:02 +0800 Subject: [PATCH] add vibrator api translation doc Signed-off-by: kevin Change-Id: I15b9f034d2b91dc0add0bc85ffe70adb42911007 --- doc/vibrator_if.h | 116 ++++++++++++++++++++++++++++++++++++++++++++ doc/vibrator_type.h | 72 +++++++++++++++++++++++++++ 2 files changed, 188 insertions(+) create mode 100644 doc/vibrator_if.h create mode 100644 doc/vibrator_type.h diff --git a/doc/vibrator_if.h b/doc/vibrator_if.h new file mode 100644 index 0000000000..dc057ecb9f --- /dev/null +++ b/doc/vibrator_if.h @@ -0,0 +1,116 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup 马达 + * @{ + * + * @brief 马达设备驱动对马达服务提供通用的接口能力。 + * + * 马达设备驱动模块对上层马达服务提供的通用接口能力，服务获取驱动对象或者代理后，通过其提供的方法操作马达震动和马达停止。 + * + * @since 2.2 + */ + +/** + * @file vibrator_if.h + * + * @brief 马达模块对通用的接口声明，提供马达连续时间内的一次震动，马达按照预置效果震动能力。 + * + * @since 2.2 + * @version 1.0 + */ + +#ifndef VIBRATOR_IF_H +#define VIBRATOR_IF_H + +#include +#include "vibrator_type.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +struct VibratorInterface { + /** + * @brief 马达在给定的连续时间内的一次震动 + * + * 在使用马达一次震动时，需要先停止预置效果震动模式，马达一次震动模式与预置效果模式互斥。 + * + * @param duration 单次震动的持续时间，时间单位：毫秒。 + * @return 成功返回0，失败返回负值。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*StartOnce)(uint32_t duration); + /** + * @brief 马达按照预置效果震动，预置效果分为时间序列的效果和马达内置的效果。 + * + * 在使用马达预置效果震动时，需要先停止一次震动模式，马达一次震动模式与预置效果模式互斥。 + * + * @param effectType 预置效果字符串，按照马达预置的字符串对应的马达效果震动，建议效果字符串最大长度不超过64字节。 + * @return 成功返回0，失败返回负值。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*Start)(const char *effectType); + /** + * @brief 停止马达震动。 + * + * 马达在启动前需要停止任何模式的震动，支持震动过程中停止和震动结束后的停止。 + * + * @param mode 马达震动模式，模式分为一次震动模式和预置模式，详见 {@link VibratorMode}. + * @return 成功返回0，失败返回负值。 + * + * @since 2.2 + * @version 1.0 + */ + int32_t (*Stop)(enum VibratorMode mode); +}; + +/** + * @brief 创建马达设备接口实例，操作马达的启动和停止。 + * + * 使用马达接口实例获取马达相关信息，按照配置的连续时间执行马达震动，或者按照马达预置的时间序列或内置效果震动。 + * + * @return 创建实例成功返回0，失败返回负值。 + * + * @since 2.2 + * @version 1.0 + */ +const struct VibratorInterface *NewVibratorInterfaceInstance(void); + +/** + * @brief 释放马达接口实例，释放相应的资源. + * + * @return 释放实例成功返回0，失败返回负值。 + * + * @since 2.2 + * @version 1.0 + */ +int32_t FreeVibratorInterfaceInstance(void); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* VIBRATOR_IF_H */ +/** @} */ \ No newline at end of file diff --git a/doc/vibrator_type.h b/doc/vibrator_type.h new file mode 100644 index 0000000000..bbe870084f --- /dev/null +++ b/doc/vibrator_type.h @@ -0,0 +1,72 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup 马达 + * @{ + * + * @brief 马达设备驱动对马达服务提供通用的接口能力。 + * + * 马达设备驱动模块对上层马达服务提供的通用接口能力，服务获取驱动对象或者代理后，通过其提供的方法操作马达震动和马达停止。 + * + * @version 1.0 + */ + +/** + * @file vibrator_type.h + * + * @brief 定义马达数据结构，包括马达震动模式，马达效果类型。 + * + * @since 2.2 + * @version 1.0 + */ + +#ifndef VIBRATOR_TYPE_H +#define VIBRATOR_TYPE_H + +#include + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif /* __cplusplus */ + +/** + * @brief 定义马达的震动模式。 + * + * @since 2.2 + */ +enum VibratorMode { + VIBRATOR_MODE_ONCE = 0, /**< 马达一次持续时间内的震动 */ + VIBRATOR_MODE_PRESET = 1, /**< 马达预置效果的震动 */ + VIBRATOR_MODE_MAX, +}; + +/** + * @brief 定义马达默认的预置效果字符串. + * + * @since 2.2 + */ +# define HDF_VIBRATOR_EFFECT_DEFAULT "hdf.vibrator.default" + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif /* __cplusplus */ + +#endif /* VIBRATOR_TYPE_H */ +/** @} */ \ No newline at end of file -- Gitee