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