SLP_HAPTIC_PG.h

   1 /*
   2  *  haptic
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: DongGi Jang <dg0402.jang@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20 */
  21
  22
  23 /**
  24  *
  25  * @ingroup SLP_PG
  26  * @defgroup SLP_HAPTIC_PG Haptic Library
  27  * @{
  28
  29 <h1 class="pg">Introduction</h1>
  30
  31 <h2 class="pg">Purpose</h2>
  32 The purpose of this document is to describe how applications can use Haptic Library APIs. This document gives programming guidelines to application engineers.
  33
  34 <h2 class="pg">Scope</h2>
  35 The scope of this document is limited to Haptic Library API usage.
  36
  37 <br>
  38 <h1 class="pg">Device Manager Library Overview</h1>
  39 <h2 class="pg">Haptic Device Manager</h2>
  40 <h3 class="pg" align="center">Haptic Vibration Functional Level Architecture</h3>
  41 @image html SLP_devman_PG_haptic_architecture.png
  42
  43 The client side is available in the form of a shared library to all the processes, whereas the server is a daemon.
  44 As shown in the diagram applications/middleware frameworks can have the haptic vibration client library in the process context.
  45 <br><br>
  46 The haptic vibration client is available in form of a shared library. This library has APIs which support various features.
  47 These features are playing a rhythmical vibration pattern, playing a monotonous vibration pattern, etc.
  48 Applications can call these APIs to give vibration feedback on any event. This could also be used to indicate any events or changes of a state to the user.
  49 <br><br>
  50 The server interacts with the device driver interfaces and generates vibration feedback.
  51 <br><br>
  52 <h3 class="pg">Haptic Vibration Features</h3>
  53 <b>Haptic client features</b>
  54 -#      Available in shared library form.<br>
  55 -#      Provides set of APIs to play haptic vibration patterns.<br>
  56 -#      Provide unique access control mechanism through client server architecture.<br>
  57 -#      Provision to play rhythmical vibration patterns.<br>
  58 -#      Provides functionality for application to play a different vibration pattern for a different event.<br>
  59 -#      Provides support for user defined duration for monotone playing or iteration for pattern playing.<br>
  60 -#      Provides immediate stop control over the vibrations played.<br><br>
  61
  62 <b>Haptic server features</b>
  63 -#      The actual implementation of the functionality supported by haptic-vibration library has been implemented through haptic-server.<br>
  64 -#      Haptic-server processes the vibration pattern's play/stop requests sent by application through the haptic client library.<br>
  65 -#      There is an internal database maintained for different patterns and their specification.<br>
  66 -#      When application requests a particular pattern, haptic server checks this database for the specification of that pattern.<br>
  67 -#      After getting data from database, server sends these specific details to device driver which plays the pattern.<br>
  68 -#      Server can maintain multiple requests at a time on a priority basis.<br><br>
  69
  70 <h1 class="pg">Device Manager Funtions</h1>
  71 <h2 class="pg">Haptic Device Manager APIs</h2>
  72 <i><b>API : device_haptic_open</b></i>
  73 <br><b>Parameter In :</b> haptic_dev_idx dev_idx , unsigned int mode
  74 <br><b>Return :</b> int
  75 <br><b>Functionality :</b> This API opens a Haptic-vibration device. On success it returns a dev_handle value.
  76 In case of failure it returns a negative value. If the device is already open it returns (-1). <br>
  77 The first in parameter dev_idx should be from a predefined haptic-device-index which is available in the typedef enum haptic_dev_idx.
  78 The DEV_IDX_0 means first haptic-device-index of target , the DEV_IDX_1 means second haptic-device-index of target and the DEV_IDX_ALL means both of them.
  79 The availability of the dev_idx value is dependent on the real target. Normally, set a DEV_IDX_0 value to the first haptic-device.<br>
  80 The second in parameter mode is reserved for future so just set a 0 value<br>
  81 <b>Note:</b> The device_haptic_open() must be called before all other haptic APIs are called.
  82 The device_haptic_open() should have a matching call to device_haptic_close().
  83 Applications call the device_haptic_open() only once if possible during application startup and call the device_haptic_close() during application shutdown.
  84
  85 <b>Enumerate values:</b>
  86 @code
  87 //Haptic_dev_idx ;
  88 typedef enum haptic_dev_idx_t {
  89         DEV_IDX_0               =       0x01,
  90         DEV_IDX_1               =       0x02,
  91         DEV_IDX_ALL            =        0x04,
  92 };
  93 @endcode
  94
  95 <i><b>API : device_haptic_close</b></i>
  96 <br><b>Parameter In :</b> int dev_handle
  97 <br><b>Parameter Return :</b> int
  98 <br><b>Functionality :</b> This API closes a Haptic-vibration device. On success it returns a zero value.
  99 In case of failure it returns a negative value. If the device is already closed it returns (-1).  <br>
 100 The first in parameter dev_handle should be from the return value of device_haptic_open().
 101 <br><br>
 102 <i><b>API : device_haptic_play_pattern</b></i>
 103 <br><b>Parameter In :</b> int dev_handle , int pattern , int iteration , int feedback_level
 104 <br><b>Parameter Return :</b> int
 105 <br><b>Functionality :</b> This API plays a predefined rhythmic haptic-vibration pattern. <br>
 106 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 107 The second in parameter pattern should be from a predefined pattern list which is available in an enumeration (effectvibe_pattern_list).
 108 These patterns are rhythmic vibration patterns. <br>
 109 The third in parameter iteration sets the number of iterations to be played. This should be less than the maximum iteration range set for the device (currently its 255).  <br>
 110 The fourth in parameter is the vibration feedback intensity level. This level is already predefined by enumeration type value from HAPTIC _FEEDBACK_LEVEL_1
 111 to HAPTIC _FEEDBACK_LEVEL_5. If you want to use the value selected by the user in the Setting application menu, just set -1 value.<br>
 112 On success it returns a zero value. In case of failure it returns a negative value. <br>
 113 <b>Note:</b> The actual behavior of the feedback play pattern and the intensity depends on the target hardware.
 114
 115 <b>Enumerate values:</b>
 116 @code
 117 //Effectvibe_pattern_list
 118 enum effectvibe_pattern_list {
 119         EFFCTVIBE_TOUCH = 0,
 120         EFFCTVIBE_HW_TOUCH,
 121         EFFCTVIBE_NOTIFICATION,
 122         EFFCTVIBE_INCOMING_CALL01,
 123         EFFCTVIBE_INCOMING_CALL02,
 124         EFFCTVIBE_INCOMONG_CALL03,
 125         EFFCTVIBE_ALERTS_CALL,
 126         EFFCTVIBE_OPERATION,
 127         EFFCTVIBE_SILENT_MODE,
 128         EFFCTVIBE_PATTERN_END
 129 };
 130
 131 //Feedback Level ;
 132 enum {
 133         HAPTIC_FEEDBACK_LEVEL_AUTO = -1,
 134         HAPTIC_FEEDBACK_LEVEL_1 = 1,
 135         HAPTIC_FEEDBACK_LEVEL_2 = 2,
 136         HAPTIC_FEEDBACK_LEVEL_3 = 3,
 137         HAPTIC_FEEDBACK_LEVEL_4 = 4,
 138         HAPTIC_FEEDBACK_LEVEL_5 = 5,
 139 };
 140
 141 //definition for infinite iteration ;
 142 #define HAPTIC_INFINITE_ITERATION       256
 143 @endcode
 144
 145 <i><b>API : device_haptic_play_file</b></i>
 146 <br><b>Parameter In :</b> int dev_handle , const char *file_name , int iteration , int feedback_level
 147 <br><b>Parameter Return :</b> int
 148 <br><b>Functionality :</b>This API plays a predefined rhythmic haptic-vibration pattern file (only supports .ivt type file, Immersion VibeTonz).<br>
 149 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 150 The second in parameter file_name sets rhythmic vibration pattern file with path. It only supports .ivt type pattern file. <br>
 151 The third in parameter iteration sets the number of iterations to be played. This should be less than the maximum iteration range set for the device (currently its 255).
 152 If you want to play indefinitely, use HAPTIC_INFINITE_ITERATION defined value. But it depends on the target hardware.<br>
 153 The fourth in parameter is the vibration feedback intensity level. This level is already predefined by enumeration type value from HAPTIC _FEEDBACK_LEVEL_1
 154 to HAPTIC _FEEDBACK_LEVEL_5. If you want to use the value selected by the user in the Setting application menu, just set HAPTIC_FEEDBACK_LEVEL_AUTO value.
 155 (But the application must have a main loop to use the HAPTIC_FEEDBACK_LEVEL_AUTO value ) <br>
 156 On success it returns a zero value. In case of failure it returns a negative value. <br>
 157 <b>Note:</b> The actual behavior of the feedback play pattern and the intensity depends on the target hardware.
 158 <br><br>
 159 <i><b>API : device_haptic_play_monotone</b></i>
 160 <br><b>Parameter In :</b> int dev_handle ,  int duration
 161 <br><b>Parameter Return :</b> int
 162 <br><b>Functionality :</b>This API plays a monotonous haptic-vibration pattern with a constant intensity.
 163 In this monotone play, the intensity used is the value that the user has selected in the Setting application menu.<br>
 164 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 165 The second in parameter duration defines the length of time this vibration should be played. This duration is in milliseconds.  <br>
 166 On success it returns a zero value. In case of failure it returns a negative value. <br>
 167 <b>Note:</b> The actual behavior of the feedback played and the intensity depends on the target hardware.
 168 <br><br>
 169 <i><b>API : device_haptic_stop_play</b></i>
 170 <br><b>Parameter In :</b> int dev_handle
 171 <br><b>Parameter Return :</b> int
 172 <br><b>Functionality :</b> This API stops the current vibration being played.<br>
 173 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 174 On success it returns a zero value. In case of failure it returns a negative value.
 175 <br><br>
 176 <i><b>API : device_haptic_get_pattern_duration</b></i>
 177 <br><b>Parameter In :</b> int dev_handle ,  int pattern
 178 <br><b>Parameter Out :</b> int *duration
 179 <br><b>Parameter Return :</b> int
 180 <br><b>Functionality :</b>This API gets a duration time value from a predefined rhythmic vibration pattern.<br>
 181 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 182 The second in parameter pattern should be from a predefined pattern list which is available in an enumeration (effectvibe_pattern_list).<br>
 183 The application can get a duration time value from the third out parameter duration when this API succeeds. The unit of duration is ms (millisecond)<br>
 184 On success it returns a zero value. In case of failure it returns a negative value. <br>
 185 <b>Note:</b> The actual behavior of the feedback played and the intensity depends on the target hardware.
 186 <br><br>
 187 <i><b>API : device_haptic_get_file_duration</b></i>
 188 <br><b>Parameter In :</b> int dev_handle ,  const char *file_name
 189 <br><b>Parameter Out :</b> int *duration
 190 <br><b>Parameter Return :</b> int
 191 <br><b>Functionality :</b>This API gets a duration time value from a predefined rhythmic vibration pattern file (only supports .ivt type file).<br>
 192 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 193 The second in parameter file_name sets rhythmic vibration pattern file with path. It only supports .ivt type pattern file.<br>
 194 The application can get a duration time value from the third out parameter duration when this API succeeds. The unit of duration is ms (millisecond)<br>
 195 On success it returns a zero value. In case of failure it returns a negative value. <br>
 196 <b>Note:</b>The actual behavior of the feedback played and the intensity depends on the target hardware.<br>
 197
 198 <br><b>Sample Code <Simple program showing how to use haptic-vibration APIs></b>
 199 @code
 200 #include <stdio.h>
 201 #include <devman_haptic.h>
 202 #define HAPTIC_TEST_ITERATION 10
 203
 204 int main()
 205 {
 206         int ret_val=0;
 207         int dev_handle;
 208
 209         printf("\n Haptic vibration test : Start of the program \n");
 210
 211         //Open the haptic device
 212         dev_handle = device_haptic_open(DEV_IDX_0,0);
 213         if(dev_handle < 0)
 214                 return -1;
 215
 216         //Play a rhythmic pattern
 217         ret_val = device_haptic_play_pattern(dev_handle, EFFCTVIBE_NOTIFICATION,
 218                         HAPTIC_TEST_ITERATION , HAPTIC_FEEDBACK_LEVEL_3);
 219         if(ret_val !=0)
 220                 return -1;
 221
 222         //Play a monotone pattern for 1s == 1000ms
 223         ret_val = device_haptic_play_monotone(dev_handle, 1000);
 224         if(ret_val !=0)
 225                 return -1;
 226
 227         //Demo for a stop pattern API, playing a monotone for 10s
 228         ret_val = device_haptic_play_monotone(dev_handle, 10000);
 229         if(ret_val !=0)
 230                 return -1;
 231
 232         sleep(1);
 233
 234         //Stop the pattern immediately
 235         ret_val = device_haptic_stop_play(dev_handle);
 236         if(ret_val !=0)
 237                 return -1;
 238
 239         //Close the device
 240         ret_val = device_haptic_close(dev_handle);
 241         if(ret_val !=0)
 242                 return -1;
 243 }
 244 @endcode
 245
 246  @}
 247 **/