Requests

A Request is something your config answers: a keyring or GPG prompt, a polkit authentication, a location authorization or a session-lock request. The event that offers it carries it as event.request. Follow-up events of the same request carry the same object.

gnoblin.on("gnoblin.prompt.requested", function(event)
    local request = event.request
    request:finished():on_complete(function(outcome)
        print(request.kind, request.id, outcome)
    end)
    request:cancel()
end)

This handler cancels every keyring and GPG prompt and prints the outcome when each one ends.

Fields

Every request has these fields. All fields are read-only.

A request also has the detail fields of the event that offered it, such as title for a prompt or app_id for location. The page for each kind lists them.

status starts as "pending". It becomes "claimed" after claim(), "answered" after answer() or cancel(), and "finished" when the request ends for any reason.

Kinds

• "password" asks for a password and "confirm" asks for a yes or no answer. See Keyring and GPG prompts.
• "authentication" asks for a polkit password. See Authentication prompts.
• "location" asks whether an application may use location. See Privacy.
• "lock" asks the shell to start its locker. It takes no answer. It finishes with locked when the session locks, or timeout after 30 seconds. See Session lock.

Methods

A method exists only on the kinds that use it. Calling it on another kind raises an error that names the kind and the method.

on takes these signals:

• "prompt" and "message" of an authentication request call fn(request) for each.
• "closed", on every kind, calls fn(request, reason) when a config reload or the worker's shutdown takes the runtime away before the request is finished. The reason is "config_reloaded" or "runtime_stopped".

A request that finishes does not raise "closed"; use finished() for that.

answer takes these arguments:

choice is the state of a prompt's optional checkbox. For location, accuracy defaults to the requested accuracy when allow is true. cancel() on a location request denies it.

answer, cancel and claim return an Operation that succeeds with {request_id = ..., submitted = true} after Gnoblin accepts the answer. An answer with wrong values fails that Operation with a message that names the problem. A request takes one answer; a second answer fails.

Answer from a shell process

A socket client does not get Request objects. It receives the same events with request_id and answers with the wire methods that each kind's page lists. Only the client that received the event can answer that request.