devman_haptic_ext.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 #ifndef __DEVMAN_HAPTIC_EXT_H__
  24 #define __DEVMAN_HAPTIC_EXT_H__
  25
  26 #include "devman_haptic_ext_core.h"
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /**
  33  * @file        devman_haptic_ext.h
  34  * @ingroup     DEVICE_MANAGER
  35  * @brief       This file contains the prototypes of the haptic extended API
  36  * @author      SLP2.0
  37  * @date        2010-01-24
  38  * @version     0.1
  39  */
  40
  41 /**
  42  * @addtogroup DEVICE_MANAGER
  43  * @{
  44  */
  45
  46 /**
  47  * @fn int device_haptic_get_device_state(int device_index, int *state)
  48  * @par Description:
  49  *      This API gets the status bits of an available device that is supported by the TouchSense Player API.\n
  50  * @param[in] dev_idx set a device index (predefined enum value by haptic_dev_idx)
  51  * @param[out] state is a pointer to the variable that will receive the status bits of the device
  52  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
  53  * @par Example:
  54  * @code
  55  *      ...
  56  *      int status;
  57  *      int state
  58  *
  59  *      //Get the haptic device state
  60  *      status = device_haptic_get_device_state(DEV_IDX_0, &state);
  61  *      if(status < 0)
  62  *              return -1;
  63  *      ...
  64  * @endcode
  65  */
  66
  67         int device_haptic_get_device_state(int device_index, int *state);
  68
  69 /**
  70  * @fn int device_haptic_get_device_capability_bool(int device_index, int device_cap_type, unsigned char *device_cap_value)
  71  * @par Description:
  72  *      This API gets a Boolean capability of an available device that is supported by the TouchSense Player API.\n
  73  * @param[in] device_index set a device index (predefined enum value by haptic_dev_idx)
  74  * @param[in] device_cap_type set capability type of the Boolean capability to get
  75  * @param[out] device_cap_value is a pointer to the variable that will receive the requested Boolean capability value of the device
  76  * @return if it succeed, it return HAPTIC_S_SUCCESS , otherwise negative value return
  77  * @see device_haptic_close()
  78  * @par Example:
  79  * @code
  80  *      ...
  81  *      int status;
  82  *      unsigned char device_cap_value;
  83  *
  84  *      //Get haptic device capability
  85  *      status = device_haptic_get_device_capability_bool(DEV_IDX_0, NOT_AVAILABLE_CAPABILITY, &device_cap_value);
  86  *      if(status < 0)
  87  *              return -1;
  88  *      ...
  89  * @endcode
  90  */
  91
  92         int device_haptic_get_device_capability_bool(int device_index, int device_cap_type, unsigned char *device_cap_value);
  93
  94 /**
  95  * @fn int device_haptic_get_device_capability_int32(int device_index, int device_cap_type, int *device_cap_value)
  96  * @par Description:
  97  *      This API gets a 32-bit integer capability of an available device that is supported by the TouchSense Player API.\n
  98  * @param[in] device_index set a device index (predefined enum value by haptic_dev_idx)
  99  * @param[in] device_cap_type set Capability type of the Boolean capability to get
 100  * @param[out] device_cap_value is a pointer to the variable that will receive the requested 32-bit integer capability value of the device
 101  * @return if it succeed, it return HAPTIC_S_SUCCESS , otherwise negative value return
 102  * @see device_haptic_close()
 103  * @par Example:
 104  * @code
 105  *      ...
 106  *      int status;
 107  *      int device_cap_value;
 108  *
 109  *      //Get haptic device capability
 110  *      status = device_haptic_get_device_capability_int32(DEV_IDX_0, HAPTIC_DEVCAPTYPE_ACTUATOR_TYPE, &device_cap_value);
 111  *      if(status < 0)
 112  *              return -1;
 113  *      ...
 114  * @endcode
 115  */
 116
 117         int device_haptic_get_device_capability_int32(int device_index, int device_cap_type, int *device_cap_value);
 118
 119 /**
 120  * @fn int device_haptic_get_device_capability_string(int device_index, int device_cap_type, int size, char *device_cap_value)
 121  * @par Description:
 122  *      This API gets a string capability of an available device that is supported by the TouchSense Player API.\n
 123  * @param[in] device_index set a device index (predefined enum value by haptic_dev_idx)
 124  * @param[in] device_cap_type set Capability type of the Boolean capability to get
 125  * @param[out] device_cap_value is a pointer to the variable that will receive the requested 32-bit integer capability value of the device
 126  * @return if it succeed, it return HAPTIC_S_SUCCESS , otherwise negative value return
 127  * @see device_haptic_close()
 128  * @par Example:
 129  * @code
 130  *      ...
 131  *      int status;
 132  *      int size = 1024;
 133  *      char device_cap_value[size];
 134  *
 135  *      //Get haptic device capability
 136  *      status = device_haptic_get_device_capability_string(DEV_IDX_0, HAPTIC_DEVCAPTYPE_DEVICE_NAME, size, device_cap_value);
 137  *      if(status < 0)
 138  *              return -1;
 139  *      ...
 140  * @endcode
 141  */
 142
 143         int device_haptic_get_device_capability_string(int device_index, int device_cap_type, int size, char *device_cap_value);
 144
 145 /**
 146  * @fn int device_haptic_get_device_property_bool(int device_handle, int device_prop_type, unsigned char *device_prop_value)
 147  * @par Description:
 148  *      This API gets a Boolean property of an open device.\n
 149  * @param[in] device_handle is a handle to the device for which to get a Boolean property
 150  * @param[in] device_prop_type set property type of the Boolean property to get
 151  * @param[out] device_prop_value is a pointer to the variable that will receive the requested Boolean property value of the device
 152  * @return if it succeed, it return HAPTIC_S_SUCCESS , otherwise negative value return
 153  * @see device_haptic_close()
 154  * @par Example:
 155  * @code
 156  *      ...
 157  *      int status;
 158  *      int device_handle;
 159  *      unsigned char device_prop_value;
 160  *
 161  *      device_handle = device_haptic_open_device(DEV_IDX0, 0);
 162  *      ...
 163  *
 164  *      //Get haptic device property
 165  *      status = device_haptic_get_device_property_bool(device_handle, HAPTIC_DEVPROPTYPE_DISABLE_EFFECTS, &device_prop_value);
 166  *      if(status < 0)
 167  *              return -1;
 168  *      ...
 169  * @endcode
 170  */
 171
 172         int device_haptic_get_device_property_bool(int device_handle, int device_prop_type, unsigned char *device_prop_value);
 173
 174 /**
 175  * @fn int device_haptic_set_device_property_bool(int device_handle, int device_prop_type, unsigned char device_prop_value)
 176  * @par Description:
 177  *      This API sets a Boolean property of an open device.\n
 178  * @param[in] device_handle is a handle to the device for which to set a Boolean property
 179  * @param[in] device_prop_type set property type of the Boolean property to set
 180  * @param[in] device_prop_value is a value of the Boolean property to set
 181  * @return if it succeed, it return HAPTIC_S_SUCCESS , otherwise negative value return
 182  * @see device_haptic_close()
 183  * @par Example:
 184  * @code
 185  *      ...
 186  *      int status;
 187  *      int device_handle;
 188  *      unsigned char device_prop_value = HAPTIC_FALSE;
 189  *
 190  *      device_handle = device_haptic_open_device(DEV_IDX0, 0);
 191  *      ...
 192  *
 193  *      //Get haptic device property
 194  *      status = device_haptic_set_device_property_bool(device_handle, HAPTIC_DEVPROPTYPE_DISABLE_EFFECTS, device_prop_value);
 195  *      if(status < 0)
 196  *              return -1;
 197  *      ...
 198  * @endcode
 199  */
 200
 201         int device_haptic_set_device_property_bool(int device_handle, int device_prop_type, unsigned char device_prop_value);
 202
 203 /**
 204  * @fn int device_haptic_get_device_property_int32(int device_handle, int device_prop_type, int *device_prop_value)
 205  * @par Description:
 206  *      This API gets a 32-bit integer property of an open device.\n
 207  * @param[in] device_handle is a handle to the device for which to get a 32-bit integer property
 208  * @param[in] device_prop_type set property type of the Boolean property to get
 209  * @param[in] device_prop_value is a pointer to the variable that will receive the requested 32-bit integer property value of the device
 210  * @return if it succeed, it return HAPTIC_S_SUCCESS , otherwise negative value return
 211  * @see device_haptic_close()
 212  * @par Example:
 213  * @code
 214  *      ...
 215  *      int status;
 216  *      int device_handle;
 217  *      int device_prop_value;
 218  *
 219  *      device_handle = device_haptic_open_device(DEV_IDX0, 0);
 220  *      ...
 221  *
 222  *      //Get haptic device property
 223  *      status = device_haptic_get_device_property_int32(device_handle, HAPTIC_DEVPROPTYPE_STRENGTH, &device_prop_value);
 224  *      if(status < 0)
 225  *              return -1;
 226  *      ...
 227  * @endcode
 228  */
 229
 230         int device_haptic_get_device_property_int32(int device_handle, int device_prop_type, int *device_prop_value);
 231
 232 /**
 233  * @fn int device_haptic_set_device_property_int32(int device_handle, int device_prop_type, int device_prop_value)
 234  * @par Description:
 235  *      This API sets a 32-bit integer property of an open device.\n
 236  * @param[in] device_handle is a handle to the device for which to set a 32-bit integer property
 237  * @param[in] device_prop_type set property type of the Boolean property to set
 238  * @param[in] device_prop_value is a value of the 32-bit integer property to set.
 239  * @return if it succeed, it return HAPTIC_S_SUCCESS , otherwise negative value return
 240  * @see device_haptic_close()
 241  * @par Example:
 242  * @code
 243  *      ...
 244  *      int status;
 245  *      int device_handle;
 246  *      int device_prop_value = 5000;
 247  *
 248  *      device_handle = device_haptic_open_device(DEV_IDX0, 0);
 249  *      ...
 250  *
 251  *      //Get haptic device property
 252  *      status = device_haptic_get_device_property_int32(device_handle, HAPTIC_DEVPROPTYPE_STRENGTH, device_prop_value);
 253  *      if(status < 0)
 254  *              return -1;
 255  *      ...
 256  * @endcode
 257  */
 258
 259         int device_haptic_set_device_property_int32(int device_handle, int device_prop_type, int device_prop_value);
 260
 261 /**
 262  * @fn int device_haptic_get_device_property_string(int device_handle, int device_prop_type, int size, char *device_prop_value)
 263  * @par Description:
 264  *      This API gets a string property of an open device.\n
 265  * @param[in] device_handle is a handle to the device for which to get a string property
 266  * @param[in] device_prop_type set property type of the string property to get
 267  * @param[in] size is a size of the buffer, in bytes, pointed to by the device_prop_value parameter.
 268  * @param[out] device_prop_value is a pointer to the variable that will receive the requested string property value of the device
 269  * @return if it succeed, it return HAPTIC_S_SUCCESS , otherwise negative value return
 270  * @see device_haptic_close()
 271  * @par Example:
 272  * @code
 273  *      ...
 274  *      int status;
 275  *      int device_handle;
 276  *      int size = 1024;
 277  *      char device_prop_value[size];
 278  *
 279  *      device_handle = device_haptic_open_device(DEV_IDX0, 0);
 280  *      ...
 281  *
 282  *      //Get haptic device property
 283  *      status = device_haptic_get_device_property_string(device_handle, HAPTIC_DEVPROPTYPE_STRENGTH, size, device_prop_value);
 284  *      if(status < 0)
 285  *              return -1;
 286  *      ...
 287  * @endcode
 288  */
 289
 290         int device_haptic_get_device_property_string(int device_handle, int device_prop_type, int size, char *device_prop_value);
 291
 292 /**
 293  * @fn int device_haptic_set_device_property_string(int device_handle, int device_prop_type, char *device_prop_value)
 294  * @par Description:
 295  *      This API sets a string property of an open device.\n
 296  * @param[in] device_handle is a handle to the device for which to get a string property
 297  * @param[in] device_prop_type set property type of the string property to set
 298  * @param[in] device_prop_value pointer to the character buffer containing the string property value to set.
 299  * @return if it succeed, it return HAPTIC_S_SUCCESS , otherwise negative value return
 300  * @see device_haptic_close()
 301  * @par Example:
 302  * @code
 303  *      ...
 304  *      int status;
 305  *      int device_handle;
 306  *      char *device_prop_value = "DMZI13021KAIA112123";
 307  *
 308  *      device_handle = device_haptic_open_device(DEV_IDX0, 0);
 309  *      ...
 310  *
 311  *      //Get haptic device property
 312  *      status = device_haptic_set_device_property_string(device_handle, HAPTIC_DEVPROPTYPE_LICENSE_KEY, device_prop_value);
 313  *      if(status < 0)
 314  *              return -1;
 315  *      ...
 316  * @endcode
 317  */
 318
 319         int device_haptic_set_device_property_string(int device_handle, int device_prop_type, const char *device_prop_value);
 320
 321 /**
 322  * @fn int device_haptic_get_effect_count(const unsigned char *ivt_buffer)
 323  * @par Description:
 324  *      This API gets number of effects defined in IVT data.\n
 325  * @param[in] ivt_buffer is a pointer to IVT data
 326  * @return if it succeed, it returns number of effects defined in the specified IVT data, otherwise negative value return
 327  * @par Example:
 328  * @code
 329  *      ...
 330  *      int effect_count;
 331  *      unsigned char ivt_buffer = { .... };
 332  *
 333  *      //Open the haptic device
 334  *      effect_count = device_haptic_get_effect_count(ivt_buffer);
 335  *      if(effect_count < 0)
 336  *              return -1;
 337  *      ...
 338  * @endcode
 339  */
 340
 341         int device_haptic_get_effect_count(const unsigned char *ivt_buffer);
 342
 343 /**
 344  * @fn int device_haptic_get_effect_name(const unsigned char *ivt_buffer, int effect_index, int size, char *effect_name)
 345  * @par Description:
 346  *      This API Gets the name of an effect defined in IVT data.\n
 347  * @param[in] ivt_buffer is a pointer to IVT data containing the effect for which to get the name
 348  * @param[in] effect_index is index of the effect for which to get the name
 349  * @param[in] size is a size of the buffer, in bytes, pointed by the effect_name parameter
 350  * @param[out] effect_name is a pointer to the character buffer that will receive the name of the effect
 351  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 352  * @par Example:
 353  * @code
 354  *      ...
 355  *      int status;
 356  *      unsigned char *ivt_buffer = { ... };
 357  *      int size = 1024;
 358  *      char effect_name[size];
 359  *
 360  *      //Get IVT effect duration
 361  *      status = device_haptic_get_effect_name(ivt_buffer, 0, size, effect_name);
 362  *      if(staus < 0)
 363  *              return -1;
 364  *      ...
 365  * @endcode
 366  */
 367
 368         int device_haptic_get_effect_name(const unsigned char *ivt_buffer, int effect_index, int size, char *effect_name);
 369
 370 /**
 371  * @fn int device_haptic_get_effect_name_u(const unsigned char *ivt_buffer, int effect_index, int size, unsigned short *effect_name)
 372  * @par Description:
 373  *      This API gets the name of an effect defined in IVT data as a string of VibeWChar in UCS-2 format.\n
 374  * @param[in] ivt_buffer is a pointer to IVT data containing the effect for which to get the name
 375  * @param[in] effect_index is index of the effect for which to get the name
 376  * @param[in] size is a size of the buffer, in bytes, pointed by the effect_name parameter
 377  * @param[out] effect_name is a pointer to the unsigned short buffer that will receive the name of the effect
 378  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 379  * @par Example:
 380  * @code
 381  *      ...
 382  *      int status;
 383  *      unsigned char *ivt_buffer = { ... };
 384  *      int size = 1024;
 385  *      unsigned short effect_name[size];
 386  *
 387  *      //Get IVT effect duration
 388  *      status = device_haptic_get_effect_name_u(ivt_buffer, 0, size, effect_name);
 389  *      if(staus < 0)
 390  *              return -1;
 391  *      ...
 392  * @endcode
 393  */
 394
 395         int device_haptic_get_effect_name_u(const unsigned char *ivt_buffer, int effect_index, int size, unsigned short *effect_name);
 396
 397 /**
 398  * @fn int device_haptic_get_effect_index_from_name(const unsigned char *ivt_buffer, const char *effect_name, int *effect_index)
 399  * @par Description:
 400  *      This API gets the index of an effect defined in IVT data given the name of the effect.\n
 401  * @param[in] ivt_buffer is a pointer to IVT data
 402  * @param[in] effect_name is pointer to the character buffer containing the name of the effect for which to get the index
 403  * @param[out] effect_index is a pointer to the variable that will receive the index of the effect
 404  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 405  * @par Example:
 406  * @code
 407  *      ...
 408  *      int status;
 409  *      unsigned char *ivt_buffer = { ... };
 410  *      int effect_index;
 411  *      char *effect_name = "PERIODIC_EFFECT";
 412  *
 413  *      //Get IVT effect duration
 414  *      status = device_haptic_get_effect_index_from_name(ivt_buffer, effect_name, &effect_index);
 415  *      if(staus < 0)
 416  *              return -1;
 417  *      ...
 418  * @endcode
 419  */
 420
 421         int device_haptic_get_effect_index_from_name(const unsigned char *ivt_buffer, const char *effect_name, int *effect_index);
 422
 423 /**
 424  * @fn int device_haptic_get_effect_index_from_name_u(const unsigned char *ivt_buffer, const unsigned short *effect_name, int *effect_index)
 425  * @par Description:
 426  *      This API Gets the index of an effect defined in IVT data given the name of the effect as a string of VibeWChar in UCS-2 format.\n
 427  * @param[in] ivt_buffer is a pointer to IVT data
 428  * @param[in] effect_name is a pointer to the unsigned short buffer containing the UCS-2 formatted name of the effect for which to get the index
 429  * @param[out] effect_index is a pointer to the variable that will receive the index of the effect
 430  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 431  * @par Example:
 432  * @code
 433  *      ...
 434  *      int status;
 435  *      unsigned char *ivt_buffer = { ... };
 436  *      int effect_index;
 437  *      unsigned short *effect_name = "PERIODIC_EFFECT";
 438  *
 439  *      //Get IVT effect duration
 440  *      status = device_haptic_get_effect_index_from_name_u(ivt_buffer, effect_name, &effect_index);
 441  *      if(staus < 0)
 442  *              return -1;
 443  *      ...
 444  * @endcode
 445  */
 446
 447         int device_haptic_get_effect_index_from_name_u(const unsigned char *ivt_buffer, const unsigned short *effect_name, int *effect_index);
 448
 449 /**
 450  * @fn int device_haptic_play_effect(int device_handle, const unsigned char *ivt_buffer, int effect_index, int *effect_handle)
 451  * @par Description:
 452  *      This API Pauses a playing effect.\n
 453  * @param[in] device_handle is a handle to the device associated to the effect
 454  * @param[in] ivt_buffer is a pointer to IVT data containing the definition of the effect to play
 455  * @param[in] effect_index is an index of the effect to play
 456  * @param[out] effect_handle is a pointer to the handle to the variable that will receive a handle to the playing effect
 457  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 458  * @see device_haptic_close()
 459  * @par Example:
 460  * @code
 461  *      ...
 462  *      int status;
 463  *      int effect_handle;
 464  *
 465  *      status = device_haptic_play_effect(device_handle, ivt_buffer, 0, &effect_handle);
 466  *      if (status < 0) {
 467  *              return status;
 468  *      }
 469  *      ...
 470  * @endcode
 471  */
 472
 473         int device_haptic_play_effect(int device_handle, const unsigned char *ivt_buffer, int effect_index, int *effect_handle);
 474
 475 /**
 476  * @fn int device_haptic_play_effect_repeat(int device_handle, const unsigned char *ivt_buffer, int effect_index, unsigned char repeat, int *effect_handle)
 477  * @par Description:
 478  *      This API Pauses a playing effect.\n
 479  * @param[in] device_handle is a handle to the device associated to the effect
 480  * @param[in] ivt_buffer is a pointer to IVT data containing the definition of the effect to play
 481  * @param[in] effect_index is an index of the effect to play
 482  * @param[in] repeat is a number of time to repeat the effect
 483  * @param[out] effect_handle is a pointer to the handle to the variable that will receive a handle to the playing effect
 484  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 485  * @see device_haptic_close()
 486  * @par Example:
 487  * @code
 488  *      ...
 489  *      int status;
 490  *      int effect_handle;
 491  *
 492  *      status = device_haptic_play_effect_repeat(device_handle, ivt_buffer, 0, 3, &effect_handle);
 493  *      if (status < 0) {
 494  *              return status;
 495  *      }
 496  *      ...
 497  * @endcode
 498  */
 499
 500         int device_haptic_play_effect_repeat(int device_handle, const unsigned char *ivt_buffer, int effect_index, unsigned char repeat, int *effect_handle);
 501
 502 /**
 503  * @fn int device_haptic_stop_playing_effects(int device_handle, int effect_handle)
 504  * @par Description:
 505  *      This API stops playing effect.\n
 506  * @param[in] device_handle is a handle to the device on which to stop the playing effect
 507  * @param[in] effect_handle is a handle to the playing effect to stop
 508  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 509  * @par Example:
 510  * @code
 511  *      ...
 512  *      int status;
 513  *
 514  *      status = device_haptic_stop_playing_effects(device_handle, effect_handle);
 515  *      if(status < 0)
 516  *              return -1;
 517  *      ...
 518  * @endcode
 519  */
 520
 521         int device_haptic_stop_playing_effect(int device_handle, int effect_handle);
 522
 523 /**
 524  * @fn int device_haptic_get_effect_type(const unsigned char *ivt_buffer, int effect_index, int *effect_type)
 525  * @par Description:
 526  *      This API gets the type of an effect defined in IVT data.\n
 527  * @param[in] ivt_buffer is a pointer to IVT data containing the effect for which to get the type
 528  * @param[in] effect_index is index of the effect for which to get the type
 529  * @param[out] effect_type is a pointer to the variable that will receive the type of the effect
 530  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 531  * @par Example:
 532  * @code
 533  *      ...
 534  *      int status;
 535  *      unsigned char *ivt_buffer = { ... };
 536  *      int effect_type;
 537  *
 538  *      //Get IVT effect type
 539  *      status = device_haptic_get_effect_type(ivt_buffer, 0, &effect_type);
 540  *      if(staus < 0)
 541  *              return -1;
 542  *      ...
 543  * @endcode
 544  */
 545
 546         int device_haptic_get_effect_type(const unsigned char *ivt_buffer, int effect_index, int *effect_type);
 547
 548 /**
 549  * @fn int device_haptic_get_magsweep_effect_definition(const unsigned char *ivt_buffer, int effect_index, int *duration, int *magnitude, int *style, int *attacktime, int *attacklevel, int *fadetime, int *fadelevel);
 550  * @par Description:
 551  *      This API gets the parameters of a MagSweep effect defined in IVT data.\n
 552  * @param[in] ivt_buffer is a pointer to IVT data containing the effect for which to get the type
 553  * @param[in] effect_index is index of the effect for which to get the type
 554  * @param[out] duration is a pointer to the variable that will receive the duration of the effect in milliseconds
 555  * @param[out] magnitude is a pointer to the variable that will receive the magnitude of the effect
 556  * @param[out] style is a pointer to the variable that will receive the style of the effect
 557  * @param[out] attacktime is a pointer to the variable that will receive the attack time of the effect in milliseconds
 558  * @param[out] attacklevel is a pointer to the variable that will receive the attack level of the effect
 559  * @param[out] fadetime is a pointer to the variable that will receive the fade time of the effect in milliseconds
 560  * @param[out] fadelevel is a pointer to the variable that will receive the fade level of the effect
 561  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 562  * @par Example:
 563  * @code
 564  *      ...
 565  *      int status;
 566  *      unsigned char *ivt_buffer = { ... };
 567  *      int duration;
 568  *      int magnitude;
 569  *      int style;
 570  *      int attacktime;
 571  *      int attacklevel;
 572  *      int fadetime;
 573  *      int fadelevel;
 574  *
 575  *      status = device_haptic_get_magsweep_effect_definition(ivt_buffer, 1,
 576  *              &duration, &magnitude, &style, &attacktime, &attacklevel, &fadetime, &fadelevel);
 577  *      if (status < 0) {
 578  *              return status;
 579  *      }
 580  *      ...
 581  * @endcode
 582  */
 583
 584         int device_haptic_get_magsweep_effect_definition(const unsigned char *ivt_buffer, int effect_index, int *duration, int *magnitude, int *style, int *attacktime, int *attacklevel, int *fadetime, int *fadelevel);
 585
 586 /**
 587  * @fn int device_haptic_get_periodic_effect_definition(const unsigned char *ivt_buffer, int effect_index, int *duration, int *magnitude, int *period, int *style_and_wave_type, int *attacktime, int *attacklevel, int *fadetime, int *fadelevel);
 588  * @par Description:
 589  *      This API gets the parameters of a Periodic effect defined in IVT data.\n
 590  * @param[in] ivt_buffer is a pointer to IVT data containing the effect for which to get the type
 591  * @param[in] effect_index is index of the effect for which to get the type
 592  * @param[out] duration is a pointer to the variable that will receive the duration of the effect in milliseconds
 593  * @param[out] magnitude is a pointer to the variable that will receive the magnitude of the effect
 594  * @param[out] period is a pointer to the variable that will receive the period of the effect in milliseconds
 595  * @param[out] style_and_wave_type is a pointer to the variable that will receive the style and wave type of the effect
 596  * @param[out] attacktime is a pointer to the variable that will receive the attack time of the effect in milliseconds
 597  * @param[out] attacklevel is a pointer to the variable that will receive the attack level of the effect
 598  * @param[out] fadetime is a pointer to the variable that will receive the fade time of the effect in milliseconds
 599  * @param[out] fadelevel is a pointer to the variable that will receive the fade level of the effect
 600  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 601  * @par Example:
 602  * @code
 603  *      ...
 604  *      int status;
 605  *      unsigned char *ivt_buffer = { ... };
 606  *      int duration;
 607  *      int magnitude;
 608  *      int period;
 609  *      int style;
 610  *      int attacktime;
 611  *      int attacklevel;
 612  *      int fadetime;
 613  *      int fadelevel;
 614  *
 615  *      status = device_haptic_get_periodic_effect_definition(ivt_buffer, 1,
 616  *              &duration, &magnitude, &period, &style, &attacktime, &attacklevel, &fadetime, &fadelevel);
 617  *      if (status < 0) {
 618  *              return status;
 619  *      }
 620  *      ...
 621  * @endcode
 622  */
 623
 624         int device_haptic_get_periodic_effect_definition(const unsigned char *ivt_buffer, int effect_index, int *duration, int *magnitude, int *period, int *style_and_wave_type, int *attacktime, int *attacklevel, int *fadetime, int *fadelevel);
 625
 626 /**
 627  * @fn int device_haptic_get_effect_duration(const unsigned char *ivt_buffer, int effect_index, int *effect_duration)
 628  * @par Description:
 629  *      This API gets the duration of an effect defined in IVT data.\n
 630  * @param[in] ivt_buffer is a pointer to IVT data containing the effect for which to get the Duration
 631  * @param[in] effect_index is a index of the effect for which to get the Duration
 632  * @param[out] effect_duration is a pointer to the variable that will receive the Duration of the effect
 633  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 634  * @par Example:
 635  * @code
 636  *      ...
 637  *      int status;
 638  *      unsigned char *ivt_buffer = { ... };
 639  *      int effect_duration
 640  *
 641  *      //Get IVT effect duration
 642  *      status = device_haptic_get_effect_duration(ivt_buffer, 0, &effect_duration);
 643  *      if(staus < 0)
 644  *              return -1;
 645  *      ...
 646  * @endcode
 647  */
 648
 649         int device_haptic_get_effect_duration(const unsigned char *ivt_buffer, int effect_index, int *effect_duration);
 650
 651 /**
 652  * @fn int device_haptic_play_magsweep_effect(int device_handle, int duration, int magnitude, int style, int attacktime, int attacklevel, int fadetime, int fadelevel, int *effect_handle);
 653  * @par Description:
 654  *      This API play Mag Sweep effect.\n
 655  * @param[in] device_handle is a handle to the device on which to modify the playing effect
 656  * @param[in] duration is a duration of the effect in milliseconds
 657  * @param[in] magnitude is a magnitude of the effect
 658  * @param[in] style is a style of the effect
 659  * @param[in] attacktime is a attack time of the effect in milliseconds
 660  * @param[in] attacklevel is a attack level of the effect
 661  * @param[in] fadetime is a fade time of the effect in milliseconds
 662  * @param[in] fadelevel is a fade level of the effect
 663  * @param[out] effect_handle is a pointer to the variable that will receive a handle to the playing effect
 664  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 665  * @par Example:
 666  * @code
 667  *      ...
 668  *      int status;
 669  *      unsigned char *ivt_buffer = { ... };
 670  *      int duration       = 2900;
 671  *      int magnitude      = HAPTIC_MAX_MAGNITUDE;
 672  *      int style          = HAPTIC_STYLE_SMOOTH;
 673  *      int attackTime     = 2483;
 674  *      int attackLevel    = 0;
 675  *      int fadeTime       = 0;
 676  *      int fadeLevel      = HAPTIC_MAX_MAGNITUDE;
 677  *      int effect_handle;
 678  *
 679  *      status = device_haptic_play_magsweep_effect(device_handle,
 680  *              duration, magnitude, style, attacktime, attacklevel, fadetime, fadelevel, &effect_handle);
 681  *      if (status < 0) {
 682  *              return status;
 683  *      }
 684  *      ...
 685  * @endcode
 686  */
 687
 688         int device_haptic_play_magsweep_effect(int device_handle, int duration, int magnitude, int style, int attacktime, int attacklevel, int fadetime, int fadelevel, int *effect_handle);
 689
 690 /**
 691  * @fn int device_haptic_play_periodic_effect(int device_handle, int duration, int magnitude, int period, int style_and_wave_type, int attacktime, int attacklevel, int fadetime, int fadelevel, int *effect_handle);
 692  * @par Description:
 693  *      This API play Periodic effect.\n
 694  * @param[in] device_handle is a handle to the device on which to modify the playing effect
 695  * @param[in] duration is a duration of the effect in milliseconds
 696  * @param[in] magnitude is a magnitude of the effect
 697  * @param[in] style is a style of the effect
 698  * @param[in] attacktime is a attack time of the effect in milliseconds
 699  * @param[in] attacklevel is a attack level of the effect
 700  * @param[in] fadetime is a fade time of the effect in milliseconds
 701  * @param[in] fadelevel is a fade level of the effect
 702  * @param[out] effect_handle is a pointer to the variable that will receive a handle to the playing effect
 703  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 704  * @par Example:
 705  * @code
 706  *      ...
 707  *      int status;
 708  *      unsigned char *ivt_buffer = { ... };
 709  *      int duration       = 2900;
 710  *      int magnitude      = HAPTIC_MAX_MAGNITUDE;
 711  *      int period         = 100;
 712  *      int style          = HAPTIC_STYLE_SMOOTH;
 713  *      int attackTime     = 2483;
 714  *      int attackLevel    = 0;
 715  *      int fadeTime       = 0;
 716  *      int fadeLevel      = HAPTIC_MAX_MAGNITUDE;
 717  *      int effect_handle;
 718  *
 719  *      status = device_haptic_play_periodic_effect(device_handle,
 720  *              duration, magnitude, period, style, attacktime, attacklevel, fadetime, fadelevel, &effect_handle);
 721  *      if (status < 0) {
 722  *              return status;
 723  *      }
 724  *      ...
 725  * @endcode
 726  */
 727
 728         int device_haptic_play_periodic_effect(int device_handle, int duration, int magnitude, int period, int style_and_wave_type, int attacktime, int attacklevel, int fadetime, int fadelevel, int *effect_handle);
 729
 730 /**
 731  * @fn int device_haptic_modify_playing_magsweep_effect(int device_handle, int effect_handle,   int duration, int magnitude, int style, int attacktime, int attacklevel, int fadetime, int fadelevel);
 732  * @par Description:
 733  *      This API Modifies a playing Mag Sweep effect.\n
 734  * @param[in] device_handle is a handle to the device on which to modify the playing effect
 735  * @param[in] effect_handle is a handle to the playing MagSweep effect to modify
 736  * @param[in] duration is a duration of the effect in milliseconds
 737  * @param[in] magnitude is a magnitude of the effect
 738  * @param[in] style is a style of the effect
 739  * @param[in] attacktime is a attack time of the effect in milliseconds
 740  * @param[in] attacklevel is a attack level of the effect
 741  * @param[in] fadetime is a fade time of the effect in milliseconds
 742  * @param[in] fadelevel is a fade level of the effect
 743  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 744  * @par Example:
 745  * @code
 746  *      ...
 747  *      int status;
 748  *      unsigned char *ivt_buffer = { ... };
 749  *      int duration       = 2900;
 750  *      int magnitude      = HAPTIC_MAX_MAGNITUDE;
 751  *      int style          = HAPTIC_STYLE_SMOOTH;
 752  *      int attackTime     = 2483;
 753  *      int attackLevel    = 0;
 754  *      int fadeTime       = 0;
 755  *      int fadeLevel      = HAPTIC_MAX_MAGNITUDE;
 756  *
 757  *      status = device_haptic_modify_playing_magsweep_effect(device_handle, effect_handle,
 758  *              duration, magnitude, style, attacktime, attacklevel, fadetime, fadelevel);
 759  *      if (status < 0) {
 760  *              return status;
 761  *      }
 762  *      ...
 763  * @endcode
 764  */
 765
 766         int device_haptic_modify_playing_magsweep_effect(int device_handle, int effect_handle,  int duration, int magnitude, int style, int attacktime, int attacklevel, int fadetime, int fadelevel);
 767
 768 /**
 769  * @fn int device_haptic_modify_playing_periodic_effect(int device_handle, int effect_handle, int duration, int magnitude, int period, int style_and_wave_type, int attacktime, int attacklevel, int fadetime, int fadelevel);
 770  * @par Description:
 771  *      This API modifies a playing Periodic effect.\n
 772  * @param[in] device_handle is a handle to the device on which to modify the playing effect
 773  * @param[in] effect_handle is a handle to the playing MagSweep effect to modify
 774  * @param[in] duration is a duration of the effect in milliseconds
 775  * @param[in] magnitude is a magnitude of the effect
 776  * @param[in] period is a period of the effect
 777  * @param[in] style is a style of the effect
 778  * @param[in] attacktime is a attack time of the effect in milliseconds
 779  * @param[in] attacklevel is a attack level of the effect
 780  * @param[in] fadetime is a fade time of the effect in milliseconds
 781  * @param[in] fadelevel is a fade level of the effect
 782  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 783  * @par Example:
 784  * @code
 785  *      ...
 786  *      int status;
 787  *      unsigned char *ivt_buffer = { ... };
 788  *      int duration       = 2900;
 789  *      int magnitude      = HAPTIC_MAX_MAGNITUDE;
 790  *      int period         = 100;
 791  *      int style          = HAPTIC_STYLE_SMOOTH;
 792  *      int attackTime     = 2483;
 793  *      int attackLevel    = 0;
 794  *      int fadeTime       = 0;
 795  *      int fadeLevel      = HAPTIC_MAX_MAGNITUDE;
 796  *
 797  *      status = device_haptic_modify_playing_periodic_effect(device_handle, effect_handle,
 798  *              duration, magnitude, period, style, attacktime, attacklevel, fadetime, fadelevel);
 799  *      if (status < 0) {
 800  *              return status;
 801  *      }
 802  *      ...
 803  * @endcode
 804  */
 805
 806         int device_haptic_modify_playing_periodic_effect(int device_handle, int effect_handle, int duration, int magnitude, int period, int style_and_wave_type, int attacktime, int attacklevel, int fadetime, int fadelevel);
 807
 808 /**
 809  * @fn int device_haptic_create_streaming_effect(int device_handle, int *effect_handle)
 810  * @par Description:
 811  *      This API creates a Streaming effect.\n
 812  * @param[in] device_handle is a handle to the device associated to the effect
 813  * @param[out] effect_handle is a pointer to the variable that will receive a handle to the Streaming effect
 814  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 815  * @par Example:
 816  * @code
 817  *      ...
 818  *      int status;
 819  *      int effect_handle;
 820  *
 821  *      status = device_haptic_create_streaming_effect(device_handle, &effect_handle);
 822  *      if(status < 0)
 823  *              return -1;
 824  *      ...
 825  * @endcode
 826  */
 827
 828         int device_haptic_create_streaming_effect(int device_handle, int *effect_handle);
 829
 830 /**
 831  * @fn int device_haptic_destroy_streaming_effect(int device_handle, int effect_handle)
 832  * @par Description:
 833  *      This API creates a Streaming effect.\n
 834  * @param[in] device_handle is a handle to the device associated to the effect
 835  * @param[in] effect_handle is a handle to the Streaming effect to destroy
 836  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 837  * @par Example:
 838  * @code
 839  *      ...
 840  *      int status;
 841  *      int effect_handle;
 842  *
 843  *      status = device_haptic_create_streaming_effect(device_handle, &effect_handle);
 844  *      if(status < 0)
 845  *              return -1;
 846  *      ...
 847  * @endcode
 848  */
 849
 850         int device_haptic_destroy_streaming_effect(int device_handle, int effect_handle);
 851
 852 /**
 853  * @fn int device_haptic_play_streaming_sample(int device_handle, int effect_handle, const unsigned char *streaming_sample, int size)
 854  * @par Description:
 855  *      This API plays a Streaming Sample given the parameters defining the effect.\n
 856  * @param[in] device_handle is a handle to the device on which to play the effect
 857  * @param[in] effect_handle is a hndle to the Streaming effect to play
 858  * @param[in] streaming_sameple is a pointer to Streaming Sample data containing the definition of the effect to play
 859  * @param[in] size is a size of the buffer, in bytes, pointed to by streaming_sample parameter
 860  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 861  * @par Example:
 862  * @code
 863  *      ...
 864  *      int status;
 865  *
 866  *      status = device_haptic_play_streaming_sample(device_handle, effect_handle, *streaming_sample, size);
 867  *      if(status < 0)
 868  *              return -1;
 869  *      ...
 870  * @endcode
 871  */
 872
 873         int device_haptic_play_streaming_sample(int device_handle, int effect_handle, const unsigned char *streaming_sample, int size);
 874
 875 /**
 876  * @fn int device_haptic_play_streaming_sample_with_offset(int device_handle, int effect_handle, const unsigned char *streaming_sample, int size, int offset_time)
 877  * @par Description:
 878  *      This API plays a Streaming Sample with a time offset given the parameters defining the effect.\n
 879  * @param[in] device_handle is a handle to the device on which to play the effect
 880  * @param[in] effect_handle is a hndle to the Streaming effect to play
 881  * @param[in] streaming_sameple is a pointer to Streaming Sample data containing the definition of the effect to play
 882  * @param[in] size is a size of the buffer, in bytes, pointed to by streaming_sample parameter
 883  * @param[in] offset_time is set offet time to play the sample
 884  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 885  * @par Example:
 886  * @code
 887  *      ...
 888  *      int status;
 889  *
 890  *      status = device_haptic_play_streaming_sample_with_offset(device_handle, effect_handle, *streaming_sample, size, 100);
 891  *      if(status < 0)
 892  *              return -1;
 893  *      ...
 894  * @endcode
 895  */
 896
 897         int device_haptic_play_streaming_sample_with_offset(int device_handle, int effect_handle, const unsigned char *streaming_sample, int size, int offset_time);
 898
 899
 900
 901 /**
 902  * @fn int device_haptic_stop_all_playing_effects(int device_handle)
 903  * @par Description:
 904  *      This API stops all playing and paused effects on a device.\n
 905  * @param[in] device_handle is a handle to the device associated to the effect
 906  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 907  * @par Example:
 908  * @code
 909  *      ...
 910  *      int status;
 911  *
 912  *      status = device_haptic_stop_all_playing_effects(device_handle);
 913  *      if(status < 0)
 914  *              return -1;
 915  *      ...
 916  * @endcode
 917  */
 918
 919         int device_haptic_stop_all_playing_effects(int device_handle);
 920
 921 /**
 922  * @fn int device_haptic_save_file(const unsigned char *ivt_buffer, const char *path_name)
 923  * @par Description:
 924  *      This API saves an IVT file to persistent storage.\n
 925  * @param[in] ivt_buffer is a pointer to IVT data
 926  * @param[in] path_name is a pointer to the character buffer containing the path name of the file to save
 927  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 928  * @par Example:
 929  * @code
 930  *      ...
 931  *      int status;
 932  *      unsigned char *ivt_buffer = { ... };
 933  *      char *path_name = "test.ivt";
 934  *
 935  *      status = device_haptic_save_file(ivt_buffer, path_name);
 936  *      if(staus < 0)
 937  *              return -1;
 938  *      ...
 939  * @endcode
 940  */
 941
 942         int device_haptic_save_file(const unsigned char *ivt_buffer, const char *path_name);
 943
 944 /**
 945  * @fn int device_haptic_delete_file(const char *path_name)
 946  * @par Description:
 947  *      This API removes an IVT file from persistent storage.\n
 948  * @param[in] path_name is a pointer to the character buffer containing the path name of the file to remove.\n
 949  * @return if it succeed, it return HAPTIC_S_SUCCESSe , otherwise negative value return
 950  * @see device_haptic_save_file()
 951  * @par Example:
 952  * @code
 953  *      ...
 954  *      char *path_name = "test.ivt";
 955  *      int = status;
 956  *
 957  *      //Remove an IVT file
 958  *      status = device_haptic_delete_file(path_name);
 959  *      if(status < 0)
 960  *              return -1;
 961  *      ...
 962  * @endcode
 963  */
 964
 965         int device_haptic_delete_file(const char *path_name);
 966
 967 /**
 968  * @fn int device_haptic_pause_playing_effect(int device_handle, int effect_handle)
 969  * @par Description:
 970  *      This API Pauses a playing effect.\n
 971  * @param[in] device_handle is a handle to the device associated to the effect
 972  * @param[in] effect_handle is a handle to the playing effect to pause
 973  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 974  * @par Example:
 975  * @code
 976  *      ...
 977  *      int status;
 978  *
 979  *      status = device_haptic_pause_playing_effect(handle, effect_handle);
 980  *      if (status < 0) {
 981  *              return status;
 982  *      }
 983  *      ...
 984  * @endcode
 985  */
 986
 987         int device_haptic_pause_playing_effect(int device_handle, int effect_handle);
 988
 989 /**
 990  * @fn int device_haptic_resume_paused_effect(int device_handle, int effect_handle)
 991  * @par Description:
 992  *      This API resumes a paused effect from the point where the effect was paused.\n
 993  * @param[in] device_handle is a handle to the device associated to the effect
 994  * @param[in] effect_handle is a handle to the playing effect to pause
 995  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
 996  * @par Example:
 997  * @code
 998  *      ...
 999  *      int status;
1000  *
1001  *      status = device_haptic_resume_paused_effect(handle, effect_handle);
1002  *      if (status < 0) {
1003  *              return status;
1004  *      }
1005  *      ...
1006  * @endcode
1007  */
1008
1009         int device_haptic_resume_paused_effect(int device_handle, int effect_handle);
1010
1011 /**
1012  * @fn int device_haptic_get_effect_state(int device_handle, int effect_handle, int *effect_state)
1013  * @par Description:
1014  *      This API retrieves the status of an effect (playing, not playing, paused).\n
1015  * @param[in] device_handle ia a handle to the device associated to the effect
1016  * @param[in] effect_handle ia a handle to the effect which must have been obtained by calling playing APIs
1017  * @param[out] state ia a pointer to the variable that will receive the status bits of the effect
1018  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
1019  * @par Example:
1020  * @code
1021  *      ...
1022  *      int status;
1023  *
1024  *      //Open the haptic device
1025  *      status = device_haptic_get_effect_state(device_handle, device_effect, &state);
1026  *      if(status < 0)
1027  *              return -1;
1028  *      ...
1029  * @endcode
1030  */
1031
1032         int device_haptic_get_effect_state(int device_handle, int effect_handle, int *effect_state);
1033
1034 /**
1035  * @fn int device_haptic_get_size(const unsigned char *ivt_buffer, int size)
1036  * @par Description:
1037  *      This API sets the size of IVT data.\n
1038  * @param[in] ivt_buffer is a pointer to an IVT buffer
1039  * @param[in] size is a size of the buffer pointed to by ivt_buffer
1040  * @return if it succeed, it return the size of the IVT data, otherwise negative value return
1041  * @par Example:
1042  * @code
1043  *      ...
1044  *      int status;
1045  *      unsigned char *ivt_buffer = { ... };
1046  *      int IVT_size;
1047  *
1048  *      IVT_size = device_haptic_get_size(ivt_buffer, sizeof(ivt_buffer));
1049  *      if (status < 0) {
1050  *              return status;
1051  *      }
1052  *      ...
1053  * @endcode
1054  */
1055
1056         int device_haptic_get_size(const unsigned char *ivt_buffer, int size);
1057
1058 /**
1059  * @fn int device_haptic_initialize_buffer(unsigned char *ivt_buffer, int size)
1060  * @par Description:
1061  *      This API initializes an IVT buffer. Any data currently in the buffer will be destroyed.\n
1062  * @param[in/out] ivt_buffer is a pointer to a buffer to initialize
1063  * @param[in] size is a size of the buffer pointed to by ivt_buffer
1064  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
1065  * @par Example:
1066  * @code
1067  *      ...
1068  *      int status;
1069  *      int size = 1024;
1070  *      unsigned char ivt_buffer[size];
1071  *
1072  *      status = device_haptic_initialize_buffer(ivt_buffer, size);
1073  *      if (status < 0) {
1074  *              return status;
1075  *      }
1076  *      ...
1077  * @endcode
1078  */
1079
1080         int device_haptic_initialize_buffer(unsigned char *ivt_buffer, int size);
1081
1082 /**
1083  * @fn int device_haptic_insert_element(unsigned char *ivt_buffer, int size, int timeline_index, const HapticElement *element)
1084  * @par Description:
1085  *      This API inserts an element into a Timeline effect in an IVT buffer.\n
1086  * @param[in/out] ivt_buffer is a pointer to an IVT buffer
1087  * @param[in] size is a size of the buffer pointed to by ivt_buffer
1088  * @param[in] timeline_index is an index of a Timeline effect in which to insert the element
1089  * @param[in] element is a pointer to an HapticElement structure containing the parameters of a Periodic effect, MagSweep effect, or Repeat event to insert into the Timeline effect
1090  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
1091  * @par Example:
1092  * @code
1093  *      ...
1094  *      int status;
1095  *      HapticElement elem1;
1096  *      elem1.elementtype    = HAPTIC_ELEMTYPE_MAGSWEEP;
1097  *      elem1.time           = 0;
1098  *      elem1.TypeSpecific.magsweep.duration       = 2900;
1099  *      elem1.TypeSpecific.magsweep.magnitude      = HAPTIC_MAX_MAGNITUDE;
1100  *      elem1.TypeSpecific.magsweep.style          = HAPTIC_STYLE_SMOOTH;
1101  *      elem1.TypeSpecific.magsweep.attacktime     = 2483;
1102  *      elem1.TypeSpecific.magsweep.attacklevel    = 0;
1103  *      elem1.TypeSpecific.magsweep.fadetime       = 0;
1104  *      elem1.TypeSpecific.magsweep.fadelevel      = HAPTIC_MAX_MAGNITUDE;
1105  *
1106  *      status = device_haptic_insert_element(temp_buffer, temp_size, timeline_index, &elem1);
1107  *      if (status < 0) {
1108  *              return status;
1109  *      }
1110
1111  *      ...
1112  * @endcode
1113  */
1114
1115         int device_haptic_insert_element(unsigned char *ivt_buffer, int size, int timeline_index, const HapticElement *element);
1116
1117 /**
1118  * @fn int device_haptic_insert_element2(unsigned char *ivt_buffer, int size, int timeline_index, const HapticElement2 *element)
1119  * @par Description:
1120  *      This API inserts an element into a Timeline effect in an IVT buffer.\n
1121  * @param[in/out] ivt_buffer is a pointer to an IVT buffer
1122  * @param[in] size is a size of the buffer pointed to by ivt_buffer
1123  * @param[in] timeline_index is an index of a Timeline effect in which to insert the element
1124  * @param[in] element is a pointer to an HapticElement2 structure containing the parameters of a Periodic effect, MagSweep effect, or Repeat event to insert into the Timeline effect
1125  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
1126  * @par Example:
1127  * @code
1128  *      ...
1129  *      int status;
1130  *      HapticElement2 elem1;
1131  *      elem1.elementtype    = HAPTIC_ELEMTYPE_MAGSWEEP;
1132  *      elem1.time           = 0;
1133  *      elem1.TypeSpecific.magsweep.duration       = 2900;
1134  *      elem1.TypeSpecific.magsweep.magnitude      = HAPTIC_MAX_MAGNITUDE;
1135  *      elem1.TypeSpecific.magsweep.style          = HAPTIC_STYLE_SMOOTH;
1136  *      elem1.TypeSpecific.magsweep.attacktime     = 2483;
1137  *      elem1.TypeSpecific.magsweep.attacklevel    = 0;
1138  *      elem1.TypeSpecific.magsweep.fadetime       = 0;
1139  *      elem1.TypeSpecific.magsweep.fadelevel      = HAPTIC_MAX_MAGNITUDE;
1140  *
1141  *      status = device_haptic_insert_element2(temp_buffer, temp_size, timeline_index, &elem1);
1142  *      if (status < 0) {
1143  *              return status;
1144  *      }
1145
1146  *      ...
1147  * @endcode
1148  */
1149
1150         int device_haptic_insert_element2(unsigned char *ivt_buffer, int size, int timeline_index, const HapticElement2 *element);
1151
1152 /**
1153  * @fn int device_haptic_insert_element3(unsigned char *ivt_buffer, int size, int timeline_index, const HapticElement3 *element)
1154  * @par Description:
1155  *      This API inserts an element into a Timeline effect in an IVT buffer.\n
1156  * @param[in/out] ivt_buffer is a pointer to an IVT buffer
1157  * @param[in] size is a size of the buffer pointed to by ivt_buffer
1158  * @param[in] timeline_index is an index of a Timeline effect in which to insert the element
1159  * @param[in] element is a pointer to an HapticElement3 structure containing the parameters of a Periodic effect, MagSweep effect, or Repeat event to insert into the Timeline effect
1160  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
1161  * @par Example:
1162  * @code
1163  *      ...
1164  *      int status;
1165  *      HapticElement3 elem1;
1166  *      elem1.elementtype    = HAPTIC_ELEMTYPE_MAGSWEEP;
1167  *      elem1.time           = 0;
1168  *      elem1.TypeSpecific.magsweep.duration       = 2900;
1169  *      elem1.TypeSpecific.magsweep.magnitude      = HAPTIC_MAX_MAGNITUDE;
1170  *      elem1.TypeSpecific.magsweep.style          = HAPTIC_STYLE_SMOOTH;
1171  *      elem1.TypeSpecific.magsweep.attacktime     = 2483;
1172  *      elem1.TypeSpecific.magsweep.attacklevel    = 0;
1173  *      elem1.TypeSpecific.magsweep.fadetime       = 0;
1174  *      elem1.TypeSpecific.magsweep.fadelevel      = HAPTIC_MAX_MAGNITUDE;
1175  *
1176  *      status = device_haptic_insert_element3(temp_buffer, temp_size, 0, &elem1);
1177  *      if (status < 0) {
1178  *              return status;
1179  *      }
1180
1181  *      ...
1182  * @endcode
1183  */
1184
1185         int device_haptic_insert_element3(unsigned char *ivt_buffer, int size, int timeline_index, const HapticElement3 *element);
1186
1187 /**
1188  * @fn int device_haptic_read_element(const unsigned char *ivt_buffer, int size, int timeline_index, int element_index, HapticElement *element);
1189  * @par Description:
1190  *      This API retrieves the parameters of an element of a Timeline effect in an IVT buffer.\n
1191  * @param[in/out] ivt_buffer is a pointer to an IVT buffer
1192  * @param[in] size is a size of the buffer pointed to by ivt_buffer
1193  * @param[in] timeline_index is an index of a Timeline effect in which to read the element
1194  * @param[in] element_index is an index of the element to retrieve
1195  * @param[out] element is a pointer to an HapticElement structure to receive the parameters of a Periodic effect, MagSweepeffect, or Repeat event
1196  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
1197  * @par Example:
1198  * @code
1199  *      ...
1200  *      int status;
1201  *      HapticElement elem1;
1202  *
1203  *      status = device_haptic_insert_element(ivt_buffer, size, 0, 0, &elem1);
1204  *      if (status < 0) {
1205  *              return status;
1206  *      }
1207
1208  *      ...
1209  * @endcode
1210  */
1211
1212
1213         int device_haptic_read_element(const unsigned char *ivt_buffer, int size, int timeline_index, int element_index, HapticElement *element);
1214
1215 /**
1216  * @fn int device_haptic_read_element2(const unsigned char *ivt_buffer, int size, int timeline_index, int element_index, HapticElement2 *element);
1217  * @par Description:
1218  *      This API retrieves the parameters of an element of a Timeline effect in an IVT buffer.\n
1219  * @param[in/out] ivt_buffer is a pointer to an IVT buffer
1220  * @param[in] size is a size of the buffer pointed to by ivt_buffer
1221  * @param[in] timeline_index is an index of a Timeline effect in which to read the element
1222  * @param[in] element_index is an index of the element to retrieve
1223  * @param[out] element is a pointer to an HapticElement2 structure to receive the parameters of a Periodic effect, MagSweepeffect, or Repeat event
1224  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
1225  * @par Example:
1226  * @code
1227  *      ...
1228  *      int status;
1229  *      HapticElement2 elem1;
1230  *
1231  *      status = device_haptic_insert_element2(ivt_buffer, size, 0, 0, &elem1);
1232  *      if (status < 0) {
1233  *              return status;
1234  *      }
1235
1236  *      ...
1237  * @endcode
1238  */
1239
1240         int device_haptic_read_element2(const unsigned char *ivt_buffer, int size, int timeline_index, int element_index, HapticElement2 *element);
1241
1242 /**
1243  * @fn int device_haptic_read_element3(const unsigned char *ivt_buffer, int size, int timeline_index, int element_index, HapticElement3 *element);
1244  * @par Description:
1245  *      This API retrieves the parameters of an element of a Timeline effect in an IVT buffer.\n
1246  * @param[in/out] ivt_buffer is a pointer to an IVT buffer
1247  * @param[in] size is a size of the buffer pointed to by ivt_buffer
1248  * @param[in] timeline_index is an index of a Timeline effect in which to read the element
1249  * @param[in] element_index is an index of the element to retrieve
1250  * @param[out] element is a pointer to an HapticElement3 structure to receive the parameters of a Periodic effect, MagSweepeffect, or Repeat event
1251  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
1252  * @par Example:
1253  * @code
1254  *      ...
1255  *      int status;
1256  *      HapticElement3 elem1;
1257  *
1258  *      status = device_haptic_insert_element3(ivt_buffer, size, 0, 0, &elem1);
1259  *      if (status < 0) {
1260  *              return status;
1261  *      }
1262
1263  *      ...
1264  * @endcode
1265  */
1266
1267         int device_haptic_read_element3(const unsigned char *ivt_buffer, int size, int timeline_index, int element_index, HapticElement3 *element);
1268
1269 /**
1270  * @fn int device_haptic_remove_element(unsigned char *ivt_buffer, int size, int timeline_index, int element_index);
1271  * @par Description:
1272  *      This API removes the element at the specified index from a Timeline effect in an IVT buffer.\n
1273  * @param[in/out] ivt_buffer is a pointer to an IVT buffer
1274  * @param[in] size is a size of the buffer pointed to by ivt_buffer
1275  * @param[in] timeline_index is an index of a Timeline effect to remove the element from
1276  * @param[in] element_index is an index of the element to remove
1277  * @return if it succeed, it return HAPTIC_S_SUCCESS, otherwise negative value return
1278  * @par Example:
1279  * @code
1280  *      ...
1281  *      int status;
1282  *      HapticElement3 elem1;
1283  *
1284  *      status = device_haptic_remove_element(ivt_buffer, size, 0, 0);
1285  *      if (status < 0) {
1286  *              return status;
1287  *      }
1288
1289  *      ...
1290  * @endcode
1291  */
1292
1293         int device_haptic_remove_element(unsigned char *ivt_buffer, int size, int timeline_index, int element_index);
1294
1295
1296 /**
1297  * @}
1298  */
1299
1300 #ifdef __cplusplus
1301 }
1302 #endif
1303 #endif /* __DEVMAN_HAPTIC_EXT_H__ */