include/power.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_POWER_H__
  19 #define __TIZEN_SYSTEM_POWER_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_POWER_MODULE
  33  * @{
  34  */
  35
  36
  37 /**
  38  * @brief Enumeration for lock type.
  39  * @details Each enum ensures that the suitable device is on until all the lock requests have been released or after a timeout.
  40  * <TABLE>
  41  * <TR><TH>Enum Type</TH><TH>CPU</TH><TH>Brightness(Display)</TH></TR>
  42  * <TR><TD>POWER_LOCK_CPU</TD><TD>ON</TD><TD>OFF</TD></TR>
  43  * <TR><TD>POWER_LOCK_DISPLAY</TD><TD>ON</TD><TD>ON(Normal)</TD></TR>
  44  * <TR><TD>POWER_LOCK_DISPLAY_DIM</TD><TD>ON</TD><TD>ON(Dim)</TD></TR>
  45  * </TABLE>
  46  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  47  * @remarks An application can lock the specific type.
  48  * @remarks These enums are mutually exclusive.
  49  * @remarks You cannot combine with an enum below.
  50  */
  51 typedef enum {
  52     POWER_LOCK_CPU, /**< CPU lock */
  53     POWER_LOCK_DISPLAY, /**< Display normal lock */
  54     POWER_LOCK_DISPLAY_DIM, /**< Display dim lock */
  55 } power_lock_e;
  56
  57
  58 /**
  59  * @brief Locks the given lock state for a specified time.
  60  * @details After the given @a timeout_ms (in milliseconds), unlock the given lock state automatically.
  61  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  62  * @privlevel public
  63  * @privilege %http://tizen.org/privilege/display
  64  * @remarks If the process dies, then every lock will be removed.
  65  * @param[in] type The power type to request lock
  66  * @param[in] timeout_ms The positive number in milliseconds or @c 0 for permanent lock \n
  67  *                       So you must release the permanent lock of power state with #device_power_release_lock() if @a timeout_ms is zero
  68  * @return @c 0 on success,
  69  *         otherwise a negative error value
  70  * @retval #DEVICE_ERROR_NONE Successful
  71  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  72  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  73  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  74  * @see device_power_release_lock()
  75  */
  76 int device_power_request_lock(power_lock_e type, int timeout_ms);
  77
  78
  79 /**
  80  * @brief Releases the given lock state which was locked before.
  81  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  82  * @privlevel public
  83  * @privilege %http://tizen.org/privilege/display
  84  * @param[in] type The power type to release lock
  85  * @return @c 0 on success,
  86  *         otherwise a negative error value
  87  * @retval #DEVICE_ERROR_NONE Successful
  88  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  89  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  90  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  91  * @see device_power_request_lock()
  92  */
  93 int device_power_release_lock(power_lock_e type);
  94
  95
  96 /**
  97  * @deprecated Deprecated Since @if WEARABLE 3.0 @else 2.4 @endif
  98  * @brief Changes the current power state to the normal/dim state.
  99  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 100  * @privlevel public
 101  * @privilege %http://tizen.org/privilege/display
 102  * @remarks This API triggers turn on process and then updates the status when it completes. While the operation is on-going, the device_display_get_state() function returns previous display state.
 103  * @param[in] dim Set @c true to set the dim state,
 104  *                otherwise set @c false to not set the dim state
 105  * @return @c 0 on success,
 106  *         otherwise a negative error value
 107  * @retval #DEVICE_ERROR_NONE Successful
 108  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 109  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
 110  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 111  * @post The device will be in #DISPLAY_STATE_NORMAL state.
 112  */
 113 int device_power_wakeup(bool dim) TIZEN_DEPRECATED_API;
 114
 115
 116 /**
 117  * @platform
 118  * @brief Reboots the device.
 119  * @details Will not return if the reboot is successful. \n
 120  *          It operates asynchronously.
 121  * @since_tizen 2.3.1
 122  * @privlevel platform
 123  * @privilege %http://tizen.org/privilege/reboot
 124  * @param[in] reason Pass to the platform and kernel to request special reboot reason, or null
 125  * @return @c 0 on success,
 126  *         otherwise a negative error value
 127  * @retval #DEVICE_ERROR_NONE Successful
 128  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
 129  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
 130  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
 131  */
 132 int device_power_reboot(const char *reason);
 133
 134
 135 /**
 136  * @}
 137  */
 138
 139
 140 #ifdef __cplusplus
 141 }
 142 #endif
 143
 144
 145 #endif  // __TIZEN_SYSTEM_POWER_H__