1 /* 2 * Copyright (c) 2021-2024 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 functions for managing vibrators. 21 * @since 6 22 */ 23 24 /** 25 * @file vibrator_agent.h 26 * 27 * @brief Declares the functions for starting or stopping a vibrator. 28 * @since 6 29 */ 30 #ifndef VIBRATOR_AGENT_H 31 #include <stdint.h> 32 #include "vibrator_agent_type.h" 33 #define VIBRATOR_AGENT_H 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 namespace OHOS { 40 namespace Sensors { 41 /** 42 * @brief Indicates the mode of stopping a one-shot vibration effect. 43 * 44 * @since 6 45 */ 46 const char *VIBRATOR_STOP_MODE_TIME = "time"; 47 48 /** 49 * @brief Indicates the mode of stopping a preset vibration effect. 50 * 51 * @since 6 52 */ 53 const char *VIBRATOR_STOP_MODE_PRESET = "preset"; 54 55 /** 56 * @brief Controls this vibrator to perform a vibration with a preset vibration effect. 57 * 58 * @param effectId Indicates the preset vibration effect, which is described in {@link vibrator_agent_type.h}, for 59 * example:{@link VIBRATOR_TYPE_CLOCK_TIMER}: Describes the vibration effect of the vibrator when a user adjusts the 60 * timer. 61 * @return Returns <b>0</b> if the vibrator vibrates as expected; returns <b>-1</b> otherwise, for example, the preset 62 * vibration effect is not supported. 63 * 64 * @since 6 65 */ 66 int32_t StartVibrator(const char *effectId); 67 68 /** 69 * @brief Controls this vibrator to perform a one-shot vibration at a given duration. 70 * 71 * @param duration Indicates the duration that the one-shot vibration lasts, in milliseconds. 72 * @return Returns <b>0</b> if the vibrator vibrates as expected; returns <b>-1</b> otherwise, for example, the given 73 * duration for the one-shot vibration is invalid. 74 * 75 * @since 6 76 */ 77 int32_t StartVibratorOnce(int32_t duration); 78 79 /** 80 * @brief Query whether the device supports custom vibration. 81 * 82 * @return Returning true indicates support; otherwise, it indicates no support. 83 * 84 * @since 10 85 */ 86 bool IsSupportVibratorCustom(); 87 88 /** 89 * @brief Play a custom vibration sequence. 90 * 91 * @param fd Indicates the file handle for custom vibration sequence. 92 * @param offset Indicates the starting address (in bytes) of the custom vibration sequence. 93 * @param length Indicates the total length (in bytes) of the custom vibration sequence. 94 * @return Returning 0 indicates success; otherwise, it indicates failure. 95 * 96 * @since 10 97 */ 98 int32_t PlayVibratorCustom(int32_t fd, int64_t offset, int64_t length); 99 100 /** 101 * @brief Sets the number of cycles for vibration. 102 * @param count Indicates the number of cycles for vibration. 103 * @since 9 104 */ 105 bool SetLoopCount(int32_t count); 106 107 /** 108 * @brief Stop the motor vibration according to the input mode. 109 * 110 * @param mode Indicates the mode of the vibration to stop. The values can be <b>time</b> and <b>preset</b>, 111 * respectively representing a one-shot vibration mode and a preset vibration mode. 112 * @return Returns <b>0</b> if the vibration is stopped as expected; returns <b>-1</b> otherwise. 113 * @since 6 114 */ 115 int32_t StopVibrator(const char *mode); 116 117 /** 118 * @brief Cancel the current motor vibration. 119 * @return Returning 0 indicates success; otherwise, it indicates failure. 120 * @since 10 121 */ 122 int32_t Cancel(); 123 124 /** 125 * @brief Set the usage of vibration. 126 * 127 * @param usage Indicates the vibration usage, which is described in {@link vibrator_agent_type.h},for 128 * example:{@link USAGE_ALARM}: Describes the vibration is used for alarm. 129 * 130 * @since 9 131 */ 132 bool SetUsage(int32_t usage, bool systemUsage = false); 133 134 /** 135 * @brief Query whether the HdHaptic is supported. 136 * 137 * @return Returning true indicates support; otherwise, it indicates no support. 138 * 139 * @since 12 140 */ 141 bool IsHdHapticSupported(); 142 143 /** 144 * @brief Query whether a vibration effect is supported. 145 * 146 * @param effectId Indicates the preset vibration effect, which is described in {@link vibrator_agent_type.h}, for 147 * example:{@link VIBRATOR_TYPE_CLOCK_TIMER}: Describes the vibration effect of the vibrator when a user adjusts the 148 * timer. 149 * @param state Indicates a pointer to the query result. 150 * @return Returning 0 indicates success; otherwise, it indicates failure. 151 * 152 * @since 10 153 */ 154 int32_t IsSupportEffect(const char *effectId, bool *state); 155 156 /** 157 * @brief Obtain the vibration delay, the time interval from the time the vibration is issued 158 * to the time when the vibration is started, which can be used in the scene of sound 159 * and vibration coordination. 160 * @param delayTime: Out of the parameter, return the vibration time delay, the time interval 161 * from the time the vibration is issued to the start of the vibration, in milliseconds. 162 * @return 0 indicates success, otherwise indicates failure. 163 * @since 11 164 */ 165 int32_t GetDelayTime(int32_t &delayTime); 166 167 /** 168 * @brief Decodes the vibration media file and generates the vibration waveform. 169 * @param fileDescription: The resulting vibration sequence package, such as {@link VibrationPackage}. 170 * @param package: the resulting vibration sequence package, such as {@link VibrationPackage}. 171 * @return 0 indicates success, otherwise indicates failure. 172 * @since 11 173 */ 174 int32_t PreProcess(const VibratorFileDescription &fd, VibratorPackage &package); 175 176 /** 177 * @brief Free up the vibration sequence package memory. 178 * @param package: Vibration sequence packages, such as {@link VibrationPackage}. 179 * @return 0 indicates success, otherwise indicates failure. 180 * @since 11 181 */ 182 int32_t FreeVibratorPackage(VibratorPackage &package); 183 184 /** 185 * @brief Play the vibration sequence. 186 * @param pattern: Vibration sequences, such as {@link VibratorPattern}. 187 * @return 0 indicates success, otherwise indicates failure. 188 * @since 11 189 */ 190 int32_t PlayPattern(const VibratorPattern &pattern); 191 192 /** 193 * @brief Set the vibration effect adjustment parameters. 194 * @param parameter: Vibration adjustment parameter, such as {@link VibratorParameter}. 195 * @return true indicates success, otherwise indicates failure. 196 * @since 11 197 */ 198 bool SetParameters(const VibratorParameter ¶meter); 199 200 /** 201 * @brief Control the vibrator to perform vibration with a preset vibration effect at a certain intensity. 202 * 203 * @param effectId Indicates the preset vibration effect, which is described in {@link vibrator_agent_type.h}, for 204 * example:{@link VIBRATOR_TYPE_HARD}: Describes the hard vibration effect of the vibrator. 205 * @param intensity Indicates the intensity of vibration, ranging from 1 to 100. 206 * @return Returns <b>0</b> if the vibrator vibrates as expected; otherwise indicates failure. 207 * 208 * @since 12 209 */ 210 int32_t PlayPrimitiveEffect(const char *effectId, int32_t intensity); 211 } // namespace Sensors 212 } // namespace OHOS 213 #ifdef __cplusplus 214 }; 215 #endif 216 /** @} */ 217 #endif // endif VIBRATOR_AGENT_H