4 * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: DongGi Jang <dg0402.jang@samsung.com>
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
23 #ifndef __POWER_MANAGER_LIBRARY_H__
24 #define __POWER_MANAGER_LIBRARY_H__
26 #include "pmapi_managed.h"
29 * @defgroup POWER_MANAGER Power manager library
30 * @ingroup SYSTEM_FRAMEWORK
31 * @brief Power manager control API library
34 * @addtogroup POWER_MANAGER
36 * This library provides APIs to lock/unlock the power state of the system.
37 * Power Manager controls the power state as following.
38 * @image html power-manager-fsm.bmp "Fig. 1 State Diagram of Power Manager
39 * <br> If there is no user input for a certain time, PM changes the power state
40 * that has lower power consumption. <br> When the user input or other system interrupt occurs,
41 * PM rolls the state back immediately.<br> If applications or other frameworks want to stop
42 * enter the specific state of power manager, use pm_lock_state() and pm_unlock_state()
43 * <br> Be careful! A caller process should unlock the power state after locking without timeout.
44 * <br> If you want to stay the LCD normal state, you can use
45 * @li @c pm_lock_state(LCD_NORMAL, GOTO_STATE_NOW, 0)
46 * <p><br> After finishing your job with locking, call
47 * @li @c pm_unlock_state(LCD_NORMAL, PM_RESET_TIMER)
48 * <p><br> Additionally, you can use the timeout for lock the state.
49 * If timeout is set, caller process doesn't need to call the unlock API.
50 * But the process should be alive.
51 * If caller process is dead, lock condition would be drop by the power manager.
52 * <p><br> Here is sample codes
56 int main(int argc, char** argv)
60 printf("=========================================\n");
61 printf("= Lock / Unlock to transit a power manager state =\n");
62 printf("=========================================\n");
64 result = pm_lock_state(LCD_NORMAL, GOTO_STATE_NOW,0); //Lock on lcd-off until explicit unlock.
72 result = pm_unlock_state(LCD_NORMAL,PM_RESET_TIMER); //Unlock
78 result = pm_lock_state(LCD_OFF,STAY_CUR_STATE, 5000); // Lock on lcd-off during 5 seconds.
97 #define LCD_NORMAL 0x1 /**< NORMAL state */
98 #define LCD_DIM 0x2 /**< LCD dimming state */
99 #define LCD_OFF 0x4 /**< LCD off state */
100 #define SUSPEND 0x8 /**< Sleep state */
101 #define POWER_OFF 0x16 /**< Sleep state */
102 #define SETALL (LCD_DIM | LCD_OFF | LCD_NORMAL) /*< select all state - not supported yet */
104 /* parameters for pm_lock_state() */
105 #define STAY_CUR_STATE 0x0
106 #define GOTO_STATE_NOW 0x1
107 #define HOLD_KEY_BLOCK 0x2
109 /* paramters for pm_unlcok_state() - details are described at 162 line */
110 #define PM_SLEEP_MARGIN 0x0 /**< keep guard time for unlock */
111 #define PM_RESET_TIMER 0x1 /**< reset timer for unlock */
112 #define PM_KEEP_TIMER 0x2 /**< keep timer for unlock */
115 * @fn int pm_lock_state (unsigned int state,
117 * unsigned int timeout);
118 * @brief This API is used to lock a particular power-state as the current power-state.\n
119 * The parameter state specifies the power state which you want to lock LCD_NORMAL, LCD_DIM, LCD_OFF. \n
120 * The second parameter Flag is set if you want to go the requested lock state directly.\n
121 * The third parameter timeout specifies lock-timeout in milliseconds.
122 * If the value 0 is selected, the power state remains locked until pm_unlock_state is called.
123 * @param[in] state target power state which you want to lock - LCD_NORMAL, LCD_DIM, LCD_OFF
124 * @param[in] flag set if you want to go the lock state directly
125 * GOTO_STATE_NOW - State is changed directly you want to lock.
126 * STAY_CUR_STATE - State is not changed directly and phone stay current state until timeout expired.
127 * (Default if there is no value in flag.)
128 * HOLD_KEY_BLOCK - Hold key is blocked during locking LCD_NORMAL or LCD_DIM.
129 * Then LCD state transition to LCD_OFF is blocked.
130 * If this flag is not set, phone state is lcd off after pressing hold key.
131 * GOTO_STATE_NOW and STAY_CUR_STATE can't be applied at the same time.
132 * @param[in] timeout lock-timeout in miliseconds.
133 * 0 is always lock until calling pm_unlock_state
134 * If you call this function with same state in duplicate,
135 * only last one will be processed and others are ignored.
136 * @return 0 on success, -1 if failed
137 * @see pm_unlock_state(), pm_change_state()
141 * // Lock current state as LCD_NORMAL
142 * result = pm_lock_state(LCD_NORMAL, GOTO_STATE_NOW, SET_TIMEOUT);
144 * printf("[ERROR] return value result =%d, \n",result);
146 * printf("[SUCCESS]return value result =%d \n",result);
150 int pm_lock_state(unsigned int, unsigned int, unsigned int);
153 * @fn int pm_unlock_state (unsigned int state,
155 * @brief This API is used to Unlock the power state. \n
156 * The parameter state specifies the power state which you want to unlock .
157 * Some examples are LCD_NORMAL, LCD_DIM, LCD_OFF.\n
158 * The second parameter flag is set if you want to go to the requested state directly after unlocking. (NOT SUPPOERTED YET)
159 * This is valid only when the current state transition was blocked by the locking and this function call releases the blocking.
160 * @param[in] state target power state which you want to unlock
161 * @param[in] flag set timer which is going to the next state after unlocking
162 * PM_SLEEP_MARGIN - If the current status is lcd off, pm reset timer to 5 second. If the current status is not lcd off, pm pm uses the existing timer.
163 * PM_RESET_TIMER - Power-manager resets timer. (lcd normal : reset timer to predfined value which is set in setting module, lcd dim or off : reset timer to 5 seconds)
164 * PM_KEEP_TIMER - Power-manager uses the existing timer (if timer is already expired, pm changes the status) <br>
165 * @return 0 on success, -1 if failed
166 * @see pn_lock_state(), pm_change_state()
170 * //Un-lock NORMAL state so that power state change can occur with system-events
171 * result = pm_unlock_state(LCD_NORMAL,PM_RESET_TIMER);
173 * printf("[ERROR] return value result =%d, \n",result);
175 * printf("[SUCCESS]return value result =%d \n",result);
179 int pm_unlock_state(unsigned int, unsigned int);
188 #endif /* __POWER_MANAGER_LIBRARY_H__ */