include/callback.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_SYSTEM_CALLBACK_H__
  19 #define __TIZEN_SYSTEM_CALLBACK_H__
  20
  21
  22 #include <stdbool.h>
  23 #include "device-error.h"
  24
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30
  31 /**
  32  * @addtogroup CAPI_SYSTEM_DEVICE_CALLBACK_MODULE
  33  * @{
  34  */
  35
  36
  37 /**
  38  * @brief Enumeration for the device state callback.
  39  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  40  */
  41 typedef enum {
  42     DEVICE_CALLBACK_BATTERY_CAPACITY, /**< Called when a battery charge percentage is changed */
  43     DEVICE_CALLBACK_BATTERY_LEVEL, /**< Called when a battery level is changed */
  44     DEVICE_CALLBACK_BATTERY_CHARGING, /**< Called when battery charging state is changed */
  45     DEVICE_CALLBACK_DISPLAY_STATE, /**< Called when a display state is changed */
  46     DEVICE_CALLBACK_FLASH_BRIGHTNESS, /**< Called when a flash brightness is changed (Since Tizen @if Mobile 2.4 @elseif WEARABLE 3.0 @endif) */
  47     DEVICE_CALLBACK_MAX,
  48 } device_callback_e;
  49
  50
  51 /**
  52  * @brief Called when a device status is changed.
  53  * @details Each device callback has a different output param type. \n
  54  *          So you need to check below output param before using this function. \n
  55  *                  callback enum               output type \n
  56  *          DEVICE_CALLBACK_BATTERY_CAPACITY        int \n
  57  *          DEVICE_CALLBACK_BATTERY_LEVEL           int \n
  58  *          DEVICE_CALLBACK_BATTERY_CHARGING        bool \n
  59  *          DEVICE_CALLBACK_DISPLAY_STATE           int \n
  60  *          DEVICE_CALLBACK_FLASH_BRIGHTNESS        int
  61  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  62  * @remarks DEVICE_CALLBACK_FLASH_BRIGHTNESS callback invoked when user set flash brightness by using device_flash_set_brightness(). It does not work by camera flash operation. To register DEVICE_CALLBACK_FLASH_BRIGHTNESS callback, you need to declare the LED privilege (%http://tizen.org/privilege/led).
  63  * @param[out] type The device type to monitor
  64  * @param[out] value The changed value
  65  * @param[out] user_data The user data passed from the callback registration function
  66  */
  67 typedef void (*device_changed_cb)(device_callback_e type, void *value, void *user_data);
  68
  69
  70 /**
  71  * @brief Adds a callback to the observing device state.
  72  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  73  * @remarks The following feature should be supported for #DEVICE_CALLBACK_DISPLAY_STATE: %http://tizen.org/feature/display. Otherwise #DEVICE_ERROR_NOT_SUPPORTED is returned.
  74  * @param[in] type The device type to monitor
  75  * @param[in] callback The callback function to add
  76  * @param[in] user_data The user data to be passed to the callback function
  77  * @return @c 0 on success,
  78  *         otherwise a negative error value
  79  * @retval #DEVICE_ERROR_NONE Successful
  80  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  81  * @retval #DEVICE_ERROR_ALREADY_IN_PROGRESS Operation already
  82  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  83  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
  84  */
  85 int device_add_callback(device_callback_e type, device_changed_cb callback, void *user_data);
  86
  87
  88 /**
  89  * @brief Removes a device callback function.
  90  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  91  * @remarks The following feature should be supported for #DEVICE_CALLBACK_DISPLAY_STATE: %http://tizen.org/feature/display. Otherwise #DEVICE_ERROR_NOT_SUPPORTED is returned.
  92  * @param[in] type The device type to monitor
  93  * @param[in] callback The callback function to remove
  94  * @return @c 0 on success,
  95  *         otherwise a negative error value
  96  * @retval #DEVICE_ERROR_NONE Successful
  97  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  98  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  99  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
 100  */
 101 int device_remove_callback(device_callback_e type, device_changed_cb callback);
 102
 103
 104 /**
 105  * @}
 106  */
 107
 108
 109 #ifdef __cplusplus
 110 }
 111 #endif
 112
 113
 114 #endif  // __TIZEN_SYSTEM_CALLBACK_H__