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
}

Java

// Java uses FDC3Event directly instead of a separate ApiEvent interface
// See FDC3Event below

See also:

• FDC3Event
• PrivateChannelEvent

EventHandler

TypeScript/JavaScript

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

.NET

public delegate void Fdc3EventHandler(IFdc3Event fdc3Event);

Go

type EventHandler func(ApiEvent)

Java

@FunctionalInterface
public interface EventHandler {
    void handleEvent(FDC3Event event);
}

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"
)

Java

// Event types are defined as FDC3Event.Type enum
public enum Type {
    ADD_CONTEXT_LISTENER("addContextListener"),
    ON_UNSUBSCRIBE("onUnsubscribe"),
    ON_DISCONNECT("onDisconnect"),
    USER_CHANNEL_CHANGED("userChannelChanged");
    
    private final String value;
    Type(String value) { this.value = value; }
    public String getValue() { return value; }
}

Type defining valid type strings for DesktopAgent interface events.

See also:

• DesktopAgent.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
}

Java

public class FDC3Event {
   
    private final Type type;
    private final Object details;
    
    public FDC3Event(Type type, Object details) {
        this.type = type;
        this.details = details;
    }
    
    public Type getType() { return type; }
    public Object getDetails() { return details; }
}

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
}

Java

// Received as FDC3Event with type USER_CHANNEL_CHANGED
desktopAgent.addEventListener("userChannelChanged", event -> {
    if (event.getType() == FDC3Event.Type.USER_CHANNEL_CHANGED) {
        Map<String, Object> details = (Map<String, Object>) event.getDetails();
        String currentChannelId = (String) details.get("currentChannelId");
    }
});

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.

FDC3ContextClearedEvent

TypeScript/JavaScript

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

.NET

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

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

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

Java

// Received as FDC3Event - contextCleared not yet in FDC3Event.Type enum
desktopAgent.addEventListener("contextCleared", event -> {
    Map<String, Object> details = (Map<String, Object>) event.getDetails();
    String contextType = (String) details.get("type");
});

Type representing the format of contextCleared events.

The specific type of context is defined in the contextType field, which can be empty if we are clearing all the contexts on the channel.

PrivateChannelEventTypes

TypeScript/JavaScript

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

.NET

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

Go

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

Java

// Private channel event types are defined in FDC3Event.Type enum:
// ADD_CONTEXT_LISTENER, ON_UNSUBSCRIBE, ON_DISCONNECT

Type defining valid type strings for Private Channel 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
}

Java

// PrivateChannel events are received as FDC3Event objects
privateChannel.addEventListener("addContextListener", event -> {
    // event.getType() returns FDC3Event.Type.ADD_CONTEXT_LISTENER
    Map<String, Object> details = (Map<String, Object>) event.getDetails();
    String contextType = (String) details.get("contextType");
});

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

See also:

• PrivateChannel.addEventListener
• PrivateChannelEventTypes

PrivateChannelAddContextListenerEvent

TypeScript/JavaScript

interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent {
  readonly type: "addContextListener";
  readonly details: {
    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
}

Java

// Received as FDC3Event with type ADD_CONTEXT_LISTENER
privateChannel.addEventListener("addContextListener", event -> {
    Map<String, Object> details = (Map<String, Object>) event.getDetails();
    String contextType = (String) details.get("contextType"); // may be null
});

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

TypeScript/JavaScript

interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent {
  readonly type: "unsubscribe";
  readonly details: {
    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
}

Java

// Received as FDC3Event with type ON_UNSUBSCRIBE
privateChannel.addEventListener("unsubscribe", event -> {
    Map<String, Object> details = (Map<String, Object>) event.getDetails();
    String contextType = (String) details.get("contextType"); // may be null
});

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

TypeScript/JavaScript

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

.NET

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

Go

type PrivateChannelDisconnectEvent struct {
  PrivateChannelEvent
}

Java

// Received as FDC3Event with type ON_DISCONNECT
privateChannel.addEventListener("disconnect", event -> {
    // No details for disconnect events
});

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.