SLP_devman_PG.h

   1 /*
   2  *  devman
   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_PG_DEVMAN Device Manager
  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 Device Manager 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 Device Manager API usage.
  36
  37 <br>
  38 <h1 class="pg">Device Manager Library Overview</h1>
  39 <h2 class="pg">General Device Manager</h2>
  40 Device Manager library is provided to control the device and to get data about several devices. You can get the data about battery, charger, display and so on.<br>
  41 Devman library uses sysfs for interfaces with device drivers and kernel. sysfs is a virtual file system provided by Linux 2.6 or above. Please refer to the web site,
  42 http://www.kernel.org/pub/linux/kernel/people/mochel/doc/papers/ols-2005/mochel.pdf for more information about sysfs.
  43 The following figure shows the basic architecture of devman library
  44
  45 <h3 class="pg" align="center">Device Manager Architecture</h3>
  46 @image html SLP_devman_PG_architecture.png
  47 <br>
  48 <h2 class="pg">Haptic Device Manager</h2>
  49 <h3 class="pg" align="center">Haptic Vibration Functional Level Architecture</h3>
  50 @image html SLP_devman_PG_haptic_architecture.png
  51
  52 The client side is available in the form of a shared library to all the processes, whereas the server is a daemon.
  53 As shown in the diagram applications/middleware frameworks can have the haptic vibration client library in the process context.
  54 <br><br>
  55 The haptic vibration client is available in form of a shared library. This library has APIs which support various features.
  56 These features are playing a rhythmical vibration pattern, playing a monotonous vibration pattern, etc.
  57 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.
  58 <br><br>
  59 The server interacts with the device driver interfaces and generates vibration feedback.
  60 <br><br>
  61 <h3 class="pg">Haptic Vibration Features</h3>
  62 <b>Haptic client features</b>
  63 -#      Available in shared library form.<br>
  64 -#      Provides set of APIs to play haptic vibration patterns.<br>
  65 -#      Provide unique access control mechanism through client server architecture.<br>
  66 -#      Provision to play rhythmical vibration patterns.<br>
  67 -#      Provides functionality for application to play a different vibration pattern for a different event.<br>
  68 -#      Provides support for user defined duration for monotone playing or iteration for pattern playing.<br>
  69 -#      Provides immediate stop control over the vibrations played.<br><br>
  70
  71 <b>Haptic server features</b>
  72 -#      The actual implementation of the functionality supported by haptic-vibration library has been implemented through haptic-server.<br>
  73 -#      Haptic-server processes the vibration pattern's play/stop requests sent by application through the haptic client library.<br>
  74 -#      There is an internal database maintained for different patterns and their specification.<br>
  75 -#      When application requests a particular pattern, haptic server checks this database for the specification of that pattern.<br>
  76 -#      After getting data from database, server sends these specific details to device driver which plays the pattern.<br>
  77 -#      Server can maintain multiple requests at a time on a priority basis.<br><br>
  78
  79 <h1 class="pg">Device Manager Funtions</h1>
  80
  81 <h2 class="pg">General Device Manager APIs</h2>
  82 <i><b>API : device_get_battery_pct</b></i><br>
  83 <b>Parameter :</b> void<br>
  84 <b>Return :</b> int<br>
  85 <b>Functionality :</b> This API is used to get the remaining battery percentage. On success, integer value(0~100) that indicate remaining battery percentage is returned.
  86 Or a negative value (-1) is returned on failure.
  87 <br><br>
  88 <i><b>API : device_is_battery_full</b></i><br>
  89 <b>Parameter :</b> void<br>
  90 <b>Return :</b> int <br>
  91 <b>Functionality :</b> This API is used to get the fully charged status of battery. On fully charged, the integer value (1) is returned,
  92 (0) is returned if battery is not fully charged, a negative value (-1) is returned on failure.
  93 <br><br>
  94 <i><b>API : device_get_display_brt</b></i>
  95 <br><b>Parameter In :</b> display_num_t num
  96 <br><b>Return :</b> int
  97 <br><b>Functionality :</b> This API is used to get the current brightness of the display from sysfs.
  98 The function returns the current brightness value on success and a negative value (-1) on failure.
  99 <br><br>
 100 <b>Enumerate values:</b>
 101 @code
 102 // Display number
 103 typedef enum {
 104         DEV_DISPLAY_0,
 105         DEV_DISPLAY_1,
 106         DEV_MAIN_DISPLAY        = DEV_DISPLAY_0,
 107 } display_num_t;
 108 @endcode
 109
 110 <i><b>API : device_set_display_brt</b></i>
 111 <br><b>Parameter In :</b> display_num_t num
 112 <br><b>Parameter In :</b> int val
 113 <br><b>Return :</b> int
 114 <br><b>Functionality :</b> This API is used to set the current brightness of the display using sysfs.
 115 The parameter val should be set as a brightnesss value of your target.
 116 The function returns the current brightness value on success and a negative value (-1) on failure.
 117 <br><br>
 118 <i><b>API : device_get_display_gamma</b></i>
 119 <br></b>Parameter In :</b> display_num_t num
 120 <br><b>Return :</b> int
 121 <br><b>Functionality :</b> This API is used to get the current gamma value of the display from sysfs.
 122 The function returns the current brightness value on success and a negative value (-1) on failure.
 123 <br><br>
 124 <i><b>API : device_set_display_brt</b></i>
 125 <br><b>Parameter In :</b> display_num_t num
 126 <br><b>Parameter In :</b> int val
 127 <br><b>Return :</b> int
 128 <br><b>Functionality :</b> This API is used to set the current brightness of the display using sysfs.
 129 The parameter val should be set as a brightnesss value of your target.
 130 The function returns the current brightness value on success and a negative value (-1) on failure.
 131 <br><br>
 132 <i><b>API : device_get_display_gamma</b></i>
 133 <br><b>Parameter In :</b> display_num_t num
 134 <br><b>Return :</b> int
 135 <br><b>Functionality :</b> This API is used to get the current gamma value of the display from sysfs.
 136 The function returns the current brightness value on success and a negative value (-1) on failure.
 137 <b>Enumerate values:</b>
 138 @code
 139 // LCD gamma values
 140 typedef enum {
 141         LCD_GAMMA_22 = 1,            // 8500K , 2.2 GAMMA
 142         LCD_GAMMA_19 = 2,            // 8500K , 1.9 GAMMA
 143         LCD_GAMMA_17 = 3,            // 8500K , 1.7 GAMMA
 144         LCD_GAMMA_NORMAL =      LCD_GAMMA_22, // Normal screen
 145         LCD_GAMMA_PLAY_RECORD = LCD_GAMMA_19, // Playing or recording cam
 146         LCD_GAMMA_PREVIEW =     LCD_GAMMA_17, // Preview
 147         LCD_GAMMA_MOVIE =       LCD_GAMMA_19, // Movie
 148         LCD_GAMMA_CAMERA =      11,               // Camera
 149 } display_gamma_t;
 150 @endcode
 151
 152 <i><b>API : device_power_suspend</b></i>
 153 <br><b>Parameter :</b> void
 154 <br><b>Return :</b> int
 155 <br><b>Functionality :</b> This API is used to make the phone go to a suspend (sleep) state.
 156 The suspend state consumes little battery power. If the caller process does not have the permission which is root, it returns failure.
 157 The function returns 0 on success and a negative value (-1) on failure.
 158 <br><br>
 159 <i><b>API : device_get_property</b></i>
 160 <br><b>Parameter In :</b> devtype_t devtype
 161 <br><b>Parameter In :</b> int property
 162 <br><b>Parameter Out :</b>  int *value
 163 <br><b>Return :</b> int
 164 <br><b>Functionality :</b>This generic API is used to get the property values of supported devices.
 165 If the caller process does not have permission, it returns failure.
 166 The function returns 0 on success and a negative value (-1) on failure.
 167 <br><br>
 168 <i><b>API : device_set_property</b></i>
 169 <br><b>Parameter In :</b> devtype_t devtype
 170 <br><b>Parameter In :</b> int property
 171 <br><b>Parameter In :</b> int value
 172 <br><b>Return :</b> int
 173 <br><b>Functionality :</b>This generic API is used to set the property values of supported devices.
 174 If the caller process does not have permission, it returns failure.
 175 The function returns 0 on success and a negative value (-1) on failure.
 176
 177 <h2 class="pg">Haptic Device Manager APIs</h2>
 178 <i><b>API : device_haptic_open</b></i>
 179 <br><b>Parameter In :</b> haptic_dev_idx dev_idx , unsigned int mode
 180 <br><b>Return :</b> int
 181 <br><b>Functionality :</b> This API opens a Haptic-vibration device. On success it returns a dev_handle value.
 182 In case of failure it returns a negative value. If the device is already open it returns (-1). <br>
 183 The first in parameter dev_idx should be from a predefined haptic-device-index which is available in the typedef enum haptic_dev_idx.
 184 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.
 185 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>
 186 The second in parameter mode is reserved for future so just set a 0 value<br>
 187 <b>Note:</b> The device_haptic_open() must be called before all other haptic APIs are called.
 188 The device_haptic_open() should have a matching call to device_haptic_close().
 189 Applications call the device_haptic_open() only once if possible during application startup and call the device_haptic_close() during application shutdown.
 190
 191 <b>Enumerate values:</b>
 192 @code
 193 //Haptic_dev_idx ;
 194 typedef enum haptic_dev_idx_t {
 195         DEV_IDX_0               =       0x01,
 196         DEV_IDX_1               =       0x02,
 197         DEV_IDX_ALL            =        0x04,
 198 };
 199 @endcode
 200
 201 <i><b>API : device_haptic_close</b></i>
 202 <br><b>Parameter In :</b> int dev_handle
 203 <br><b>Parameter Return :</b> int
 204 <br><b>Functionality :</b> This API closes a Haptic-vibration device. On success it returns a zero value.
 205 In case of failure it returns a negative value. If the device is already closed it returns (-1).  <br>
 206 The first in parameter dev_handle should be from the return value of device_haptic_open().
 207 <br><br>
 208 <i><b>API : device_haptic_play_pattern</b></i>
 209 <br><b>Parameter In :</b> int dev_handle , int pattern , int iteration , int feedback_level
 210 <br><b>Parameter Return :</b> int
 211 <br><b>Functionality :</b> This API plays a predefined rhythmic haptic-vibration pattern. <br>
 212 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 213 The second in parameter pattern should be from a predefined pattern list which is available in an enumeration (effectvibe_pattern_list).
 214 These patterns are rhythmic vibration patterns. <br>
 215 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>
 216 The fourth in parameter is the vibration feedback intensity level. This level is already predefined by enumeration type value from HAPTIC _FEEDBACK_LEVEL_1
 217 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>
 218 On success it returns a zero value. In case of failure it returns a negative value. <br>
 219 <b>Note:</b> The actual behavior of the feedback play pattern and the intensity depends on the target hardware.
 220
 221 <b>Enumerate values:</b>
 222 @code
 223 //Effectvibe_pattern_list
 224 enum effectvibe_pattern_list {
 225         EFFCTVIBE_TOUCH = 0,
 226         EFFCTVIBE_HW_TOUCH,
 227         EFFCTVIBE_NOTIFICATION,
 228         EFFCTVIBE_INCOMING_CALL01,
 229         EFFCTVIBE_INCOMING_CALL02,
 230         EFFCTVIBE_INCOMONG_CALL03,
 231         EFFCTVIBE_ALERTS_CALL,
 232         EFFCTVIBE_OPERATION,
 233         EFFCTVIBE_SILENT_MODE,
 234         EFFCTVIBE_PATTERN_END
 235 };
 236
 237 //Feedback Level ;
 238 enum {
 239         HAPTIC_FEEDBACK_LEVEL_AUTO = -1,
 240         HAPTIC_FEEDBACK_LEVEL_1 = 1,
 241         HAPTIC_FEEDBACK_LEVEL_2 = 2,
 242         HAPTIC_FEEDBACK_LEVEL_3 = 3,
 243         HAPTIC_FEEDBACK_LEVEL_4 = 4,
 244         HAPTIC_FEEDBACK_LEVEL_5 = 5,
 245 };
 246
 247 //definition for infinite iteration ;
 248 #define HAPTIC_INFINITE_ITERATION       256
 249 @endcode
 250
 251 <i><b>API : device_haptic_play_file</b></i>
 252 <br><b>Parameter In :</b> int dev_handle , const char *file_name , int iteration , int feedback_level
 253 <br><b>Parameter Return :</b> int
 254 <br><b>Functionality :</b>This API plays a predefined rhythmic haptic-vibration pattern file (only supports .ivt type file, Immersion VibeTonz).<br>
 255 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 256 The second in parameter file_name sets rhythmic vibration pattern file with path. It only supports .ivt type pattern file. <br>
 257 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).
 258 If you want to play indefinitely, use HAPTIC_INFINITE_ITERATION defined value. But it depends on the target hardware.<br>
 259 The fourth in parameter is the vibration feedback intensity level. This level is already predefined by enumeration type value from HAPTIC _FEEDBACK_LEVEL_1
 260 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.
 261 (But the application must have a main loop to use the HAPTIC_FEEDBACK_LEVEL_AUTO value ) <br>
 262 On success it returns a zero value. In case of failure it returns a negative value. <br>
 263 <b>Note:</b> The actual behavior of the feedback play pattern and the intensity depends on the target hardware.
 264 <br><br>
 265 <i><b>API : device_haptic_play_monotone</b></i>
 266 <br><b>Parameter In :</b> int dev_handle ,  int duration
 267 <br><b>Parameter Return :</b> int
 268 <br><b>Functionality :</b>This API plays a monotonous haptic-vibration pattern with a constant intensity.
 269 In this monotone play, the intensity used is the value that the user has selected in the Setting application menu.<br>
 270 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 271 The second in parameter duration defines the length of time this vibration should be played. This duration is in milliseconds.  <br>
 272 On success it returns a zero value. In case of failure it returns a negative value. <br>
 273 <b>Note:</b> The actual behavior of the feedback played and the intensity depends on the target hardware.
 274 <br><br>
 275 <i><b>API : device_haptic_stop_play</b></i>
 276 <br><b>Parameter In :</b> int dev_handle
 277 <br><b>Parameter Return :</b> int
 278 <br><b>Functionality :</b> This API stops the current vibration being played.<br>
 279 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 280 On success it returns a zero value. In case of failure it returns a negative value.
 281 <br><br>
 282 <i><b>API : device_haptic_get_pattern_duration</b></i>
 283 <br><b>Parameter In :</b> int dev_handle ,  int pattern
 284 <br><b>Parameter Out :</b> int *duration
 285 <br><b>Parameter Return :</b> int
 286 <br><b>Functionality :</b>This API gets a duration time value from a predefined rhythmic vibration pattern.<br>
 287 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 288 The second in parameter pattern should be from a predefined pattern list which is available in an enumeration (effectvibe_pattern_list).<br>
 289 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>
 290 On success it returns a zero value. In case of failure it returns a negative value. <br>
 291 <b>Note:</b> The actual behavior of the feedback played and the intensity depends on the target hardware.
 292 <br><br>
 293 <i><b>API : device_haptic_get_file_duration</b></i>
 294 <br><b>Parameter In :</b> int dev_handle ,  const char *file_name
 295 <br><b>Parameter Out :</b> int *duration
 296 <br><b>Parameter Return :</b> int
 297 <br><b>Functionality :</b>This API gets a duration time value from a predefined rhythmic vibration pattern file (only supports .ivt type file).<br>
 298 The first in parameter dev_handle should be from the return value of device_haptic_open().<br>
 299 The second in parameter file_name sets rhythmic vibration pattern file with path. It only supports .ivt type pattern file.<br>
 300 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>
 301 On success it returns a zero value. In case of failure it returns a negative value. <br>
 302 <b>Note:</b>The actual behavior of the feedback played and the intensity depends on the target hardware.<br>
 303
 304 <br><b>Sample Code <Simple program showing how to use haptic-vibration APIs></b>
 305 @code
 306 #include <stdio.h>
 307 #include <devman_haptic.h>
 308 #define HAPTIC_TEST_ITERATION 10
 309
 310 int main()
 311 {
 312         int ret_val=0;
 313         int dev_handle;
 314
 315         printf("\n Haptic vibration test : Start of the program \n");
 316
 317         //Open the haptic device
 318         dev_handle = device_haptic_open(DEV_IDX_0,0);
 319         if(dev_handle < 0)
 320                 return -1;
 321
 322         //Play a rhythmic pattern
 323         ret_val = device_haptic_play_pattern(dev_handle, EFFCTVIBE_NOTIFICATION,
 324                         HAPTIC_TEST_ITERATION , HAPTIC_FEEDBACK_LEVEL_3);
 325         if(ret_val !=0)
 326                 return -1;
 327
 328         //Play a monotone pattern for 1s == 1000ms
 329         ret_val = device_haptic_play_monotone(dev_handle, 1000);
 330         if(ret_val !=0)
 331                 return -1;
 332
 333         //Demo for a stop pattern API, playing a monotone for 10s
 334         ret_val = device_haptic_play_monotone(dev_handle, 10000);
 335         if(ret_val !=0)
 336                 return -1;
 337
 338         sleep(1);
 339
 340         //Stop the pattern immediately
 341         ret_val = device_haptic_stop_play(dev_handle);
 342         if(ret_val !=0)
 343                 return -1;
 344
 345         //Close the device
 346         ret_val = device_haptic_close(dev_handle);
 347         if(ret_val !=0)
 348                 return -1;
 349 }
 350 @endcode
 351
 352  @}
 353 **/