app.wakelock - Sleep Prevention API

Prevent system sleep using IOKit power assertions.

Methods

app.wakelock.preventSleep(config?)

Create a sleep prevention assertion.

Parameters:

• config (table, optional):
  • type (string) - assertion type:
    • "idle" (default) - prevent idle sleep
    • "display" - prevent display sleep
    • "system" - prevent system sleep
  • reason (string) - reason description (default “Plugin requested sleep prevention”)
  • duration (number) - duration in seconds, automatically released when expired

Returns: string, error - assertion ID

-- Prevent idle sleep (no time limit)
local id, err = app.wakelock.preventSleep()

-- Prevent display sleep for 30 minutes
local id = app.wakelock.preventSleep({
    type = "display",
    reason = "Long-running task in progress",
    duration = 1800
})

-- Prevent system sleep for 1 hour
local id = app.wakelock.preventSleep({
    type = "system",
    duration = 3600
})

app.wakelock.release(id)

Release a specific assertion.

Parameters:

• id (string) - assertion ID

Returns: boolean, error

local ok, err = app.wakelock.release(id)

app.wakelock.releaseAll()

Release all assertions for the current plugin.

Returns: boolean

app.wakelock.releaseAll()

app.wakelock.list()

List active assertions for the current plugin.

Returns: array<table> - each item contains:

• id (string) - assertion ID
• type (string) - type
• reason (string) - reason
• createdAt (string) - creation time (ISO 8601)

local assertions = app.wakelock.list()
for _, a in ipairs(assertions) do
    app.log.info(a.id .. ": " .. a.type .. " - " .. a.reason)
end

Description

• Assertions are automatically released when the plugin is unloaded
• When duration is specified, the assertion is released automatically; no need to call release() manually
• "idle" type is the most common: prevents the system from sleeping automatically when the user is inactive
• "display" type also prevents the display from turning off

Examples

Prevent Sleep During Long Tasks

function MyPlugin:handleLongTask(context)
    -- Prevent sleep before starting the task
    local cafId = app.wakelock.preventSleep({
        type = "idle",
        reason = "Processing files"
    })

    app.progress.show("Processing", {message = "Processing..."})

    -- Execute long-running task
    for i, file in ipairs(context.selectedFiles) do
        app.progress.update(i / #context.selectedFiles * 100)
        -- ... process file ...
    end

    app.progress.hide()

    -- Release after task completion
    if cafId then
        app.wakelock.release(cafId)
    end

    app.notification.show("Done", "Processed " .. #context.selectedFiles .. " files")
end