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 * // Initialize vibration pattern
71 * IntensityDurationVibrationPattern patterns[4] = {{2000, 50}, {1000, 0}, {500, -1}, {1000, 80}};
72 * int length = sizeof(patterns);
74 * // Vibrate with a given pattern and repeat 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 * 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 the specified array pattern which has vibration intensity and duration. @n
147 * This 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.
155 * @privilege http://tizen.org/privilege/vibrator
157 * @return An error code
159 * @param[in] patterns An array of @c IntensityDurationVibrationPattern.
160 * @param[in] length The length of @c patterns.
161 * @param[in] repeatCount The number of repeat for pattern. This value has to be between 1 to 100.
162 * @exception E_SUCCESS The method is successful.
163 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
164 * @exception E_INVALID_ARG A specified input parameter is invalid.
165 * @exception E_OPERATION_FAILED The device operation has failed.
166 * @remarks The vibration intensity does not apply the change, even if the system default vibration intensity is changed after starting vibration.
167 * @see IntensityDurationVibrationPattern
169 result Start(IntensityDurationVibrationPattern* patterns, int length, int repeatCount = 1);
172 * Vibrates the device with the specified pattern and level. @n
173 * This method returns the result immediately so that the vibration occurs simultaneously as the device runs.
174 * If this method is called again before the previous vibration stops, the previous vibration is canceled and the new vibration starts immediately.
178 * @deprecated This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount).
181 * @privilege http://tizen.org/privilege/vibrator
183 * @return An error code
184 * @param[in] onPeriod The period in milliseconds when the vibrator is on @n
185 * It should be greater than @c 0.
186 * @param[in] offPeriod The period in milliseconds when the vibrator is off @n
187 * It should be equal to or greater than @c 0.
188 * @param[in] count The number of times to execute the given pattern @n
189 * It should be greater than @c 0.
190 * @param[in] level The vibration level @n
191 * Ranges from [@c 0~ @c 100], where ' @c 0' is a special case indicating the system default level.
192 * @exception E_SUCCESS The method is successful.
193 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
194 * @exception E_INVALID_ARG A specified input parameter is invalid.
195 * @exception E_DEVICE_BUSY The device cannot be approached because of other operations.
196 * @exception E_DEVICE_FAILED The device operation has failed.
197 * @remarks Various devices may have different vibration capabilities.
198 * If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration.
199 * 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
200 * 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.
203 result Start(long onPeriod, long offPeriod, int count, int level = 0);
206 * Vibrates the device for the specified duration at the specified @c level. @n
207 * This method returns the result immediately so that the vibration occurs simultaneously as the device runs.
208 * If this method is called again before the previous vibration stops, the previous vibration is canceled and the new vibration starts immediately.
212 * @deprecated This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount).
215 * @privilege http://tizen.org/privilege/vibrator
217 * @return An error code
218 * @param[in] milliseconds The duration for the vibration in milliseconds @n
219 * It should be greater than @c 0.
220 * @param[in] level The vibration level @n
221 * Ranges from [@c 0~ @c 100], where ' @c 0' is a special case indicating the system default level.
222 * @exception E_SUCCESS The method is successful.
223 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
224 * @exception E_INVALID_ARG A specified input parameter is invalid.
225 * @exception E_DEVICE_BUSY The device cannot be approached because of other operations.
226 * @exception E_DEVICE_FAILED The device operation has failed.
227 * @remarks Various devices have different vibration capabilities. @n
228 * If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration.
229 * 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
230 * 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.
233 result Start(long milliseconds, int level = 0);
236 * Turns the vibrator off.
241 * @privilege http://tizen.org/privilege/vibrator
243 * @return An error code
244 * @exception E_SUCCESS The method is successful.
245 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
246 * @exception E_DEVICE_FAILED The device operation has failed.
253 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
255 Vibrator(const Vibrator& value);
258 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
260 Vibrator& operator =(const Vibrator& value);
263 friend class _VibratorImpl;
264 class _VibratorImpl* __pVibratorImpl;