Merge "update reviewed dox." into tizen_2.2
[platform/framework/native/appfw.git] / inc / FSysVibrator.h
1 //
2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
3 //
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
7 //
8 //     http://www.apache.org/licenses/LICENSE-2.0
9 //
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
15 //
16
17 /**
18  * @file        FSysVibrator.h
19  * @brief       This is the header file for the %Vibrator class.
20  *
21  * This header file contains the declarations of the %Vibrator class.
22  */
23
24 #ifndef _FSYS_VIBRATOR_H_
25 #define _FSYS_VIBRATOR_H_
26
27 #include <FBaseObject.h>
28
29 namespace Tizen { namespace System
30 {
31
32 /**
33  * @class   Vibrator
34  * @brief   This class handles the vibration functionality of the device.
35  *
36  * @since   2.0
37  *
38  * The %Vibrator class handles the vibration functionality of a device. It allows the management of the device's vibrator parameters, such as the vibration count and level.
39  *
40  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/system/vibrator_mgmt.htm">Vibrator Management</a>.
41  *
42  * The following example demonstrates how to use the %Vibrator class.
43  *
44  * @code
45  *
46  * #include <FBase.h>
47  * #include <FSystem.h>
48  *
49  * using namespace Tizen::Base;
50  * using namespace Tizen::System;
51  *
52  * class MyVibratorClass
53  * {
54  * public:
55  *  result VibratorExample(void);
56  * private:
57  *  Vibrator vibrator;
58  * };
59  *
60  * result
61  * MyVibratorClass::VibratorExample(void)
62  * {
63  *      result r = vibrator.Construct();
64  *      if (IsFailed(r))
65  *      {
66  *              goto CATCH;
67  *      }
68  *
69  *      // Initializes the vibration pattern
70  *      IntensityDurationVibrationPattern patterns[4] = {{2000, 50}, {1000, 0}, {500, -1}, {1000, 80}};
71  *      int length = sizeof(patterns);
72
73  *      // Vibrates with a given pattern and repeats count
74  *      vibrator.Start(patterns, length, 3);
75  *
76  *      return E_SUCCESS;
77  *
78  * CATCH:
79  *      // Do some exception handling
80  *      return r;
81  * }
82  * @endcode
83  */
84
85 /**
86  * @struct      IntensityDurationVibrationPattern
87  * @brief       This struct represents the specified duration and vibration intensity level.
88  *
89  * The %IntensityDurationVibrationPattern struct represents the specified duration and vibration intensity level. This struct can be used with Vibrator::Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount) as a custom pattern.
90  *
91  * @since 2.1
92  */
93 struct _OSP_EXPORT_ IntensityDurationVibrationPattern
94 {
95         int duration;   /**< The duration in milliseconds when the vibrator is on @n
96                                          *       The @c duration does not allow a negative value.
97                                          */
98         int intensity; /**< The vibration intensity [@c -1~ @c 100]: @n
99                                 *       @li The system default vibration intensity (-1)
100                                         *       @li The silent vibration intensity (0)
101                                         *       @li The minimum vibration intensity (1)
102                                         *       @li The maximum vibration intensity (100)
103                                         */
104 };
105
106
107 class _OSP_EXPORT_ Vibrator
108         : public Tizen::Base::Object
109 {
110
111 public:
112         /**
113          * This is the default constructor for this class. @n
114          * The object is not fully constructed after this constructor is called.
115          * For full construction, the Construct() method must be called right after calling this constructor.
116          * @since   2.0
117          *
118          */
119         Vibrator(void);
120
121         /**
122          * This is the destructor for this class. @n
123          * This destructor overrides Tizen::Base::Object::~Object().
124          *
125          * @since   2.0
126          *
127          * @remarks If the instance is destroyed before the vibration stops, the vibration is stopped forcefully.
128          */
129         virtual ~Vibrator(void);
130
131         /**
132          * Initializes this instance of %Vibrator.
133          *
134          * @since       2.0
135          *
136          * @return      An error code
137          * @exception   E_SUCCESS           The method is successful.
138          * @exception   E_SYSTEM            An unknown operating system error has occurred.
139          *
140          */
141         result Construct(void);
142
143
144         /**
145          * Vibrates the device with a specified array pattern that has a vibration intensity and duration. @n
146          * The %Start() method returns the result immediately so that the vibration occurs simultaneously as the device runs. @n
147          * If this method is called again before the previous vibration stops, the previous vibration is cancelled and the new vibration starts immediately. @n
148          * If a new vibrator instance triggers the vibration, the vibrator merges the previous vibration pattern with the new one in the overlapped time. @n
149          * If a system alert occurs such as a ring vibration or a system event notification, the vibration can be interrupted. @n
150          * If the application is terminated, the vibration is cancelled.
151          *
152          * @since 2.1
153              * @privlevel       public
154          * @privilege   %http://tizen.org/privilege/vibrator
155          *
156          * @return      An error code
157          *
158          * @param[in]   patterns             The 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 
161                  *                                                                       This value must be between @c 1 to @c 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 the vibration.
167          * @see  IntensityDurationVibrationPattern
168          */
169         result Start(IntensityDurationVibrationPattern* patterns, int length, int repeatCount = 1);
170
171         /**
172          * Vibrates the device with the specified pattern and level. @n
173          * The %Start() 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 cancelled and the new vibration starts immediately.
175          *
176          * @brief               <i>[Deprecated]</i>
177          * @deprecated  This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern*, int, int).
178          * @since 2.0
179          * @privlevel   public
180          * @privilege   %http://tizen.org/privilege/vibrator
181          *
182          * @return      An error code
183          * @param[in]   onPeriod                The period in milliseconds when the vibrator is on @n
184          *                                      It should be greater than @c 0.
185          * @param[in]   offPeriod               The period in milliseconds when the vibrator is off @n
186          *                                      It should be equal to or greater than @c 0.
187          * @param[in]   count                   The number of times to execute the given pattern @n
188          *                                      It should be greater than @c 0.
189          * @param[in]   level                   The vibration level @n
190          *                                      It ranges from [@c 0~ @c 100], where '@c 0' is a special case indicating the system default level.
191          * @exception   E_SUCCESS           The method is successful.
192          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
193          * @exception   E_INVALID_ARG       A specified input parameter is invalid.
194          * @exception   E_DEVICE_BUSY       The device cannot be approached because of other operations.
195          * @exception   E_DEVICE_FAILED     The device operation has failed.
196          * @remarks     Various devices may have different vibration capabilities. @n
197          *                      If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration. @n
198          *                      If the device supports many levels of vibration, then a level value @c 0 results in the system default vibration, 
199          *                      value @c 1 results in the lowest frequency vibration, value @c 100 results in the highest frequency vibration, and intermediate values result in 
200          *                      intermediate vibration levels. @n
201          *                      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 
202          *                      greater than the limit.
203          *
204          */
205         result Start(long onPeriod, long offPeriod, int count, int level = 0);
206
207         /**
208          * Vibrates the device for the specified duration at the specified level. @n
209          * The %Start() method returns the result immediately so that the vibration occurs simultaneously as the device runs.
210          * If this method is called again before the previous vibration stops, the previous vibration is cancelled and the new vibration starts immediately.
211          *
212          * @brief               <i>[Deprecated]</i>
213          * @deprecated  This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern*, int, int).
214          * @since       2.0
215          * @privlevel   public
216          * @privilege   %http://tizen.org/privilege/vibrator
217          *
218          * @return      An error code
219          * @param[in]   milliseconds            The duration for the vibration in milliseconds @n
220          *                                      It should be greater than @c 0.
221          * @param[in]   level                   The vibration level @n
222          *                                      It ranges from [@c 0~ @c 100], where ' @c 0' is a special case indicating the system default level.
223          * @exception   E_SUCCESS               The method is successful.
224          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
225          * @exception   E_INVALID_ARG       A specified input parameter is invalid.
226          * @exception   E_DEVICE_BUSY       The device cannot be approached because of other operations.
227          * @exception   E_DEVICE_FAILED     The device operation has failed.
228          * @remarks     Various devices have different vibration capabilities. @n
229          *                      If the device supports only one level of vibration, then a level value between [@c 0~ @c 100] results in the default vibration. @n
230          *                      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 
231          *                      frequency vibration, value @c 100 results in the highest frequency vibration, and intermediate values result in intermediate vibration levels. @n
232          *                      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 
233          *                      greater than the limit.
234          *
235          */
236         result Start(long milliseconds, int level = 0);
237
238         /**
239          * Turns the vibrator off.
240          *
241          * @since       2.0
242          * @privlevel   public
243          * @privilege   %http://tizen.org/privilege/vibrator
244          *
245          * @return      An error code
246          * @exception   E_SUCCESS           The method is successful.
247          * @exception   E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
248          * @exception   E_DEVICE_FAILED     The device operation has failed.
249          *
250          */
251         result Stop(void);
252
253 private:
254         /**
255          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
256          */
257         Vibrator(const Vibrator& value);
258
259         /**
260          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
261          */
262         Vibrator& operator =(const Vibrator& value);
263
264 private:
265         friend class _VibratorImpl;
266         class _VibratorImpl* __pVibratorImpl;
267
268 }; // Vibrator
269
270 } } // Tizen::System
271
272 #endif