# hs.caffeinate

Control system power states (sleeping, preventing sleep, screen locking, etc)

**NOTE**: Any sleep preventions will be removed when hs.reload() is called. A future version of the module will save/restore state across reloads.

---

## Submodules
 * [hs.caffeinate.watcher](hs.caffeinate.watcher.md)

---

## API Overview
**Functions** - _API calls offered directly by the extension_
 * [currentAssertions](#currentassertions)
 * [declareUserActivity](#declareuseractivity)
 * [fastUserSwitch](#fastuserswitch)
 * [get](#get)
 * [lockScreen](#lockscreen)
 * [logOut](#logout)
 * [restartSystem](#restartsystem)
 * [sessionProperties](#sessionproperties)
 * [set](#set)
 * [shutdownSystem](#shutdownsystem)
 * [startScreensaver](#startscreensaver)
 * [systemSleep](#systemsleep)
 * [toggle](#toggle)

---

## API Documentation

#### Functions

### [currentAssertions](#currentassertions)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.currentAssertions()`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Fetches information about processes which are currently asserting display/power sleep restrictions                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>A table containing information about current power assertions, with process IDs (PID) as the keys, each of which may contain multiple assertions</li></ul>          |
| **Notes**                                   | None |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/libcaffeinate.m line 296](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/libcaffeinate.m#L296) |

---

### [declareUserActivity](#declareuseractivity)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.declareUserActivity([id])`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Informs the OS that the user performed some activity                                                                     |
| **Parameters**                              | <ul><li>id - An option number containing the assertion ID returned by a previous call of this function</li></ul> |
| **Returns**                                 | <ul><li>A number containing the ID of the assertion generated by this function</li></ul>          |
| **Notes**                                   | <ul><li>This is intended to simulate user activity, for example to prevent displays from sleeping, or to wake them up</li><li>It is not mandatory to re-use assertion IDs if you are calling this function multiple times, but it is recommended that you do so if the calls are related</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/libcaffeinate.m line 209](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/libcaffeinate.m#L209) |

---

### [fastUserSwitch](#fastuserswitch)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.fastUserSwitch()`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Show the Fast User Switch screen (ie a login screen without logging out first)                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | None |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/caffeinate.lua line 109](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/caffeinate.lua#L109) |

---

### [get](#get)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.get(sleepType) -> bool or nil`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Queries whether a particular sleep type is being prevented                                                                     |
| **Parameters**                              | <ul><li>sleepType - A string containing the type of sleep to inspect (see [hs.caffeinate.set()](#set) for information about the possible values)</li></ul> |
| **Returns**                                 | <ul><li>True if the specified type of sleep is being prevented, false if not. nil if sleepType was an invalid value</li></ul>          |
| **Notes**                                   | None |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/caffeinate.lua line 55](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/caffeinate.lua#L55) |

---

### [lockScreen](#lockscreen)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.lockScreen()`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Locks the displays                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | <ul><li>This function uses private Apple APIs and could therefore stop working in any given release of macOS without warning.</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/libcaffeinate.m line 237](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/libcaffeinate.m#L237) |

---

### [logOut](#logout)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.logOut()`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Request the system log out the current user                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | None |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/caffeinate.lua line 135](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/caffeinate.lua#L135) |

---

### [restartSystem](#restartsystem)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.restartSystem()`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Request the system reboot                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | None |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/caffeinate.lua line 148](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/caffeinate.lua#L148) |

---

### [sessionProperties](#sessionproperties)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.sessionProperties()`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Fetches information from the display server about the current session                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>A table containing information about the current session, or nil if an error occurred</li></ul>          |
| **Notes**                                   | <ul><li>The keys in this dictionary will vary based on the current state of the system (e.g. local vs VNC login, screen locked vs unlocked).</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/libcaffeinate.m line 271](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/libcaffeinate.m#L271) |

---

### [set](#set)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.set(sleepType, aValue, acAndBattery)`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Configures the sleep prevention settings                                                                     |
| **Parameters**                              | <ul><li>sleepType - A string containing the type of sleep to be configured. The value should be one of:
  displayIdle - Controls whether the screen will be allowed to sleep (and also the system) if the user is idle.
  systemIdle - Controls whether the system will be allowed to sleep if the user is idle (display may still sleep).
  system - Controls whether the system will be allowed to sleep for any reason.</li><li>aValue - A boolean, true if the specified type of sleep should be prevented, false if it should be allowed</li><li>acAndBattery - A boolean, true if the sleep prevention should apply to both AC power and battery power, false if it should only apply to AC power.</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | <ul><li>These calls are not guaranteed to prevent the system sleep behaviours described above. The OS may override them if it feels it must (e.g. if your CPU temperature becomes dangerously high).</li><li>The acAndBattery argument only applies to the `system` sleep type.</li><li>You can toggle the acAndBattery state by calling `hs.caffeinate.set()` again and altering the acAndBattery value.</li><li>The acAndBattery option does not appear to work anymore - it is based on private API that is not allowed in macOS 10.15 when running with the Hardened Runtime (which Hammerspoon now uses).</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/caffeinate.lua line 11](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/caffeinate.lua#L11) |

---

### [shutdownSystem](#shutdownsystem)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.shutdownSystem()`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Request the system log out and power down                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | None |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/caffeinate.lua line 161](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/caffeinate.lua#L161) |

---

### [startScreensaver](#startscreensaver)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.startScreensaver()`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Request the system start the screensaver (which may lock the screen if the OS is configured to do so)                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | None |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/caffeinate.lua line 122](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/caffeinate.lua#L122) |

---

### [systemSleep](#systemsleep)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.systemSleep()`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Requests the system to sleep immediately                                                                     |
| **Parameters**                              | <ul><li>None</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | None |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/libcaffeinate.m line 193](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/libcaffeinate.m#L193) |

---

### [toggle](#toggle)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `hs.caffeinate.toggle(sleepType) -> bool or nil`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Toggles the current state of the specified type of sleep                                                                     |
| **Parameters**                              | <ul><li>sleepType - A string containing the type of sleep to toggle (see [hs.caffeinate.set()](#set) for information about the possible values)</li></ul> |
| **Returns**                                 | <ul><li>True if the specified type of sleep is being prevented, false if not. nil if sleepType was an invalid value</li></ul>          |
| **Notes**                                   | <ul><li>If systemIdle is toggled to on, it will apply to AC only</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [extensions/caffeinate/caffeinate.lua line 82](https://github.com/CommandPost/CommandPost-App/blob/master/extensions/caffeinate/caffeinate.lua#L82) |

---

---

<script src="https://giscus.app/client.js"
        data-repo="CommandPost/CommandPost"
        data-repo-id="MDEwOlJlcG9zaXRvcnk3NDY0NTk2NQ=="
        data-category="Website Discussion"
        data-category-id="DIC_kwDOBHMBzc4CXFFA"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="dark"
        data-lang="en"
        crossorigin="anonymous"
        async>
</script>