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.

TypeScript/JavaScript

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

.NET

Not implemented, as ApiEvent and Fdc3Event definitions are the same, given .NET can not restrict on a string enum. Use IFdc3Event instead

Go

type ApiEvent struct {
  Type string 
  Details any
}

See also:

• FDC3Event
• PrivateChannelEvent

EventHandler

TypeScript/JavaScript

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

.NET

public delegate void Fdc3EventHandler(IFdc3Event fdc3Event);

Go

type EventHandler func(ApiEvent)

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

TypeScript/JavaScript

type FDC3EventTypes = "userChannelChanged" | "contextCleared";

.NET

public static class Fdc3EventType
{
    public const string UserChannelChanged = "userChannelChanged";
    public const string ContextCleared = "contextCleared";
}

Go

type FDC3EventTypes string

const (
	UserChannelChanged     FDC3EventTypes = "userChannelChanged"
	ContextCleared         FDC3EventTypes = "contextCleared"
)

Type defining valid type strings for DesktopAgent interface events.

See also:

• DesktopAgent.addEventListener

ChannelEventTypes

TypeScript/JavaScript

type ChannelEventTypes = "contextCleared";

.NET

public static class ChannelEventType
{
    public const string ContextCleared = "contextCleared";
}

Go

type ChannelEventTypes string

const (
  ContextClearedChannelEventType ChannelEventTypes = "contextCleared"
)

Type defining valid type strings for Channel interface events.

See also:

• Channel.addEventListener

FDC3Event

TypeScript/JavaScript

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

.NET

public interface IFdc3Event
{
    public string Type { get; }
    public object? Details { get; }
}

public class Fdc3Event : IFdc3Event
{
    public string Type { get; }
    public object? Details { get; }

    public Fdc3Event(string type, object? details = null)
    {
        this.Type = type ?? throw new ArgumentNullException(nameof(type));
        this.Details = details;
    }
}

Go

type FDC3Event struct {
  ApiEvent
  Type FDC3EventTypes
}

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

TypeScript/JavaScript

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

.NET

public interface IFdc3ChannelChangedEventDetails
{
    string? CurrentChannelId { get; }
}
public class Fdc3ChannelChangedEventDetails : IFdc3ChannelChangedEventDetails
{
    public string? CurrentChannelId { get; }

    public Fdc3ChannelChangedEventDetails(string? channelId)
    {
        this.CurrentChannelId = channelId;
    }
}

public class Fdc3ChannelChangedEvent : Fdc3Event
{
    public Fdc3ChannelChangedEvent(string? channelId)
        : base(Fdc3EventType.UserChannelChanged, new Fdc3ChannelChangedEventDetails(channelId))
    {
    }
}

Go

type FDC3ChannelChangedEvent struct {
  FDC3Event
  Details FDC3ChannelChangedEventDetails
}

type FDC3ChannelChangedEventDetails struct {
  currentChannelId *string
}

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.

Desktop Agents MUST emit this event after applying a User channel membership change when the app has registered a matching event listener. When the app initiated the change by calling joinUserChannel, the event MUST be dispatched before the returned promise resolves.

FDC3ContextClearedEvent

TypeScript/JavaScript

export interface FDC3ContextClearedEvent extends FDC3Event {
  readonly type: 'contextCleared';
  readonly details: {
    channelId: string;
    contextType: string | null;
  };
}

.NET

public interface IFdc3ContextClearedEventDetails
{
    string ChannelId { get; }
    string? ContextType { get; }
}
public class Fdc3ContextClearedEventDetails : IFdc3ContextClearedEventDetails
{
    public string ChannelId { get; }
    public string? ContextType { get; }

    public Fdc3ContextClearedEventDetails(string channelId, string? contextType)
    {
        this.ChannelId = channelId;
        this.ContextType = contextType;
    }
}

public class Fdc3ContextClearedEvent : Fdc3Event
{
    public Fdc3ContextClearedEvent(string channelId, string? contextType)
        : base(Fdc3EventType.ContextCleared, new Fdc3ContextClearedEventDetails(channelId, contextType))
    {
    }
}

Go

type FDC3ContextClearedEventDetails struct {
  Type *string `json:"type"`
}

type FDC3ContextClearedEvent struct {
  Type   string                        `json:"type"`
  Details FDC3ContextClearedEventDetails `json:"details"`
}

Type representing the format of contextCleared events.

The channel on which context was cleared is identified by details.channelId. This field is included for events received through both DesktopAgent.addEventListener and Channel.addEventListener, allowing the same event handler to be used with either API.

The specific type of context is defined in details.contextType, which will be null if all contexts on the channel were cleared.

PrivateChannelEventTypes

TypeScript/JavaScript

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

.NET

public static class Fdc3PrivateChannelEventType
{
    public const string ContextCleared = "contextCleared";
    public const string AddContextListener = "addContextListener";
    public const string Unsubscribe = "unsubscribe";
    public const string Disconnect = "disconnect";
}

Go

type PrivateChannelEventTypes string 
const (
  ContextClearedPrivateChannelEventType PrivateChannelEventTypes = "contextCleared"
  AddContextListenerPrivateChannelEventType PrivateChannelEventTypes = "addContextListener"
  UnsubscribePrivateChannelEventType PrivateChannelEventTypes = "unsubscribe"
  DisconnectPrivateChannelEventType PrivateChannelEventTypes = "disconnect"
)

Type defining valid type strings for Private Channel events. Private Channels support the contextCleared event defined by ChannelEventTypes, in addition to their lifecycle events.

See also:

• PrivateChannel.addEventListener

PrivateChannelEvent

TypeScript/JavaScript

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

.NET

public interface IFdc3PrivateChannelEventDetails
{
    string? ContextType { get; }
}
public class Fdc3PrivateChannelEventDetails : IFdc3PrivateChannelEventDetails
{
    public string? ContextType { get; }

    public Fdc3PrivateChannelEventDetails(string? contextType)
    {
        this.ContextType = contextType;
    }
}

Go

type PrivateChannelEvent struct {
  ApiEvent
  Type PrivateChannelEventTypes
}

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

All PrivateChannel events identify the channel to which they relate through details.channelId. The corresponding DACP event payloads use the field name privateChannelId; Desktop Agent API implementations expose that value as channelId for consistency with other channel-related events.

See also:

• PrivateChannel.addEventListener
• PrivateChannelEventTypes

PrivateChannelAddContextListenerEvent

TypeScript/JavaScript

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

.NET

public class Fdc3PrivateChannelAddContextListenerEvent : Fdc3Event
{
    public Fdc3PrivateChannelAddContextListenerEvent(string? contextType)
        : base(Fdc3PrivateChannelEventType.AddContextListener, new Fdc3PrivateChannelEventDetails(contextType))
  {
  }
}

Go

type PrivateChannelAddContextListenerEvent struct {
  PrivateChannelEvent
  Details PrivateChannelAddContextListenerEventDetails
}

type PrivateChannelAddContextListenerEventDetails struct {
  contextType *string
}

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 channel is identified by details.channelId. 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

TypeScript/JavaScript

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

.NET

public class Fdc3PrivateChannelUnsubscribeListenerEvent : Fdc3Event
{
    public Fdc3PrivateChannelUnsubscribeListenerEvent(string? contextType)
            : base(Fdc3PrivateChannelEventType.Unsubscribe, new Fdc3PrivateChannelEventDetails(contextType))
    {
    }
}

Go

type PrivateChannelUnsubscribeEvent struct {
  PrivateChannelEvent
  Details PrivateChannelUnsubscribeEventDetails
}

type PrivateChannelUnsubscribeEventDetails struct {
  contextType *string
}

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 channel is identified by details.channelId. 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

TypeScript/JavaScript

export interface PrivateChannelDisconnectEvent extends PrivateChannelEvent {
  readonly type: "disconnect";
  readonly details: {
    channelId: string;
  };
}

.NET

public class Fdc3PrivateChanneDisconnectEvent : Fdc3Event
{
    public Fdc3PrivateChanneDisconnectEvent()
        : base(Fdc3PrivateChannelEventType.Disconnect)
    {
    }
}

Go

type PrivateChannelDisconnectEvent struct {
  PrivateChannelEvent
}

Type defining the format of events representing a remote app being terminated or 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. The channel is identified by details.channelId.