Events.md

title	Events

In addition to intent and context events, the FDC3 API and PrivateChannel API may be used to listen for other types of events via their addEventListener() functions.

ApiEvent

Type defining a basic event object that may be emitted by an FDC3 API interface such as DesktopAgent or PrivateChannel. There are more specific event types defined for each interface.

interface ApiEvent {
  readonly type: string;
  readonly details: any;
}

interface IApiEvent
{
  string Type { get; }
  string Details { get; }
}

See also:

• FDC3Event
• PrivateChannelEvent

EventHandler

type EventHandler = (event: ApiEvent) => void;

delegate void EventHandler<T>(T event) where T : IApiEvent;

Describes a callback that handles non-context and non-intent events. Provides the details of the event.

Used when attaching listeners to events.

See also:

• DesktopAgent.addEventListener
• PrivateChannel.addEventListener
• ApiEvent

FDC3EventTypes

type FDC3EventTypes = "userChannelChanged";

enum FDC3EventType 
{
  UserChannelChanged
}

Type defining valid type strings for DesktopAgent interface events.

See also:

• DesktopAgent.addEventListener

FDC3Event

interface FDC3Event extends ApiEvent{
  readonly type: FDC3EventTypes;
  readonly details: any;
}

interface IFDC3Event<T> : IApiEvent
{
  FDC3EventType Type { get; }
  T Details { get; }
}

Type representing the format of event objects that may be received via the FDC3 API's addEventListener function.

Events will always include both type and details properties, which describe the type of the event and any additional details respectively.

See also:

• DesktopAgent.addEventListener
• FDC3EventTypes

FDC3ChannelChangedEvent

interface FDC3ChannelChangedEvent extends FDC3Event {
  readonly type: "userChannelChanged";
  readonly details: {
    currentChannelId: string | null
  };
}

class Details 
{
  string? CurrentChannelId { get; }
}

interface IFDC3ChannelChangedEvent : IFDC3Event
{
  FDC3EventType Type { get; }
  Details Details { get; } // TODO 
}

Type representing the format of userChannelChanged events.

The identity of the channel joined is provided as details.currentChannelId, which will be null if the app is no longer joined to any channel.

PrivateChannelEventTypes

type PrivateChannelEventTypes = "addContextListener" | "unsubscribe" | "disconnect";

enum PrivateChannelEventType
{
  AddContextListener, 
  Unsubscribe,
  Disconnect
}

Type defining valid type strings for Private Channel events.

See also:

• PrivateChannel.addEventListener

PrivateChannelEvent

interface PrivateChannelEvent extends ApiEvent {
  readonly type: PrivateChannelEventTypes;
  readonly details: any;
}

interface IPrivateChannelEvent<T> : IApiEvent
{
  PrivateChannelEventType Type { get; }
  T Details { get; }
}

Type defining the format of event objects that may be received via a PrivateChannel's addEventListener function.

See also:

• PrivateChannel.addEventListener
• PrivateChannelEventTypes

PrivateChannelAddContextListenerEvent

interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent {
  readonly type: "addContextListener";
  readonly details: {
    contextType: string | null
  };
}

class Details 
{
  string? ContextType { get; }
}

interface IPrivateChannelAddContextListenerEvent : IPrivateChannelEvent
{
  PrivateChannelEventType Type { get; }
  Details Details { get; }
}

Type defining the format of events representing a context listener being added to the channel (addContextListener). Desktop Agents MUST fire this event for each invocation of addContextListener on the channel, including those that occurred before this handler was registered (to prevent race conditions).

The context type of the listener added is provided as details.contextType, which will be null if all event types are being listened to.

PrivateChannelUnsubscribeEvent

interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent {
  readonly type: "unsubscribe";
  readonly details: {
    contextType: string | null
  };
}

class Details 
{
  string? ContextType { get; }
}

interface IPrivateChannelUnsubscribeEvent : IPrivateChannelEvent
{
  PrivateChannelEventType Type { get; }
  Details Details { get; } 
}

Type defining the format of events representing a context listener removed from the channel (Listener.unsubscribe()). Desktop Agents MUST call this when disconnect() is called by the other party, for each listener that they had added.

The context type of the listener removed is provided as details.contextType, which will be null if all event types were being listened to.

PrivateChannelDisconnectEvent

export interface PrivateChannelDisconnectEvent extends PrivateChannelEvent {
  readonly type: "disconnect";
  readonly details: null | undefined;
}

public interface IPrivateChannelDisconnectEvent : IPrivateChannelEvent {
  PrivateChannelEventType Type { get; }
}

Type defining the format of events representing a remote app being terminated or is otherwise disconnecting from the PrivateChannel. This event is fired in addition to unsubscribe events that will also be fired for any context listeners the disconnecting app had added.

No details are provided.