Skip to main content
Version: Next

Types

FDC3 API operations make use of several type declarations.

AppIdentifier​

Identifies an application, or instance of an application, and is used to target FDC3 API calls at specific applications. Will always include at least an appId property, which can be used with fdc3.open, fdc3.raiseIntent etc.. If the instanceId field is set then the AppIdentifier object represents a specific instance of the application that may be addressed using that Id.

interface AppIdentifier {
  /** The unique application identifier located within a specific application
   *  directory instance. An example of an appId might be 'app@sub.root'.
   */
  readonly appId: string;
  
  /** An optional instance identifier, indicating that this object represents a
   *  specific instance of the application described.
   */
  readonly instanceId?: string;

  /** The Desktop Agent that the app is available on. Used in Desktop Agent 
   *  Bridging to identify the Desktop Agent to target.
   *  @experimental
   **/
  readonly desktopAgent?: string;
}

See also:

Context​

interface Context {
  id?: { [key: string]: string };
  name?: string;
  type: string;
}

The base interface that all contexts should extend: a context data object adhering to the FDC3 Context Data specification.

This means that it must at least have a type property that indicates what type of data it represents, e.g. 'fdc3.contact'. The type property of context objects is important for certain FDC3 operations, like Channel.getCurrentContext and DesktopAgent.addContextListener, which allows you to filter contexts by their type.

See also:

ContextHandler​

type ContextHandler = (context: Context, metadata?: ContextMetadata) => void;

Describes a callback that handles a context event. Optional metadata about the context message, including the app that originated the message, may be provided.

Used when attaching listeners for context broadcasts.

Optional metadata about the context message, including the app that originated the message, SHOULD be provided by the desktop agent implementation.

See also:

DesktopAgentIdentifier​

/** @experimental */
interface DesktopAgentIdentifier {
  /** Used in Desktop Agent Bridging to attribute or target a message to a 
   *  particular Desktop Agent.**/
  readonly desktopAgent: string;
}

(Experimental) Identifies a particular Desktop Agent in Desktop Agent Bridging scenarios where a request needs to be directed to a Desktop Agent rather than a specific app, or a response message is returned by the Desktop Agent (or more specifically its resolver) rather than a specific app. Used as a substitute for AppIdentifier in cases where no app details are available or are appropriate.

See also:

IntentHandler​

type IntentHandler = (context: Context, metadata?: ContextMetadata) => Promise<IntentResult> | void;

Describes a callback that handles a context event and may return a promise of a Context, Channel object or void to be returned to the application that raised the intent.

Used when attaching listeners for raised intents.

Optional metadata about the intent & context message, including the app that originated the message, SHOULD be provided by the desktop agent implementation.

See also:

IntentResult​

type IntentResult = Context | Channel | void;

Describes results that an Intent handler may return that should be communicated back to the app that raised the intent, via the IntentResolution.

Represented as a union type in TypeScript, however, this type may be rendered as an interface in other languages that both the Context and Channel types implement, allowing either to be returned by an IntentHandler.

See also:

Listener​

A Listener object is returned when an application subscribes to intents or context broadcasts via the addIntentListener or addContextListener methods on the DesktopAgent object.

interface Listener {
  unsubscribe(): void;
}

unsubscribe​

unsubscribe(): void;

Allows an application to unsubscribe from listening to intents or context broadcasts.

See also:

Last updated on by Kris West