src/Tizen.System/Device/Haptic.cs

   1 /*
   2 * Copyright (c) 2018 Samsung Electronics Co., Ltd All Rights Reserved
   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 using System;
  18 using System.Collections.Generic;
  19 namespace Tizen.System
  20 {
  21     /// <summary>
  22     /// The Vibrator class provides the properties and methods to control a vibrator.
  23     /// </summary>
  24     /// <remarks>
  25     /// The Vibrator API provides the way to access the vibrators in the device.
  26     /// It allows the management of the device's vibrator parameters, such as the vibration count and level.
  27     /// It provides the methods to vibrate and stop the vibration.
  28     /// </remarks>
  29     /// <privilege>
  30     /// http://tizen.org/privilege/haptic
  31     /// </privilege>
  32     /// <feature>
  33     /// http://tizen.org/feature/feedback.vibration
  34     /// </feature>
  35     /// <exception cref="ArgumentException"> When an invalid parameter value is set.</exception>
  36     /// <exception cref="UnauthorizedAccessException">If the privilege is not set.</exception>
  37     /// <exception cref="InvalidOperationException">In case of any system error.</exception>
  38     /// <exception creg="NotSupportedException">The required feature is not supported</exception>
  39     /// <example>
  40     /// <code>
  41     ///     Console.WriteLine("Total number of Vibrators are: {0}", Tizen.System.Vibrator.NumberOfVibrators);
  42     /// </code>
  43     /// </example>
  44     /// <since_tizen> 3 </since_tizen>
  45     public class Vibrator : IDisposable
  46     {
  47         private readonly int _vibratorId;
  48         private IntPtr _hapticHandle = IntPtr.Zero;
  49         private bool _disposedValue = false;
  50         private static Lazy<IReadOnlyList<Vibrator>> _lazyVibrators;
  51         private static int _maxcount = 0;
  52         private Vibrator(int id)
  53         {
  54             _vibratorId = id;
  55             DeviceError res = (DeviceError)Interop.Device.DeviceHapticOpen(_vibratorId, out _hapticHandle);
  56             if (res != DeviceError.None)
  57             {
  58                 throw DeviceExceptionFactory.CreateException(res, "unable to create Vibrator for given Id");
  59             }
  60             res = (DeviceError)Interop.Device.DeviceHapticGetCount(out _maxcount);
  61             if (res != DeviceError.None)
  62             {
  63                 Log.Warn(DeviceExceptionFactory.LogTag, "unable to get Vibrators count.");
  64             }
  65
  66         }
  67
  68         /// <summary>
  69         /// Finalizes an instance of the Vibrator class.
  70         /// </summary>
  71         ~Vibrator()
  72         {
  73             Dispose(false);
  74         }
  75         /// <summary>
  76         /// Gets the number of the available vibrators.
  77         /// </summary>
  78         /// <since_tizen> 3 </since_tizen>
  79         public static int NumberOfVibrators
  80         {
  81             get
  82             {
  83                 int count = 0;
  84                 DeviceError res = (DeviceError)Interop.Device.DeviceHapticGetCount(out count);
  85                 if (res != DeviceError.None)
  86                 {
  87                     Log.Warn(DeviceExceptionFactory.LogTag, "unable to get Vibrators count.");
  88                 }
  89                 return count;
  90             }
  91         }
  92         /// <summary>
  93         /// Gets all the available vibrators.
  94         /// </summary>
  95         /// <since_tizen> 3 </since_tizen>
  96         public static IReadOnlyList<Vibrator> Vibrators
  97         {
  98             get
  99             {
 100                 _lazyVibrators = new Lazy<IReadOnlyList<Vibrator>>(() => GetAllVibrators());
 101                 return _lazyVibrators.Value;
 102             }
 103         }
 104         private static IReadOnlyList<Vibrator> GetAllVibrators()
 105         {
 106             int count = 0;
 107             List<Vibrator> vibrators = new List<Vibrator>();
 108             DeviceError res = (DeviceError)Interop.Device.DeviceHapticGetCount(out count);
 109             if (res != DeviceError.None)
 110             {
 111                 throw DeviceExceptionFactory.CreateException(res, "unable to get Vibrators count.");
 112             }
 113             for (int i = 0; i < NumberOfVibrators; i++)
 114             {
 115                 vibrators.Add(new Vibrator(i));
 116             }
 117             return vibrators;
 118
 119         }
 120         /// <summary>
 121         /// Vibrates during the specified time with a constant intensity.
 122         /// This function can be used to start monotonous vibration for the specified time.
 123         /// </summary>
 124         /// <since_tizen> 3 </since_tizen>
 125         /// <param name="duration">The play duration in milliseconds.</param>
 126         /// <param name="feedback">The amount of the intensity variation (0 ~ 100).</param>
 127         /// <feature>
 128         /// http://tizen.org/feature/feedback.vibration
 129         /// </feature>
 130         /// <exception cref="ArgumentException"> When an invalid parameter value is set.</exception>
 131         /// <exception cref="UnauthorizedAccessException">If the privilege is not set.</exception>
 132         /// <exception cref="InvalidOperationException">In case of any system error.</exception>
 133         /// <exception cref="NotSupportedException">In case the device does not support this behavior.</exception>
 134         /// <example>
 135         /// <code>
 136         ///     Vibrator vibrator = Vibrator.Vibrators[0];
 137         ///     try
 138         ///     {
 139         ///         vibrator.Vibrate(2000, 70);
 140         ///     }
 141         ///     Catch(Exception e)
 142         ///     {
 143         ///     }
 144         /// </code>
 145         /// </example>
 146
 147         public void Vibrate(int duration, int feedback)
 148         {
 149             IntPtr effect;
 150             DeviceError res = DeviceError.None;
 151             if (_hapticHandle == IntPtr.Zero)
 152             {
 153                 res = (DeviceError)Interop.Device.DeviceHapticOpen(_vibratorId, out _hapticHandle);
 154                 if (res != DeviceError.None)
 155                 {
 156                     throw DeviceExceptionFactory.CreateException(res, "unable to get vibrator.");
 157                 }
 158             }
 159
 160             res = (DeviceError)Interop.Device.DeviceHapticVibrate(_hapticHandle, duration, feedback, out effect);
 161             if (res != DeviceError.None)
 162             {
 163                 throw DeviceExceptionFactory.CreateException(res, "unable to vibrate the current vibrator.");
 164             }
 165         }
 166         /// <summary>
 167         /// Stops all the vibration effects which are being played.
 168         /// This function can be used to stop all the effects started by Vibrate().
 169         /// </summary>
 170         /// <since_tizen> 3 </since_tizen>
 171         /// <feature>
 172         /// http://tizen.org/feature/feedback.vibration
 173         /// </feature>
 174         /// <exception cref="ArgumentException"> In case an invalid vibrator instance is used.</exception>
 175         /// <exception cref="UnauthorizedAccessException">If the privilege is not set.</exception>
 176         /// <exception cref="InvalidOperationException">In case of any system error.</exception>
 177         /// <exception cref="NotSupportedException">In case the device does not support this behavior.</exception>
 178         /// <example>
 179         /// <code>
 180         ///     Vibrator vibrator = Vibrator.Vibrators[0];
 181         ///     try
 182         ///     {
 183         ///         vibrator.Stop();
 184         ///     }
 185         ///     Catch(Exception e)
 186         ///     {
 187         ///     }
 188         /// </code>
 189         /// </example>
 190         public void Stop()
 191         {
 192             if (_hapticHandle != IntPtr.Zero)
 193             {
 194                 DeviceError res = (DeviceError)Interop.Device.DeviceHapticStop(_hapticHandle, IntPtr.Zero);
 195                 if (res != DeviceError.None)
 196                 {
 197                     throw DeviceExceptionFactory.CreateException(res, "unable to stop the current vibrator.");
 198                 }
 199             }
 200         }
 201         /// <summary>
 202         /// Dispose API for closing the internal resources.
 203         /// This function can be used to stop all the effects started by Vibrate().
 204         /// </summary>
 205         /// <since_tizen> 3 </since_tizen>
 206         public void Dispose()
 207         {
 208             Dispose(true);
 209             GC.SuppressFinalize(this);
 210         }
 211
 212         /// <summary>
 213         /// Dispose API for closing the internal resources.
 214         /// This function can be used to stop all the effects started by Vibrate().
 215         /// </summary>
 216         /// <since_tizen> 3 </since_tizen>
 217         protected virtual void Dispose(bool disposing)
 218         {
 219             if (!_disposedValue)
 220             {
 221                 if (_hapticHandle != IntPtr.Zero)
 222                 {
 223                     Interop.Device.DeviceHapticClose(_hapticHandle);
 224                     _hapticHandle = IntPtr.Zero;
 225                 }
 226                 _disposedValue = true;
 227             }
 228         }
 229     }
 230 }