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.

TypeScript/JavaScript

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;
}

.NET

interface IAppIdentifier
{
    /// <summary>
    /// The unique application identifier located within a specific application directory instance. An example of an appId might be 'app@sub.root'.
    /// </summary>
    string AppId { get; }

    /// <summary>
    /// An optional instance identifier, indicating that this object represents a specific instance of the application described.
    /// </summary>
    string? InstanceId { get; }
}

See also:

• AppMetadata
• DesktopAgent.open
• DesktopAgent.raiseIntent
• DesktopAgent.raiseIntentForContext
• IntentResolution

Context

TypeScript/JavaScript

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

.NET

interface IContext<out T>: IIntentResult, IDynamicContext where T : class
{
    T? ID { get; }
    string? Name { get; }
    string Type { get; }
}

interface IContext : IContext<object>
{
}

interface IDynamicContext
{
    /// <summary>
    /// Underlying message as a dynamic type for accessing all properties without deserialization
    /// </summary>
    dynamic? Native { get; set; }
}

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
• DesktopAgent.open
• DesktopAgent.broadcast
• DesktopAgent.addIntentListener
• DesktopAgent.addContextListener
• DesktopAgent.findIntent
• DesktopAgent.findIntentsByContext
• DesktopAgent.raiseIntent
• DesktopAgent.raiseIntentForContext
• Channel.broadcast
• Channel.getCurrentContext
• Channel.addContextListener

ContextHandler

TypeScript/JavaScript

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

.NET

delegate void ContextHandler<T>(T context, IContextMetadata? metadata = null) where T : IContext;

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:

• Context
• ContextMetadata
• DesktopAgent.addContextListener
• Channel.addContextListener

DesktopAgentIdentifier

TypeScript/JavaScript

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

.NET

Not implemented

(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:

• Agent Bridging - Identifying Desktop Agents Identity and Message Sources

IntentHandler

TypeScript/JavaScript

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

.NET

delegate Task<IIntentResult> IntentHandler<T>(T context, IContextMetadata? metadata = null) where T : IContext;

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:

• Context
• ContextMetadata
• PrivateChannel
• DesktopAgent.addIntentListener
• Channel.addContextListener

IntentResult

TypeScript/JavaScript

type IntentResult = Context | Channel | void;

.NET

interface IIntentResult { /* Marker interface implemented by IContext and Channel */ }

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:

• Context
• Channel
• PrivateChannel
• IntentHandler
• DesktopAgent.addIntentListener
• IntentResolution

Listener

A Listener object is returned when an application subscribes to intents or context broadcasts via the addIntentListener, addContextListener or addEventListener on the DesktopAgent object or (PrivateChannel#addeventlistener) on the PrivateChannel object.

TypeScript/JavaScript

interface Listener {
  unsubscribe(): Promise<void>;
}

.NET

interface IListener
{
    void Unsubscribe();
}

unsubscribe

TypeScript/JavaScript

unsubscribe(): Promise<void>;

.NET

void Unsubscribe();

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

See also:

• DesktopAgent.addIntentListener
• DesktopAgent.addContextListener
• Channel.addContextListener
• ContextHandler