Update PowerSaveBlocker APIs design.

This commit is contained in:
Haojian Wu 2015-06-22 10:23:58 +08:00
parent 7ee2a703d9
commit 532f75fcab
3 changed files with 95 additions and 28 deletions

View file

@ -1,37 +1,49 @@
# power-save-blocker
The `power-save-blocker` module is used to block the system from entering
low-power(sleep) mode.
low-power(sleep) mode, allowing app to keep system and screen active.
An example is:
```javascript
var powerSaveBlocker = require('power-save-blocker');
powerSaveBlocker.start(powerSaveBlocker.PREVENT_DISPLAY_SLEEP);
console.log(powerSaveBlocker.IsStarted());
var id = powerSaveBlocker.start(powerSaveBlocker.PREVENT_DISPLAY_SLEEP);
console.log(powerSaveBlocker.isStarted(id));
powerSaveBlocker.stop(id);
```
## powerSaveBlocker.start(type)
* type - Power save blocker type
* `type` - Power save blocker type
* powerSaveBlocker.PREVENT_APP_SUSPENSION - Prevent the application from being
suspended. On some platforms, apps may be suspended when they are not visible
to the user. This type of block requests that the app continue to run in that
case,and on all platforms prevents the system from sleeping.
suspended. Keeps system active, but allows screen to be turned off.
Example use cases: downloading a file, playing audio.
* powerSaveBlocker.PREVENT_DISPLAY_SLEEP - Prevent the display from going to sleep.
This also has the side effect of preventing the system from sleeping, but
does not necessarily prevent the app from being suspended on some platforms
if the user hides it.
Keeps system and screen active.
Example use case: playing video.
Starts the power save blocker preventing the system entering lower-power mode.
Returns an integer identified the power save blocker.
## powerSaveBlocker.isStarted()
**Note:**
`PREVENT_DISPLAY_SLEEP` has higher precedence level than `PREVENT_APP_SUSPENSION`.
Only the highest precedence type takes effect. In other words, `PREVENT_DISPLAY_SLEEP`
always take precedence over `PREVENT_APP_SUSPENSION`.
Returns whether the `powerSaveBlocker` starts.
For example, an API calling A requests for `PREVENT_APP_SUSPENSION`, and
another calling B requests for `PREVENT_DISPLAY_SLEEP`. `PREVENT_DISPLAY_SLEEP`
will be used until B stops its request. After that, `PREVENT_APP_SUSPENSION` is used.
## powerSaveBlocker.stop()
## powerSaveBlocker.stop(id)
Stops blocking the system from entering low-power mode.
* `id` Integer - The power save blocker id returned by `powerSaveBlocker.start`.
Stops the specified power save blocker.
## powerSaveBlocker.isStarted(id)
* `id` Integer - The power save blocker id returned by `powerSaveBlocker.start`.
Returns whether the corresponding `powerSaveBlocker` starts.