AboutSupportDeveloper GuideVersion 38.126.83.79

The Channel API allows an OpenFin application to create a channel as a ChannelProvider, or connect to a channel as a ChannelClient.

Remarks

The "handshake" between the communication partners is simplified when using a channel. A request to connect to a channel as a client will return a promise that resolves if/when the channel has been created. Both the provider and client can dispatch actions that have been registered on their opposites, and dispatch returns a promise that resolves with a payload from the other communication participant. There can be only one provider per channel, but many clients. Version 9.61.35.* or later is required for both communication partners.

Asynchronous Methods:

Hierarchy

  • EmitterBase<ChannelEvent>
    • Channel

Accessors

  • get me(): Identity
  • Provides access to the OpenFin representation of the current code context (usually a document such as a OpenFin.View or OpenFin.Window), as well as to the current Interop context.

    Useful for debugging in the devtools console, where this will intelligently type itself based on the context in which the devtools panel was opened.

    Returns Identity

Methods

  • Connect to a channel. If you wish to send a payload to the provider, add a payload property to the options argument. EXPERIMENTAL: pass { protocols: ['rtc'] } as options to opt-in to High Throughput Channels.

    Parameters

    Returns Promise<ChannelClient>

    Returns a promise that resolves with an instance of ChannelClient.

    Remarks

    The connection request will be routed to the channelProvider if/when the channel is created. If the connect request is sent prior to creation, the promise will not resolve or reject until the channel is created by a channelProvider (whether or not to wait for creation is configurable in the connectOptions).

    The connect call returns a promise that will resolve with a channelClient bus if accepted by the channelProvider, or reject if the channelProvider throws an error to reject the connection. This bus can communicate with the Provider, but not to other clients on the channel. Using the bus, the channelClient can register actions and middleware. Channel lifecycle can also be handled with an onDisconnection listener.

    Example

    async function makeClient(channelName) {
    // A payload can be sent along with channel connection requests to help with authentication
    const connectPayload = { payload: 'token' };

    // If the channel has been created this request will be sent to the provider. If not, the
    // promise will not be resolved or rejected until the channel has been created.
    const clientBus = await fin.InterApplicationBus.Channel.connect(channelName, connectPayload);

    clientBus.onDisconnection(channelInfo => {
    // handle the channel lifecycle here - we can connect again which will return a promise
    // that will resolve if/when the channel is re-created.
    makeClient(channelInfo.channelName);
    })

    clientBus.register('topic', (payload, identity) => {
    // register a callback for a topic to which the channel provider can dispatch an action
    console.log('Action dispatched by provider: ', JSON.stringify(identity));
    console.log('Payload sent in dispatch: ', JSON.stringify(payload));
    return {
    echo: payload
    };
    });
    }

    makeClient('channelName')
    .then(() => console.log('Connected'))
    .catch(console.error);
  • Create a new channel. You must provide a unique channelName. If a channelName is not provided, or it is not unique, the creation will fail. EXPERIMENTAL: pass { protocols: ['rtc'] } as options to opt-in to High Throughput Channels.

    Parameters

    • channelName: string

      Name of the channel to be created.

    • Optional options: ChannelCreateOptions

      Creation options.

    Returns Promise<ChannelProvider>

    Returns a promise that resolves with an instance of ChannelProvider.

    Remarks

    If successful, the create method returns a promise that resolves to an instance of the channelProvider bus. The caller then becomes the “channel provider” and can use the channelProvider bus to register actions and middleware.

    The caller can also set an onConnection and/or onDisconnection listener that will execute on any new channel connection/disconnection attempt from a channel client. To reject a connection, simply throw an error in the onConnection listener. The default behavior is to accept all new connections.

    A map of client connections is updated automatically on client connection and disconnection and saved in the [read-only] connections property on the channelProvider bus. The channel will exist until the provider destroys it or disconnects by closing or destroying the context (navigating or reloading). To setup a channel as a channelProvider, call Channel.create with a unique channel name. A map of client connections is updated automatically on client connection and disconnection.

    Example

    (async ()=> {
    // entity creates a channel and becomes the channelProvider
    const providerBus = await fin.InterApplicationBus.Channel.create('channelName');

    providerBus.onConnection((identity, payload) => {
    // can reject a connection here by throwing an error
    console.log('Client connection request identity: ', JSON.stringify(identity));
    console.log('Client connection request payload: ', JSON.stringify(payload));
    });

    providerBus.register('topic', (payload, identity) => {
    // register a callback for a 'topic' to which clients can dispatch an action
    console.log('Action dispatched by client: ', JSON.stringify(identity));
    console.log('Payload sent in dispatch: ', JSON.stringify(payload));
    return {
    echo: payload
    };
    });
    })();
  • Returns (string | symbol)[]

  • Parameters

    • type: string | symbol

    Returns number

  • Parameters

    • type: string | symbol

    Returns Function[]

  • Listens for channel connections.

    Parameters

    • listener: ((...args) => void)

      callback to execute.

        • (...args): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns Promise<void>

    Example

    const listener = (channelPayload) => console.log(channelPayload); // see return value below

    fin.InterApplicationBus.Channel.onChannelConnect(listener);

    // example shape
    {
    "topic": "channel",
    "type": "connected",
    "uuid": "OpenfinPOC",
    "name": "OpenfinPOC",
    "channelName": "counter",
    "channelId": "OpenfinPOC/OpenfinPOC/counter"
    }
  • Listen for channel disconnections.

    Parameters

    • listener: ((...args) => void)

      callback to execute.

        • (...args): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns Promise<void>

    Example

    const listener = (channelPayload) => console.log(channelPayload); // see return value below

    fin.InterApplicationBus.Channel.onChannelDisconnect(listener);

    // example shape
    {
    "topic": "channel",
    "type": "disconnected",
    "uuid": "OpenfinPOC",
    "name": "OpenfinPOC",
    "channelName": "counter",
    "channelId": "OpenfinPOC/OpenfinPOC/counter"
    }
  • Adds a one time listener for the event. The listener is invoked only the first time the event is fired, after which it is removed.

    Type Parameters

    • EventType extends "connected" | "disconnected"

    Parameters

    Returns Promise<OpenFin.Channel>

    Remarks

    Event payloads are documented in the OpenFin.Events namespace.

  • Adds a one time listener for the event. The listener is invoked only the first time the event is fired, after which it is removed. The listener is added to the beginning of the listeners array.

    Type Parameters

    • EventType extends "connected" | "disconnected"

    Parameters

    Returns Promise<OpenFin.Channel>

    Remarks

    Event payloads are documented in the OpenFin.Events namespace.

  • Removes all listeners, or those of the specified event.

    Parameters

    • Optional eventType: "connected" | "disconnected"

    Returns Promise<OpenFin.Channel>

  • Remove a listener from the listener array for the specified event.

    Type Parameters

    • EventType extends "connected" | "disconnected"

    Parameters

    Returns Promise<OpenFin.Channel>

    Remarks

    Caution: Calling this method changes the array indices in the listener array behind the listener.