Skip to content

Latest commit

 

History

History
238 lines (180 loc) · 6.73 KB

DesktopAgent.md

File metadata and controls

238 lines (180 loc) · 6.73 KB
id sidebar_label title hide_title original_id
version-1.0-beta-DesktopAgent
DesktopAgent
DesktopAgent
true
DesktopAgent

DesktopAgent

A Desktop Agent is a desktop component (or aggregate of components) that serves as a launcher and message router (broker) for applications in its domain.

A Desktop Agent can be connected to one or more App Directories and will use directories for application identity and discovery. Typically, a Desktop Agent will contain the proprietary logic of a given platform, handling functionality like explicit application interop workflows where security, consistency, and implementation requirements are proprietary.

Methods

open

open(name: string, context?: Context): Promise<void>;

Launches/links to an app by name.

If a Context object is passed in, this object will be provided to the opened application via a contextListener. The Context argument is functionally equivalent to opening the target app with no context and broadcasting the context directly to it. If opening errors, it returns an Error with a string from the OpenError enumeration.

Example

//no context
await agent.open('myApp');

//with context
await agent.open('myApp', context);

See also

findIntent

findIntent(intent: string, context?: Context): Promise<AppIntent>;

Find out more information about a particular intent by passing its name, and optionally its context.

findIntent is effectively granting programmatic access to the Desktop Agent's resolver. A promise resolving to the intent, its metadata and metadata about the apps that registered it is returned. This can be used to raise the intent against a specific app.

If the resolution fails, the promise will return an Error with a string from the ResolveError enumeration.

Examples

// I know 'StartChat' exists as a concept, and want to know more about it ...
const appIntent = await agent.findIntent("StartChat");
// returns a single AppIntent:
// {
//     intent: { name: "StartChat", displayName: "Chat" },
//     apps: [{ name: "Skype" }, { name: "Symphony" }, { name: "Slack" }]
// }

// raise the intent against a particular app
await agent.raiseIntent(appIntent.intent.name, context, appIntent.apps[0].name);

See also

findIntentsByContext

findIntentsByContext(context: Context): Promise<Array<AppIntent>>;

Find all the avalable intents for a particular context. findIntentsByContext is effectively granting programmatic access to the Desktop Agent's resolver. A promise resolving to all the intents, their metadata and metadata about the apps that registered it is returned, based on the context types the intents have registered.

If the resolution fails, the promise will return an Error with a string from the ResolveError enumeration.

Examples

// I have a context object, and I want to know what I can do with it, hence, I look for for intents...
const appIntents = await agent.findIntentsForContext(context);

// returns for example:
// [{
//     intent: { name: "StartCall", displayName: "Call" },
//     apps: [{ name: "Skype" }]
// },
// {
//     intent: { name: "StartChat", displayName: "Chat" },
//     apps: [{ name: "Skype" }, { name: "Symphony" }, { name: "Slack" }]
// }];

// select a particular intent to raise
const startChat = appIntents[1];

// target a particular app
const selectedApp = startChat.apps[0];

// raise the intent, passing the given context, targeting the app
await agent.raiseIntent(startChat.intent.name, context, selectedApp.name);

See also

broadcast

broadcast(context: Context): void;

Publishes context to other apps on the desktop.

Examples

agent.broadcast(context);

See also

raiseIntent

raiseIntent(intent: string, context: Context, target?: string): Promise<IntentResolution>;

Raises an intent to the desktop agent to resolve.

Examples

//raise an intent to start a chat with a given contact
const intentR = await agent.findIntents("StartChat", context);
//use the IntentResolution object to target the same chat app with a new context
agent.raiseIntent("StartChat", newContext, intentR.source);

See also

addIntentListener

addIntentListener(intent: string, handler: (context: Context) => void): Listener;

Adds a listener for incoming Intents from the Agent.

See also

addContextListener

addContextListener(handler: (context: Context) => void): Listener;

Adds a listener for incoming context broadcast from the Desktop Agent.

See also

Return Types

AppIntent

interface AppIntent {
  intent: IntentMetadata;
  apps: Array<AppMetadata>;
}

An interface that represents the binding of an intent to apps

See also

IntentMetadata

interface IntentMetadata {
  name: string;
  displayName: string;
}

The Interface used to describe an Intent within the platform.

AppMetadata

interface AppMetadata {
  name: string;
}

App metadata is Desktop Agent specific - but should always support a name property.

IntentResolution

interface IntentResolution {
  source: string;
  data?: object;
  version: string;
}

IntentResolution provides a standard format for data returned upon resolving an intent.

Example

//resolve a "Chain" type intent
var intentR = await agent.raiseIntent("intentName", context);
//resolve a "Client-Service" type intent with data response
var intentR = await agent.raiseIntent("intentName", context);
var dataR = intentR.data;

See also

Listener

interface Listener {
  unsubscribe();
}

A Listener object is returned when an application subscribes to intents or context broadcasts via the addIntentListener or addContextListener methods on the DesktopAgent object. The unsubscribe method on the listener object allows the application to cancel the subscription.

See also