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.

An AppIdentifier will always include at least an appId property, which can be used with fdc3.open, fdc3.raiseIntent etc.. An appId is intended to reference a specific record from an App Directory, which it uniquely identifies within that App Directory.

The appId may be unqualified or fully-qualified as described in the API overview and App Directory Parts of the Standard and may be resolved and used interchangeably as described in the API overview.

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

Go

type AppIdentifier struct {
  // The unique application identifier located within a specific application directory instance. An example of an appId might be 'app@sub.root'.
  AppId      string `json:"appId"`
  // An optional instance identifier, indicating that this object represents a specific instance of the application described.
  InstanceId string `json:"instanceId"`
}

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

Go

type Context struct {
  Type    string                 `json:"type"`
  Name    string                 `json:"name"`
  Id      map[string]string      `json:"id"`
}

type IContext interface {
  // TODO: include at least one method in here 
}

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

ContextWithMetadata

TypeScript/JavaScript

type ContextWithMetadata = {
  context: Context;
  metadata: ContextMetadata;
};

.NET

interface IContextWithMetadata
{
    IContext Context { get; }
    IContextMetadata Metadata { get; }
}

Go

type ContextWithMetadata struct {
  Context  Context         `json:"context"`
  Metadata ContextMetadata `json:"metadata"`
}

Represents a context object paired with its associated metadata. Returned by Channel.getCurrentContextWithMetadata() to allow retrieval of both the current context and the ContextMetadata that was provided when it was broadcast. May also be returned by an IntentHandler to include app-provided metadata alongside a context result, which will be merged with Desktop Agent generated metadata and made available to the raising app via IntentResolution.getResultMetadata().

See also:

• Context
• ContextMetadata
• Channel.getCurrentContextWithMetadata
• IntentHandler
• IntentResolution.getResultMetadata

ContextHandler

TypeScript/JavaScript

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

.NET

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

Go

type ContextHandler func(IContext, *ContextMetadata)

Describes a callback that handles a context event. Used when attaching listeners for context broadcasts.

Metadata about each context message received, including the app that originated the message and a timestamp, MUST be provided by the Desktop Agent implementation. Apps raising intents MAY provide additional metadata (such as a traceId, signature or custom metadata), which the Desktop Agent MUST pass on to the handler.

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

Go

type DesktopAgentIdentifier struct {
  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:

• Agent Bridging - Identifying Desktop Agents Identity and Message Sources

IntentHandler

TypeScript/JavaScript

type IntentHandler = (
  context: Context,
  metadata: ContextMetadata
) => Promise<Context | ContextWithMetadata | Channel | PrivateChannel | void> | void;

.NET

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

Go

type IntentHandler func(IContext, *ContextMetadata) <-chan IntentResult

Describes a callback that handles a context event and may return a promise of a Context, ContextWithMetadata, Channel, PrivateChannel or void to be returned to the application that raised the intent. Used when attaching listeners for raised intents.

Metadata about each intent & context message received, including the app that originated the message and a timestamp, MUST be provided by the Desktop Agent implementation. Apps raising intents MAY provide additional metadata (such as a traceId, signature or custom metadata), which the Desktop Agent MUST pass on to the handler.

An IntentHandler MAY return a ContextWithMetadata object instead of a plain Context to include app-provided metadata (e.g. a traceId or signature) alongside the context result. The Desktop Agent will merge this with its own generated metadata and make the combined ContextMetadata available to the raising app via IntentResolution.getResultMetadata(). IntentResolution.getResult() will still return only the Context portion.

See also:

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

IntentResult

TypeScript/JavaScript

type IntentResult = Context | Channel | void;

.NET

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

Go

type IntentResult any

type IntentResultType string
const (
  ChannelIntentResult        IntentResultType = "Channel"
  ContextIntentResult        IntentResultType = "Context"
  PrivateChannelIntentResult IntentResultType = "PrivateChannel"
)

Describes results returned by IntentResolution.getResult() after an intent is resolved. Note that IntentHandler functions may also return ContextWithMetadata to include app-provided metadata alongside a context result; in that case getResult() still returns only the Context portion, while the metadata is available via IntentResolution.getResultMetadata().

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
• ContextWithMetadata
• 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
{
    Task Unsubscribe();
}

Go

type IListener interface {
  Unsubscribe()
}
type Listener struct {}

unsubscribe

TypeScript/JavaScript

unsubscribe(): Promise<void>;

.NET

Task Unsubscribe();

Go

func (l *Listener) Unsubscribe() {
  // Implementation here
}

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

See also:

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