summaryrefslogtreecommitdiff
path: root/pmapi.h
diff options
context:
space:
mode:
authorKibum Kim <kb0929.kim@samsung.com>2012-02-27 12:16:23 (GMT)
committerKibum Kim <kb0929.kim@samsung.com>2012-02-27 12:16:23 (GMT)
commitb20978afef9aeac60c217b7d4ba02a87b8b95296 (patch)
tree6fcfd38b47191b8f89fa76ba491c047a717affc6 /pmapi.h
downloadlibslp-pm-b20978afef9aeac60c217b7d4ba02a87b8b95296.zip
libslp-pm-b20978afef9aeac60c217b7d4ba02a87b8b95296.tar.gz
libslp-pm-b20978afef9aeac60c217b7d4ba02a87b8b95296.tar.bz2
tizen beta release
Diffstat (limited to 'pmapi.h')
-rw-r--r--pmapi.h197
1 files changed, 197 insertions, 0 deletions
diff --git a/pmapi.h b/pmapi.h
new file mode 100644
index 0000000..fbd9c6c
--- /dev/null
+++ b/pmapi.h
@@ -0,0 +1,197 @@
+/*
+ * libslp-pm
+ *
+ * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
+ *
+ * Contact: DongGi Jang <dg0402.jang@samsung.com>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+
+
+#ifndef __POWER_MANAGER_LIBRARY_H__
+#define __POWER_MANAGER_LIBRARY_H__
+
+/**
+ * @defgroup POWER_MANAGER Power manager library
+ * @ingroup SYSTEM_FRAMEWORK
+ * @brief Power manager control API library
+ *
+ * @open
+ * @addtogroup POWER_MANAGER
+ * @{
+ * This library provides APIs to lock/unlock the power state of the system.
+ * Power Manager controls the power state as following.
+ * @image html power-manager-fsm.bmp "Fig. 1 State Diagram of Power Manager
+ * <br> If there is no user input for a certain time, PM changes the power state
+ * that has lower power consumption. <br> When the user input or other system interrupt occurs,
+ * PM rolls the state back immediately.<br> If applications or other frameworks want to stop
+ * enter the specific state of power manager, use pm_lock_state() and pm_unlock_state()
+ * <br> Be careful! A caller process should unlock the power state after locking without timeout.
+ * <br> If you want to stay the LCD normal state, you can use
+ * @li @c pm_lock_state(LCD_NORMAL, GOTO_STATE_NOW, 0)
+ * <p><br> After finishing your job with locking, call
+ * @li @c pm_unlock_state(LCD_NORMAL, PM_RESET_TIMER)
+ * <p><br> Additionally, you can use the timeout for lock the state.
+ * If timeout is set, caller process doesn't need to call the unlock API.
+ * But the process should be alive.
+ * If caller process is dead, lock condition would be drop by the power manager.
+ * <p><br> Here is sample codes
+ * @code
+
+#include "pmapi.h"
+int main(int argc, char** argv)
+{
+ int result;
+
+ printf("=========================================\n");
+ printf("= Lock / Unlock to transit a power manager state =\n");
+ printf("=========================================\n");
+
+ result = pm_lock_state(LCD_NORMAL, GOTO_STATE_NOW,0); //Lock on lcd-off until explicit unlock.
+ if (!result)
+ printf("SUCCESS");
+ else
+ printf("FAILED");
+
+ // DO something.
+
+ result = pm_unlock_state(LCD_NORMAL,PM_RESET_TIMER); //Unlock
+ if (!result)
+ printf("SUCCESS");
+ else
+ printf("FAILED");
+
+ result = pm_lock_state(LCD_OFF,STAY_CUR_STATE, 5000); // Lock on lcd-off during 5 seconds.
+ if (!result)
+ printf("SUCCESS");
+ else
+ printf("FAILED");
+
+ // DO something.
+ sleep(10);
+
+ return 0;
+}
+ * @endcode
+ *
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define LCD_NORMAL 0x1 /**< NORMAL state */
+#define LCD_DIM 0x2 /**< LCD dimming state */
+#define LCD_OFF 0x4 /**< LCD off state */
+#define SUSPEND 0x8 /**< Sleep state */
+#define POWER_OFF 0x16 /**< Sleep state */
+#define SETALL (LCD_DIM | LCD_OFF | LCD_NORMAL) /*< select all state - not supported yet */
+
+/* parameters for pm_lock_state() */
+#define GOTO_STATE_NOW 0x1
+#define STAY_CUR_STATE 0x0
+
+/* paramters for pm_unlcok_state() - details are described at 162 line */
+#define PM_SLEEP_MARGIN 0x0 /**< keep guard time for unlock */
+#define PM_RESET_TIMER 0x1 /**< reset timer for unlock */
+#define PM_KEEP_TIMER 0x2 /**< keep timer for unlock */
+
+/**
+ * @fn int pm_lock_state (unsigned int state,
+ * unsigned int flag,
+ * unsigned int timeout);
+ * @brief This API is used to lock a particular power-state as the current power-state.\n
+ * The parameter state specifies the power state which you want to lock LCD_NORMAL, LCD_DIM, LCD_OFF. \n
+ * The second parameter Flag is set if you want to go the requested lock state directly.\n
+ * The third parameter timeout specifies lock-timeout in milliseconds.
+ * If the value 0 is selected, the power state remains locked until pm_unlock_state is called.
+ * @param[in] state target power state which you want to lock - LCD_NORMAL, LCD_DIM, LCD_OFF
+ * @param[in] flag set if you want to go the lock state directly - GOTO_STATE_NOW, STAY_CUR_STATE
+ * @param[in] timeout lock-timeout in miliseconds.
+ * 0 is always lock until calling pm_unlock_state
+ * If you call this function with same state in duplicate,
+ * only last one will be processed and others are ignored.
+ * @return 0 on success, -1 if failed
+ * @see pm_unlock_state(), pm_change_state()
+ * @par Example
+ * @code
+ * ...
+ * // Lock current state as LCD_NORMAL
+ * result = pm_lock_state(LCD_NORMAL, GOTO_STATE_NOW, SET_TIMEOUT);
+ * if( result < 0 )
+ * printf("[ERROR] return value result =%d, \n",result);
+ * else
+ * printf("[SUCCESS]return value result =%d \n",result);
+ * ...
+ * @endcode
+ */
+ int pm_lock_state(unsigned int, unsigned int, unsigned int);
+
+/**
+ * @fn int pm_unlock_state (unsigned int state,
+ * unsigned int flag)
+ * @brief This API is used to Unlock the power state. \n
+ * The parameter state specifies the power state which you want to unlock .
+ * Some examples are LCD_NORMAL, LCD_DIM, LCD_OFF.\n
+ * The second parameter flag is set if you want to go to the requested state directly after unlocking. (NOT SUPPOERTED YET)
+ * This is valid only when the current state transition was blocked by the locking and this function call releases the blocking.
+ * @param[in] state target power state which you want to unlock
+ * @param[in] flag set timer which is going to the next state after unlocking
+ * 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.
+ * 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)
+ * PM_KEEP_TIMER - Power-manager uses the existing timer (if timer is already expired, pm changes the status) <br>
+ * @return 0 on success, -1 if failed
+ * @see pn_lock_state(), pm_change_state()
+ * @par Example
+ * @code
+ * ...
+ * //Un-lock NORMAL state so that power state change can occur with system-events
+ * result = pm_unlock_state(LCD_NORMAL,PM_RESET_TIMER);
+ * if( result < 0 )
+ * printf("[ERROR] return value result =%d, \n",result);
+ * else
+ * printf("[SUCCESS]return value result =%d \n",result);
+ * ...
+ * @endcode
+ */
+ int pm_unlock_state(unsigned int, unsigned int);
+
+/**
+ * @fn int pm_change_state(unsigned int state);
+ * @brief This API is used to change the power manager state by force.
+ * @param[in] state power manager state - LCD_NORMAL, LCD_DIM, LCD_OFF
+ * @return 0 on success, -1 if failed.
+ * @see pm_lock_state(), pm_unlock_state()
+ * @pat Example
+ * @code
+ * ...
+ * result = pm_change_state(LCD_OFF);
+ * if( result < 0 )
+ * printf("[ERROR] return value result =%d, \n",result);
+ * else
+ * printf("[SUCCESS]return value result =%d \n",result);
+ * ...
+ * @endcode
+ */
+ int pm_change_state(unsigned int);
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* __POWER_MANAGER_LIBRARY_H__ */