inc/FSysVibrator.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  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.
  16 //
  17
  18 /**
  19  * @file        FSysVibrator.h
  20  * @brief       This is the header file for the %Vibrator class.
  21  *
  22  * This header file contains the declarations of the %Vibrator class.
  23  */
  24
  25 #ifndef _FSYS_VIBRATOR_H_
  26 #define _FSYS_VIBRATOR_H_
  27
  28 #include <FBaseObject.h>
  29
  30 namespace Tizen { namespace System
  31 {
  32
  33 /**
  34  * @class   Vibrator
  35  * @brief   This class handles the vibration functionality of the device.
  36  *
  37  * @since   2.0
  38  *
  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.
  40  *
  41  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/system/vibrator_mgmt.htm">Vibrator Management</a>.
  42  *
  43  * The following example demonstrates how to use the %Vibrator class.
  44  *
  45  * @code
  46  *
  47  * #include <FBase.h>
  48  * #include <FSystem.h>
  49  *
  50  * using namespace Tizen::Base;
  51  * using namespace Tizen::System;
  52  *
  53  * class MyVibratorClass
  54  * {
  55  * public:
  56  *  result VibratorExample(void);
  57  * private:
  58  *  Vibrator vibrator;
  59  * };
  60  *
  61  * result
  62  * MyVibratorClass::VibratorExample(void)
  63  * {
  64  *      result r = vibrator.Construct();
  65  *      if (IsFailed(r))
  66  *      {
  67  *              goto CATCH;
  68  *      }
  69  *
  70  *      // Initializes the vibration pattern
  71  *      IntensityDurationVibrationPattern patterns[4] = {{2000, 50}, {1000, 0}, {500, -1}, {1000, 80}};
  72  *      int length = sizeof(patterns);
  73
  74  *      // Vibrates with a given pattern and repeats count
  75  *      vibrator.Start(patterns, length, 3);
  76  *
  77  *      return E_SUCCESS;
  78  *
  79  * CATCH:
  80  *      // Do some exception handling
  81  *      return r;
  82  * }
  83  * @endcode
  84  */
  85
  86 /**
  87  * @struct      IntensityDurationVibrationPattern
  88  * @brief       This struct has the specified duration and a vibration intensity level.
  89  *
  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.
  91  *
  92  * @since 2.1
  93  */
  94 struct _OSP_EXPORT_ IntensityDurationVibrationPattern
  95 {
  96         int duration; /**< The duration in milliseconds when the vibrator is on @n
  97                         *       The @c duration is not allowed a negative value.
  98                         */
  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)
 104                         */
 105 };
 106
 107
 108 class _OSP_EXPORT_ Vibrator
 109         : public Tizen::Base::Object
 110 {
 111
 112 public:
 113         /**
 114          * This is the default constructor for this class.
 115          *
 116          * @since   2.0
 117          *
 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.
 119          */
 120         Vibrator(void);
 121
 122         /**
 123          * This is the destructor for this class. @n
 124          * This destructor overrides Tizen::Base::Object::~Object().
 125          *
 126          * @since   2.0
 127          *
 128          * @remarks If the instance is destroyed before the vibration stops, the vibration is stopped forcefully.
 129          */
 130         virtual ~Vibrator(void);
 131
 132         /**
 133          * Initializes this instance of %Vibrator.
 134          *
 135          * @since       2.0
 136          *
 137          * @return      An error code
 138          * @exception   E_SUCCESS           The method is successful.
 139          * @exception   E_SYSTEM            An unknown operating system error has occurred.
 140          *
 141          */
 142         result Construct(void);
 143
 144
 145         /**
 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.
 152          *
 153          * @since 2.1
 154          * @privilege     %http://tizen.org/privilege/vibrator
 155          *
 156          * @return      An error code
 157          *
 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
 167          */
 168         result Start(IntensityDurationVibrationPattern* patterns, int length, int repeatCount = 1);
 169
 170         /**
 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.
 174          *
 175          * @deprecated This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount).
 176          * @since 2.0
 177          * @privlevel   public
 178          * @privilege   %http://tizen.org/privilege/vibrator
 179          *
 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.
 198          *
 199          */
 200         result Start(long onPeriod, long offPeriod, int count, int level = 0);
 201
 202         /**
 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.
 206          *
 207          * @deprecated This method is deprecated. Instead of using this method, use Start(IntensityDurationVibrationPattern[] patterns, int length, int repeatCount).
 208          * @since       2.0
 209          * @privlevel   public
 210          * @privilege   %http://tizen.org/privilege/vibrator
 211          *
 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.
 226          *
 227          */
 228         result Start(long milliseconds, int level = 0);
 229
 230         /**
 231          * Turns the vibrator off.
 232          *
 233          * @since   2.0
 234          * @privlevel   public
 235          * @privilege   %http://tizen.org/privilege/vibrator
 236          *
 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.
 241          *
 242          */
 243         result Stop(void);
 244
 245 private:
 246         /**
 247          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 248          */
 249         Vibrator(const Vibrator& value);
 250
 251         /**
 252          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 253          */
 254         Vibrator& operator =(const Vibrator& value);
 255
 256 private:
 257         friend class _VibratorImpl;
 258         class _VibratorImpl* __pVibratorImpl;
 259
 260 }; // Vibrator
 261
 262 } } // Tizen::System
 263
 264 #endif