include/power.h

   1 /*
   2  * Copyright (c) 2011 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
  19
  20
  21 #ifndef __TIZEN_SYSTEM_POWER_H__
  22 #define __TIZEN_SYSTEM_POWER_H__
  23
  24
  25 #include <tizen.h>
  26
  27
  28 #ifdef __cplusplus
  29 extern "C"
  30 {
  31 #endif
  32
  33 /**
  34  * @addtogroup CAPI_SYSTEM_POWER_MODULE
  35  * @{
  36  * @brief
  37  * This is a Power API of the System Service.
  38  * @}
  39  */
  40
  41 /**
  42  * @addtogroup CAPI_SYSTEM_POWER_MODULE
  43  * @{
  44  */
  45
  46
  47 /**
  48  * @brief       Enumerations of available power states.
  49  * @details     An application cannot put the device into the power off state or the suspend state.
  50  */
  51 typedef enum
  52 {
  53     POWER_STATE_NORMAL,      /**< Normal state */
  54     POWER_STATE_SCREEN_DIM,  /**< Screen dim state */
  55     POWER_STATE_SCREEN_OFF,  /**< Screen off state */
  56 } power_state_e;
  57
  58
  59 /**
  60  * @brief       Enumerations of error code for Power.
  61  */
  62 typedef enum
  63 {
  64     POWER_ERROR_NONE                 = TIZEN_ERROR_NONE,                                /**< Successful */
  65     POWER_ERROR_IO_ERROR             = TIZEN_ERROR_IO_ERROR,                    /**< I/O error */
  66     POWER_ERROR_INVALID_PARAMETER    = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  67 } power_error_e;
  68
  69
  70 /**
  71  * @}
  72 */
  73
  74
  75 /**
  76  * @addtogroup CAPI_SYSTEM_POWER_MODULE
  77  * @{
  78  */
  79
  80 /**
  81  * @brief Called when an power state changed
  82  *
  83  * @param[in] state     The state of power
  84  * @param[in] user_data     The user data passed from the callback registration function
  85  *
  86  */
  87 typedef void (*power_changed_cb)(power_state_e state, void *user_data);
  88
  89 /**
  90  * @brief Locks the given power state for a specified time.
  91  *
  92  * @details After the given @a timeout_ms (in milliseconds), unlock the given power state automatically.
  93  * #SYSTEM_INFO_KEY_POWER_STATE key and associated system information function can give inform about the current state.
  94  *
  95  * @remarks If the process dies, every lock will be removed.
  96  *
  97  * @param[in] power_state       The power state to lock
  98  * @param[in] timeout_ms        The positive number in milliseconds or 0 for permanent lock \n
  99  *                                                      So you must release the permanent lock of power state with #power_unlock_state() if @a timeout_ms is zero. \n
 100  *
 101  * @return 0 on success, otherwise a negative error value.
 102  * @retval #POWER_ERROR_NONE               Successful
 103  * @retval #POWER_ERROR_INVALID_PARAMETER  Invalid parameter
 104  * @retval #POWER_ERROR_IO_ERROR           I/O error
 105  *
 106  * @see power_unlock_state()
 107  * @see system_info_set_changed_cb()
 108  * @see system_info_get_value_int(SYSTEM_INFO_KEY_POWER_STATE, ...)
 109  */
 110 int power_lock_state(power_state_e power_state, int timeout_ms);
 111
 112
 113 /**
 114  * @brief Releases the given power state locked before.
 115  * @param[in] power_state       The power state to release
 116  *
 117  * @return 0 on success, otherwise a negative error value.
 118  * @retval #POWER_ERROR_NONE                            Successful
 119  * @retval #POWER_ERROR_INVALID_PARAMETER       Invalid parameter
 120  * @retval #POWER_ERROR_IO_ERROR                        I/O error
 121  *
 122  * @see power_lock_state()
 123  */
 124 int power_unlock_state(power_state_e power_state);
 125
 126
 127 /**
 128  * @brief Changes the current power state to the normal/dim state.
 129  *
 130  * @param[in] dim       Determine to go to dim state.
 131  *
 132  * @return 0 on success, otherwise a negative error value.
 133  * @retval #POWER_ERROR_NONE            Successful
 134  * @retval #POWER_ERROR_IO_ERROR        I/O error
 135  *
 136  * @post The device will be in #POWER_STATE_NORMAL state.
 137  *
 138  */
 139 int power_wakeup(bool dim);
 140
 141 /**
 142  * @brief Get the current power state.
 143  *
 144  * @return power state enum, otherwise a negative error value.
 145  * @retval #POWER_ERROR_NONE            Successful
 146  * @retval #POWER_ERROR_IO_ERROR        I/O error
 147  */
 148 power_state_e power_get_state(void);
 149
 150 /**
 151  * @brief Set the callback for getting power changed event.
 152  *
 153  * @param[in]   power_changed_cb        The power state changed callback function pointer
 154  * @param[in]   user_data   The user data to be passed to the callback function
 155  *
 156  * @return 0 on success, otherwise a negative error value.
 157  * @retval #POWER_ERROR_NONE                            Successful
 158  * @retval #POWER_ERROR_INVALID_PARAMETER       Invalid parameter
 159  * @retval #POWER_ERROR_IO_ERROR                        I/O error
 160  */
 161 int power_set_changed_cb(power_changed_cb callback, void* user_data);
 162
 163 /**
 164  * @brief Unset the callback for getting power changed event.
 165  *
 166  * @return 0 on success, otherwise a negative error value.
 167  * @retval #POWER_ERROR_NONE                            Successful
 168  * @retval #POWER_ERROR_IO_ERROR                        I/O error
 169  */
 170 int power_unset_changed_cb(void);
 171
 172 /**
 173  * @}
 174  */
 175
 176 #ifdef __cplusplus
 177 }
 178 #endif
 179
 180 #endif /* __TIZEN_SYSTEM_POWER_H__*/