pmapi.h

   1 /*
   2  *  libslp-pm
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: DongGi Jang <dg0402.jang@samsung.com>
   7  *
   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
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  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.
  19  *
  20 */
  21
  22
  23 #ifndef __POWER_MANAGER_LIBRARY_H__
  24 #define __POWER_MANAGER_LIBRARY_H__
  25
  26 /**
  27  * @defgroup POWER_MANAGER Power manager library
  28  * @ingroup SYSTEM_FRAMEWORK
  29  * @brief Power manager control API library
  30  *
  31  * @open
  32  * @addtogroup POWER_MANAGER
  33  * @{
  34  * This library provides APIs to lock/unlock the power state of the system.
  35  * Power Manager controls the power state as following.
  36  * @image html power-manager-fsm.bmp "Fig. 1 State Diagram of Power Manager
  37  * <br> If there is no user input for a certain time, PM changes the power state
  38  *  that has lower power consumption. <br> When the user input or other system interrupt occurs,
  39  *  PM rolls the state back immediately.<br> If applications or other frameworks want to stop
  40  *  enter the specific state of power manager, use pm_lock_state() and pm_unlock_state()
  41  *  <br> Be careful! A caller process should unlock the power state after locking without timeout.
  42  *  <br> If you want to stay the LCD normal state, you can use
  43  *  @li @c pm_lock_state(LCD_NORMAL, GOTO_STATE_NOW, 0)
  44  *  <p><br> After finishing your job with locking, call
  45  *  @li @c pm_unlock_state(LCD_NORMAL, PM_RESET_TIMER)
  46  *  <p><br> Additionally, you can use the timeout for lock the state.
  47  *  If timeout is set, caller process doesn't need to call the unlock API.
  48  *  But the process should be alive.
  49  *  If caller process is dead, lock condition would be drop by the power manager.
  50  *  <p><br> Here is sample codes
  51  * @code
  52
  53 #include "pmapi.h"
  54 int main(int argc, char** argv)
  55 {
  56         int result;
  57
  58         printf("=========================================\n");
  59         printf("=  Lock / Unlock to transit a power manager state   =\n");
  60         printf("=========================================\n");
  61
  62         result = pm_lock_state(LCD_NORMAL, GOTO_STATE_NOW,0); //Lock on lcd-off until explicit unlock.
  63         if (!result)
  64                 printf("SUCCESS");
  65         else
  66                 printf("FAILED");
  67
  68         // DO something.
  69
  70         result = pm_unlock_state(LCD_NORMAL,PM_RESET_TIMER); //Unlock
  71         if (!result)
  72                 printf("SUCCESS");
  73         else
  74                 printf("FAILED");
  75
  76         result = pm_lock_state(LCD_OFF,STAY_CUR_STATE, 5000); // Lock on lcd-off during 5 seconds.
  77         if (!result)
  78                 printf("SUCCESS");
  79         else
  80                 printf("FAILED");
  81
  82         // DO something.
  83         sleep(10);
  84
  85         return 0;
  86 }
  87  * @endcode
  88  *
  89  */
  90
  91 #ifdef __cplusplus
  92 extern "C" {
  93 #endif
  94
  95 #define LCD_NORMAL      0x1   /**< NORMAL state */
  96 #define LCD_DIM         0x2  /**< LCD dimming state */
  97 #define LCD_OFF         0x4  /**< LCD off state */
  98 #define SUSPEND         0x8  /**< Sleep state */
  99 #define POWER_OFF       0x16  /**< Sleep state */
 100 #define SETALL (LCD_DIM | LCD_OFF | LCD_NORMAL) /*< select all state - not supported yet */
 101
 102 /* parameters for pm_lock_state() */
 103 #define STAY_CUR_STATE  0x0
 104 #define GOTO_STATE_NOW  0x1
 105 #define HOLD_KEY_BLOCK  0x2
 106
 107 /* paramters for pm_unlcok_state() - details are described at 162 line */
 108 #define PM_SLEEP_MARGIN 0x0     /**< keep guard time for unlock */
 109 #define PM_RESET_TIMER  0x1     /**< reset timer for unlock */
 110 #define PM_KEEP_TIMER   0x2     /**< keep timer for unlock */
 111
 112 /**
 113  * @fn int pm_lock_state        (unsigned int state,
 114  *                                                       unsigned int flag,
 115  *                                                       unsigned int timeout);
 116  * @brief This API is used to lock a particular power-state as the current power-state.\n
 117  *              The parameter state specifies the power state which you want to lock LCD_NORMAL, LCD_DIM, LCD_OFF. \n
 118  *              The second parameter Flag is set if you want to go the requested lock state directly.\n
 119  *              The third parameter timeout specifies lock-timeout in milliseconds.
 120  *              If the value 0 is selected, the power state remains locked until pm_unlock_state is called.
 121  * @param[in] state target power state which you want to lock - LCD_NORMAL, LCD_DIM, LCD_OFF
 122  * @param[in] flag set if you want to go the lock state directly
 123  *              GOTO_STATE_NOW - State is changed directly you want to lock.
 124  *              STAY_CUR_STATE - State is not changed directly and phone stay current state until timeout expired.
 125  *                               (Default if there is no value in flag.)
 126  *              HOLD_KEY_BLOCK - Hold key is blocked during locking LCD_NORMAL or LCD_DIM.
 127  *                               Then LCD state transition to LCD_OFF is blocked.
 128  *                               If this flag is not set, phone state is lcd off after pressing hold key.
 129  *              GOTO_STATE_NOW and STAY_CUR_STATE can't be applied at the same time.
 130  * @param[in] timeout lock-timeout in miliseconds.
 131  *                                        0 is always lock until calling pm_unlock_state
 132  *                                        If you call this function with same state in duplicate,
 133  *                                        only last one will be processed and others are ignored.
 134  * @return 0 on success, -1 if failed
 135  * @see pm_unlock_state(), pm_change_state()
 136  * @par Example
 137  * @code
 138  *      ...
 139  *      // Lock current state as LCD_NORMAL
 140  *      result = pm_lock_state(LCD_NORMAL, GOTO_STATE_NOW, SET_TIMEOUT);
 141  *      if( result < 0 )
 142  *              printf("[ERROR] return value result =%d, \n",result);
 143  *      else
 144  *              printf("[SUCCESS]return value result =%d \n",result);
 145  *      ...
 146  * @endcode
 147  */
 148         int pm_lock_state(unsigned int, unsigned int, unsigned int);
 149
 150 /**
 151  * @fn int pm_unlock_state      (unsigned int state,
 152  *                                                       unsigned int flag)
 153  * @brief This API is used to Unlock the power state. \n
 154  *              The parameter state specifies the power state which you want to unlock .
 155  *              Some examples are LCD_NORMAL, LCD_DIM, LCD_OFF.\n
 156  *              The second parameter flag is set if you want to go to the requested state directly after unlocking. (NOT SUPPOERTED YET)
 157  *              This is valid only when the current state transition was blocked by the locking and this function call releases the blocking.
 158  * @param[in] state target power state which you want to unlock
 159  * @param[in] flag set timer which is going to the next state after unlocking
 160  *              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.
 161  *              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)
 162  *              PM_KEEP_TIMER - Power-manager uses the existing timer (if timer is already expired, pm changes the status) <br>
 163  * @return 0 on success, -1 if failed
 164  * @see pn_lock_state(), pm_change_state()
 165  * @par Example
 166  * @code
 167  *      ...
 168  *      //Un-lock NORMAL state so that power state change can occur with system-events
 169  *      result = pm_unlock_state(LCD_NORMAL,PM_RESET_TIMER);
 170  *      if( result < 0 )
 171  *              printf("[ERROR] return value result =%d, \n",result);
 172  *      else
 173  *              printf("[SUCCESS]return value result =%d \n",result);
 174  *      ...
 175  * @endcode
 176  */
 177         int pm_unlock_state(unsigned int, unsigned int);
 178
 179 /**
 180  * @fn int pm_change_state(unsigned int state);
 181  * @brief This API is used to change the power manager state by force.
 182  * @param[in] state power manager state - LCD_NORMAL, LCD_DIM, LCD_OFF
 183  * @return 0 on success, -1 if failed.
 184  * @see pm_lock_state(), pm_unlock_state()
 185  * @pat Example
 186  * @code
 187  *      ...
 188  *      result = pm_change_state(LCD_OFF);
 189  *      if( result < 0 )
 190  *              printf("[ERROR] return value result =%d, \n",result);
 191  *      else
 192  *              printf("[SUCCESS]return value result =%d \n",result);
 193  *      ...
 194  * @endcode
 195  */
 196         int pm_change_state(unsigned int);
 197
 198 /**
 199  * @}
 200  */
 201
 202 #ifdef __cplusplus
 203 }
 204 #endif
 205 #endif                          /* __POWER_MANAGER_LIBRARY_H__ */