public final class Intents

True when this platform can expose intents to the system.

False does not make the API useless: invoke still runs your handlers in-process on every platform, because the dispatch table is generated code rather than a platform service. Only the projections outward – voice, search indexing, shortcuts – go quiet.

True when a voice assistant can invoke intents here.

This is the honest discriminator between the platforms. Branch on it rather than on areIntentsSupported() when deciding whether to tell a user they can talk to your app.

Every intent this application declares, from the build-time table and from registerDynamicIntent.

The simulator’s Intents window is built from exactly this list, which is what makes it trustworthy: it can only show what actually shipped.

Declares a parameterization of an intent the application already declares – a specific shortcut such as “reorder my usual”, built from data only known once the app is running.

It runs by running the intent it names, with the bound values filled in, which is what makes it invokable at all. It cannot introduce a new capability: the native catalogue is compiled into the app, so a genuinely new verb could never reach the platform.

Ignored when the base intent is not declared, or when the id would shadow a declared one.

The parameterization registered under this id, or null when the id is a build-time declaration or nothing at all.

Ports need this to resolve a donation: a shortcut outlives the process while a parameterization does not, so the shortcut has to record the base intent and the bound values rather than a runtime id nothing will recognise later.

Runs an intent on the calling thread and returns its result.

This is the in-app path – your own code deciding to perform one of its declared capabilities – and it works on every platform, including those with no intent support at all, because the dispatch table is generated code rather than a platform service.

Platform-initiated invocations do not come through here; they arrive at dispatchInvocation, which adds thread marshalling and an enforced deadline.

The deadline on this path is a budget the handler may consult, not a cutoff: your own thread is blocked in this call, nothing else is waiting to report an outcome, and a handler that overruns has still done the work and produced the answer you asked for. So a late result is returned rather than discarded. Discarding is the right behaviour under dispatchInvocation, where the framework has already told the platform the invocation failed and a second answer would be a protocol violation.

Framework/port entry point: runs an intent the platform asked for and reports the outcome exactly once.

Ports call this after decoding their platform payload. It owns everything the ports should not each reinvent: queuing across a cold start, running the handler off the event dispatch thread, enforcing the deadline, and guaranteeing the completion fires once and only once.

Overrides how long a handler may run before the framework gives up, for intents that did not state their own budget.

Raising this is rarely the right fix. The platform’s patience is not the constraint that matters – a spoken interaction that takes ten seconds has already failed as an interaction. An intent that genuinely needs longer should return IntentResult.opens and do the work in the app.

Tells the system the user just performed this capability, so it can suggest or predict it later.

Donate when the user does the thing in your app by hand. That is the signal the system learns from; donating on every intent invocation teaches it only that the user uses shortcuts.

Callable from any thread. A no-op where unsupported.

Publishes app content to the device’s search index, replacing any entry carrying the same type and id.

Threading

A background thread is the right thread, not merely a permitted one. This writes through to the platform index and encodes any thumbnails on the way, so calling it on the event dispatch thread looks instantaneous in the simulator and stalls the UI on a device.

Removes one entry from the search index.

Removal matters more than it looks. An index entry outlives the data behind it, so content the user deleted keeps appearing in device search and taps resolve to nothing until the app removes it.

Runs one of an entity type’s declared queries.

The platform calls this on its own when it has to disambiguate a parameter – “which playlist?” – and the simulator calls it to populate its picker, which is why the simulator exercises the real query rather than a stand-in.

The intents that opted into Exposure.MODEL, projected down to com.codename1.ai.Tool so they can be handed to a language model or an MCP host.

Nothing is exposed by calling this. It returns descriptions; the application decides whether to give them to a model, which is deliberately a separate act from declaring the intent, because a model calls a capability because it inferred it should rather than because a person asked by name.

The projection is one-way and lossy on purpose. A Tool is stringly typed – a JSON schema in, a JSON string out – which is right for a model and wrong for the platform, where entity types let the system run its own picker before the handler is reached. So the richer declaration projects down to the weaker one, never the reverse.

Registers the single handler that receives taps on content published with index.

Registration drains anything that arrived before it, which is the normal case: a tap in device search is frequently what started the process, so the selection is already waiting by the time your init() runs.

Framework/port entry point: a platform activity arrived that is not a web link. Returns true when this application claimed it.

Answering honestly matters. Claiming everything would swallow handoff and third-party activities the app never declared, so an activity is claimed only when its type names an intent this application actually declares – which is the shape the platform uses to continue a donated action.

Framework/port entry point: resolves the platform bridge, which publishes any declarations that were installed before one existed.

The generated bootstrap installs the dispatcher before the port has booted – from main() on iOS, and before startContext on Android – so the first publication finds no bridge and is deferred. Something has to ask for the bridge afterwards or the platform never learns the catalogue, and on Android a request parked at a cold start is never judged, so the shortcut opens the app and runs nothing.

Ports call this once the runtime is up. It is safe to call at any time and does nothing when there is nothing owed.