1 /* 2 * Copyright (c) 2021-2023 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: 60 * {@link VIBRATOR_TYPE_CLOCK_TIMER}: Describes the vibration effect of the vibrator when a user adjusts the 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: 129 * {@link USAGE_ALARM}: Describes the vibration is used for alarm. 130 * 131 * @since 9 132 */ 133 bool SetUsage(int32_t usage); 134 135 /** 136 * @brief Query whether a vibration effect is supported. 137 * 138 * @param effectId Indicates the preset vibration effect, which is described in {@link vibrator_agent_type.h}, for 139 * example: 140 * {@link VIBRATOR_TYPE_CLOCK_TIMER}: Describes the vibration effect of the vibrator when a user adjusts the timer. 141 * @param state Indicates a pointer to the query result. 142 * @return Returning 0 indicates success; otherwise, it indicates failure. 143 * 144 * @since 10 145 */ 146 int32_t IsSupportEffect(const char *effectId, bool *state); 147 } // namespace Sensors 148 } // namespace OHOS 149 #ifdef __cplusplus 150 }; 151 #endif 152 /** @} */ 153 #endif // endif VIBRATOR_AGENT_H