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 * // Vibrate with a given pattern and level
71 * vibrator.Start(2000, 1000, 1, 50);
76 * // Do some exception handling
82 class _OSP_EXPORT_ Vibrator
83 : public Tizen::Base::Object
88 * This is the default constructor for this class.
92 * @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.
97 * This is the destructor for this class. @n
98 * This destructor overrides Tizen::Base::Object::~Object().
102 * @remarks If the instance is destroyed before the vibration stops, the vibration is stopped forcefully.
104 virtual ~Vibrator(void);
107 * Initializes this instance of %Vibrator.
111 * @return An error code
112 * @exception E_SUCCESS The method is successful.
113 * @exception E_SYSTEM An unknown operating system error has occurred.
116 result Construct(void);
119 * Vibrates the device with the specified pattern and level. @n
120 * This method returns the result immediately so that the vibration occurs simultaneously as the device runs.
121 * If this method is called again before the previous vibration stops, the previous vibration is canceled and the new vibration starts immediately.
125 * @privilege %http://tizen.org/privilege/vibrator
127 * @return An error code
128 * @param[in] onPeriod The period in milliseconds when the vibrator is on @n
129 * It should be greater than @c 0.
130 * @param[in] offPeriod The period in milliseconds when the vibrator is off @n
131 * It should be equal to or greater than @c 0.
132 * @param[in] count The number of times to execute the given pattern @n
133 * It should be greater than @c 0.
134 * @param[in] level The vibration level @n
135 * Ranges from [@c 0~ @c 100], where ' @c 0' is a special case indicating the system default level.
136 * @exception E_SUCCESS The method is successful.
137 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
138 * @exception E_INVALID_ARG A specified input parameter is invalid.
139 * @exception E_DEVICE_BUSY The device cannot be approached because of other operations.
140 * @exception E_DEVICE_FAILED The device operation has failed.
141 * @remarks Various devices may have different vibration capabilities.
142 * If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration.
143 * 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
144 * 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.
147 result Start(long onPeriod, long offPeriod, int count, int level = 0);
150 * Vibrates the device for the specified duration at the specified @c level. @n
151 * This method returns the result immediately so that the vibration occurs simultaneously as the device runs.
152 * If this method is called again before the previous vibration stops, the previous vibration is canceled and the new vibration starts immediately.
156 * @privilege %http://tizen.org/privilege/vibrator
158 * @return An error code
159 * @param[in] milliseconds The duration for the vibration in milliseconds @n
160 * It should be greater than @c 0.
161 * @param[in] level The vibration level @n
162 * Ranges from [@c 0~ @c 100], where ' @c 0' is a special case indicating the system default level.
163 * @exception E_SUCCESS The method is successful.
164 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
165 * @exception E_INVALID_ARG A specified input parameter is invalid.
166 * @exception E_DEVICE_BUSY The device cannot be approached because of other operations.
167 * @exception E_DEVICE_FAILED The device operation has failed.
168 * @remarks Various devices have different vibration capabilities. @n
169 * If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration.
170 * 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
171 * 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.
174 result Start(long milliseconds, int level = 0);
177 * Turns the vibrator off.
181 * @privilege %http://tizen.org/privilege/vibrator
183 * @return An error code
184 * @exception E_SUCCESS The method is successful.
185 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
186 * @exception E_DEVICE_FAILED The device operation has failed.
193 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
195 Vibrator(const Vibrator& value);
198 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
200 Vibrator& operator =(const Vibrator& value);
203 friend class _VibratorImpl;
204 class _VibratorImpl* __pVibratorImpl;