1 /* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup Vibrator 18 * @{ 19 * 20 * @brief Provides a driver for upper-layer vibrator services. 21 * 22 * After obtaining a driver object or agent, a vibrator service starts or stops the vibrator 23 * using the functions provided by the driver object or agent. 24 * 25 * @since 2.2 26 */ 27 28 /** 29 * @file vibrator_if.h 30 * 31 * @brief Declares common APIs in the vibrator module. The APIs can be used to control 32 * the vibrator to perform a one-shot or periodic vibration. 33 * 34 * @since 2.2 35 * @version 1.0 36 */ 37 38 #ifndef VIBRATOR_IF_H 39 #define VIBRATOR_IF_H 40 41 #include <stdint.h> 42 #include "vibrator_type.h" 43 44 #ifdef __cplusplus 45 #if __cplusplus 46 extern "C" { 47 #endif 48 #endif /* __cplusplus */ 49 50 struct VibratorInterface { 51 /** 52 * @brief Controls the vibrator to perform a one-shot vibration that lasts for a given duration. 53 * 54 * One-shot vibration is mutually exclusive with periodic vibration. Before using one-shot vibration, 55 * exit periodic vibration. 56 * 57 * @param duration Indicates the duration that the one-shot vibration lasts, in milliseconds. 58 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 59 * 60 * @since 2.2 61 * @version 1.0 62 */ 63 int32_t (*StartOnce)(uint32_t duration); 64 /** 65 * @brief Controls the vibrator to perform a periodic vibration with the preset effect. 66 * 67 * One-shot vibration is mutually exclusive with periodic vibration. Before using periodic vibration, 68 * exit one-shot vibration. 69 * 70 * @param effectType Indicates the pointer to the preset effect type. It is recommended that the 71 * maximum length be 64 bytes. 72 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 73 * 74 * @since 2.2 75 * @version 1.0 76 */ 77 int32_t (*Start)(const char *effectType); 78 /** 79 * @brief Stops the vibration. 80 * 81 * Before the vibrator starts, it must stop vibrating in any mode. This function can be used during 82 * and after the vibrating process. 83 * 84 * @param mode Indicates the vibration mode, which can be one-shot or periodic. For details, 85 * see {@link VibratorMode}. 86 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 87 * 88 * @since 2.2 89 * @version 1.0 90 */ 91 int32_t (*Stop)(enum VibratorMode mode); 92 }; 93 94 /** 95 * @brief Creates a <b>VibratorInterface</b> instance. 96 * 97 * The obtained <b>VibratorInterface</b> instance can be used to control the vibrator to vibrate as configured. 98 * 99 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 100 * 101 * @since 2.2 102 * @version 1.0 103 */ 104 const struct VibratorInterface *NewVibratorInterfaceInstance(void); 105 106 /** 107 * @brief Releases this <b>VibratorInterface</b> instance to free up related resources. 108 * 109 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 110 * 111 * @since 2.2 112 * @version 1.0 113 */ 114 int32_t FreeVibratorInterfaceInstance(void); 115 116 #ifdef __cplusplus 117 #if __cplusplus 118 } 119 #endif 120 #endif /* __cplusplus */ 121 122 #endif /* VIBRATOR_IF_H */ 123 /** @} */ 124