2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FSysVibrator.h
20 * @brief This is the header file for the %Vibrator class.
22 * This header file contains the declarations of the %Vibrator class.
25 #ifndef _FSYS_VIBRATOR_H_
26 #define _FSYS_VIBRATOR_H_
28 #include <FBaseObject.h>
30 namespace Tizen { namespace System
35 * @brief This class handles the vibration functionality of the device.
39 * The %Vibrator class handles the vibration functionality of a device. It allows you to manage the device's vibrator parameters, such as vibration count and level.
41 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/system/vibrator_mgmt.htm">Vibrator Management</a>.
43 * The following example demonstrates how to use the %Vibrator class.
48 * #include <FSystem.h>
50 * using namespace Tizen::Base;
51 * using namespace Tizen::System;
53 * class MyVibratorClass
56 * result VibratorExample(void);
62 * MyVibratorClass::VibratorExample(void)
64 * result r = vibrator.Construct();
70 * // Initializes the vibration pattern
71 * IntensityDurationVibrationPattern patterns[4] = {{2000, 50}, {1000, 0}, {500, -1}, {1000, 80}};
72 * int length = sizeof(patterns);
74 * // Vibrates with a given pattern and repeats count
75 * vibrator.Start(patterns, length, 3);
80 * // Do some exception handling
87 * @struct IntensityDurationVibrationPattern
88 * @brief This struct has the specified duration and a vibration intensity level.
90 * The %IntensityDurationVibrationPattern struct has the specified duration and a vibration intensity level. This can be used with Vibrator::Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount) as a custom pattern.
94 struct _OSP_EXPORT_ IntensityDurationVibrationPattern
96 int duration; /**< The duration in milliseconds when the vibrator is on @n
97 * The @c duration is not allowed a negative value.
99 int intensity; /**< The vibration intensity [@c -1~ @c 100]: @n
100 * @li The system default vibration intensity (-1)
101 * @li The silent vibration intensity (0)
102 * @li The minimum vibration intensity (1)
103 * @li The maximum vibration intensity (100)
108 class _OSP_EXPORT_ Vibrator
109 : public Tizen::Base::Object
114 * This is the default constructor for this class.
118 * @remarks The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
123 * This is the destructor for this class. @n
124 * This destructor overrides Tizen::Base::Object::~Object().
128 * @remarks If the instance is destroyed before the vibration stops, the vibration is stopped forcefully.
130 virtual ~Vibrator(void);
133 * Initializes this instance of %Vibrator.
137 * @return An error code
138 * @exception E_SUCCESS The method is successful.
139 * @exception E_SYSTEM An unknown operating system error has occurred.
142 result Construct(void);
146 * Vibrates the device with a specified array pattern that has vibration intensity and duration. @n
147 * The %Start() method returns the result immediately so that the vibration occurs simultaneously as the device runs. @n
148 * If this method is called again before the previous vibration stops, the previous vibration is canceled and the new vibration starts immediately. @n
149 * If a new vibrator instance triggers the vibration, the vibrator merges the previous vibration pattern with the new one in the overlapped time. @n
150 * If the system alert occurs such as ring vibration and a system event notification, the vibration can be interrupted. @n
151 * If the application is terminated, the vibration is canceled.
154 * @privilege %http://tizen.org/privilege/vibrator
156 * @return An error code
158 * @param[in] patterns An array of @c IntensityDurationVibrationPattern
159 * @param[in] length The length of @c patterns
160 * @param[in] repeatCount The number of times the pattern repeats @n This value must be between @c 1 to @c 100.
161 * @exception E_SUCCESS The method is successful.
162 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
163 * @exception E_INVALID_ARG A specified input parameter is invalid.
164 * @exception E_OPERATION_FAILED The device operation has failed.
165 * @remarks The vibration intensity does not apply the change, even if the system default vibration intensity is changed after starting vibration.
166 * @see IntensityDurationVibrationPattern
168 result Start(IntensityDurationVibrationPattern* patterns, int length, int repeatCount = 1);
171 * Vibrates the device with the specified pattern and level. @n
172 * The %Start() method returns the result immediately so that the vibration occurs simultaneously as the device runs.
173 * If this method is called again before the previous vibration stops, the previous vibration is canceled and the new vibration starts immediately.
175 * @deprecated This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount).
178 * @privilege %http://tizen.org/privilege/vibrator
180 * @return An error code
181 * @param[in] onPeriod The period in milliseconds when the vibrator is on @n
182 * It should be greater than @c 0.
183 * @param[in] offPeriod The period in milliseconds when the vibrator is off @n
184 * It should be equal to or greater than @c 0.
185 * @param[in] count The number of times to execute the given pattern @n
186 * It should be greater than @c 0.
187 * @param[in] level The vibration level @n
188 * Ranges from [@c 0~ @c 100], where '@c 0' is a special case indicating the system default level.
189 * @exception E_SUCCESS The method is successful.
190 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
191 * @exception E_INVALID_ARG A specified input parameter is invalid.
192 * @exception E_DEVICE_BUSY The device cannot be approached because of other operations.
193 * @exception E_DEVICE_FAILED The device operation has failed.
194 * @remarks Various devices may have different vibration capabilities.
195 * If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration.
196 * If the device supports many levels of vibration, then a level value @c 0 results in the system default vibration, value @c 1 results in the lowest frequency vibration, value @c 100 results in the highest frequency vibration, and intermediate values result in intermediate vibration levels. @n
197 * Devices have implementation-specific limits for the total duration of the vibration, and vibration cuts off at that limit even if the duration parameter is greater than the limit.
200 result Start(long onPeriod, long offPeriod, int count, int level = 0);
203 * Vibrates the device for the specified duration at the specified @c level. @n
204 * The %Start() method returns the result immediately so that the vibration occurs simultaneously as the device runs.
205 * If this method is called again before the previous vibration stops, the previous vibration is canceled and the new vibration starts immediately.
207 * @deprecated This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount).
210 * @privilege %http://tizen.org/privilege/vibrator
212 * @return An error code
213 * @param[in] milliseconds The duration for the vibration in milliseconds @n
214 * It should be greater than @c 0.
215 * @param[in] level The vibration level @n
216 * Ranges from [@c 0~ @c 100], where ' @c 0' is a special case indicating the system default level.
217 * @exception E_SUCCESS The method is successful.
218 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
219 * @exception E_INVALID_ARG A specified input parameter is invalid.
220 * @exception E_DEVICE_BUSY The device cannot be approached because of other operations.
221 * @exception E_DEVICE_FAILED The device operation has failed.
222 * @remarks Various devices have different vibration capabilities. @n
223 * If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration.
224 * If the device supports many levels of vibration, then a level value @c 0 results in the system default vibration, value @c 1 results in the lowest frequency vibration, value @c 100 results in the highest frequency vibration, and intermediate values result in intermediate vibration levels. @n
225 * Devices have implementation-specific limits for the total duration of the vibration, and vibration cuts off at that limit even if the duration parameter is greater than the limit.
228 result Start(long milliseconds, int level = 0);
231 * Turns the vibrator off.
235 * @privilege %http://tizen.org/privilege/vibrator
237 * @return An error code
238 * @exception E_SUCCESS The method is successful.
239 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
240 * @exception E_DEVICE_FAILED The device operation has failed.
247 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
249 Vibrator(const Vibrator& value);
252 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
254 Vibrator& operator =(const Vibrator& value);
257 friend class _VibratorImpl;
258 class _VibratorImpl* __pVibratorImpl;