AboutSupportDeveloper GuideVersion 38.126.83.79

Object representing a private context channel, which is intended to support secure communication between applications, and extends the Channel interface with event handlers which provide information on the connection state of both parties, ensuring that desktop agents do not need to queue or retain messages that are broadcast before a context listener is added and that applications are able to stop broadcasting messages when the other party has disconnected.

It is intended that Desktop Agent implementations:

  • SHOULD restrict external apps from listening or publishing on this channel.
  • MUST prevent private channels from being retrieved via fdc3.getOrCreateChannel.
  • MUST provide the id value for the channel as required by the Channel interface.
interface PrivateChannel {
    displayMetadata?: OpenFin.FDC3.v2_0.DisplayMetadata;
    id: string;
    type: "user" | "app" | "private";
    addContextListener(contextType, handler): Promise<OpenFin.FDC3.v2_0.Listener>;
    addContextListener(handler): Promise<OpenFin.FDC3.v2_0.Listener>;
    broadcast(context): Promise<void>;
    disconnect(): void;
    getCurrentContext(contextType?): Promise<null | OpenFin.FDC3.v2_0.Context>;
    onAddContextListener(handler): OpenFin.FDC3.v2_0.Listener;
    onDisconnect(handler): OpenFin.FDC3.v2_0.Listener;
    onUnsubscribe(handler): OpenFin.FDC3.v2_0.Listener;
}

Hierarchy (view full)

Properties

displayMetadata?: OpenFin.FDC3.v2_0.DisplayMetadata

Channels may be visualized and selectable by users. DisplayMetadata may be used to provide hints on how to see them. For App channels, displayMetadata would typically not be present.

id: string

Constant that uniquely identifies this channel.

type: "user" | "app" | "private"

Uniquely defines each channel type. Can be "user", "app" or "private".

Methods

  • Adds a listener for incoming contexts of the specified context type whenever a broadcast happens on this channel.

    If, when this function is called, the channel already contains context that would be passed to the listener it is NOT called or passed this context automatically (this behavior differs from that of the fdc3.addContextListener function). Apps wishing to access to the current context of the channel should instead call the getCurrentContext(contextType) function.

    Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the desktop agent implementation.

    Parameters

    Returns Promise<OpenFin.FDC3.v2_0.Listener>

  • Parameters

    Returns Promise<OpenFin.FDC3.v2_0.Listener>

    Deprecated

    use addContextListener(null, handler) instead of addContextListener(handler).

  • Broadcasts a context on the channel. This function can be used without first joining the channel, allowing applications to broadcast on both App Channels and User Channels that they aren't a member of.

    If the broadcast is denied by the channel or the channel is not available, the promise will be rejected with an Error with a message string from the ChannelError enumeration.

    Channel implementations should ensure that context messages broadcast by an application on a channel should not be delivered back to that same application if they are joined to the channel.

    If you are working with complex context types composed of other simpler types (as recommended by the FDC3 Context Data specification) then you should broadcast each individual type (starting with the simpler types, followed by the complex type) that you want other apps to be able to respond to. Doing so allows applications to filter the context types they receive by adding listeners for specific context types.

    If an application attempts to broadcast an invalid context argument the Promise returned by this function should reject with the ChannelError.MalformedContext error.

    Parameters

    Returns Promise<void>

  • May be called to indicate that a participant will no longer interact with this channel.

    After this function has been called, Desktop Agents SHOULD prevent apps from broadcasting on this channel and MUST automatically call Listener.unsubscribe() for each listener that they've added (causing any onUnsubscribe handler added by the other party to be called) before triggering any onDisconnect handler added by the other party.

    Returns void

  • When a contextType_is provided, the most recent context matching the type will be returned, ornull` if no matching context is found.

    If no contextType is provided, the most recent context that was broadcast on the channel - regardless of type - will be returned. If no context has been set on the channel, it will return null.

    It is up to the specific Desktop Agent implementation whether and how recent contexts are stored. For example, an implementation could store context history for a channel in a single array and search through the array for the last context matching a provided type, or context could be maintained as a dictionary keyed by context types. An implementation could also choose not to support context history, in which case this method will return null for any context type not matching the type of the most recent context.

    If getting the current context fails, the promise will be rejected with an Error with a message string from the ChannelError enumeration.

    Parameters

    • Optional contextType: string

    Returns Promise<null | OpenFin.FDC3.v2_0.Context>

  • Adds a listener that will be called each time that the remote app invokes addContextListener on this channel.

    Desktop Agents MUST call this for each invocation of addContextListener on this channel, including those that occurred before this handler was registered (to prevent race conditions).

    Parameters

    • handler: ((contextType?) => void)
        • (contextType?): void
        • Parameters

          • Optional contextType: string

          Returns void

    Returns OpenFin.FDC3.v2_0.Listener

  • Adds a listener that will be called when the remote app terminates, for example when its window is closed or because disconnect was called. This is in addition to calls that will be made to onUnsubscribe listeners.

    Parameters

    • handler: (() => void)
        • (): void
        • Returns void

    Returns OpenFin.FDC3.v2_0.Listener

  • Adds a listener that will be called whenever the remote app invokes Listener.unsubscribe() on a context listener that it previously added.

    Desktop Agents MUST call this when disconnect() is called by the other party, for each listener that they have added.

    Parameters

    • handler: ((contextType?) => void)
        • (contextType?): void
        • Parameters

          • Optional contextType: string

          Returns void

    Returns OpenFin.FDC3.v2_0.Listener