src/Tizen.System/Device/Haptic.cs

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